Manage WorkItem Services

Use the AI Studio SDK to manage an API service for a specific WorkItem node and version. Publishing, enabling, invoking, inspecting, and disabling the service all target the same node ID and version.

Task flow

Obtain a service handle for the target node ID and version, publish the service configuration, and enable the service. Once enabled, invoke the service and inspect business execution fields; when retiring access, disable the service and read back its metadata to confirm the state transition.

Node ID + Version + Compute resource ID
                   │
                   ▼
       Publish and enable service
                   │
                   ▼
   Invoke service and inspect status
                   │
                   ▼
  Disable service and verify status

Prerequisites

  1. Complete the endpoint, personal access token, and workspace setup in Use the SDK.

  2. Node ID and version: use the node ID and version of a custom operator created and tested in Manage Custom Operators and Templates, or query the catalog in Inspect Workflow Node Definitions.

  3. Compute resource ID and invocation parameters: obtain a compute resource ID from Manage Compute Resources or Read Resource Inventories, and prepare the service name, service type, and non-empty input payload matching the operator’s input schema.

Publish and enable a service

The example below publishes a service with a compute resource ID, timeout, concurrency limit, and per-minute rate limit, then enables it. Before routing production traffic, inspect the returned service status or run an application readiness check.

import os

import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"],
    os.environ["PRODUCT_API_KEY"],
)
workspace = client.workspace(os.environ["WORKSPACE_ID"])
service = workspace.workitem_api_service("<node-id>", "<version>")
published = service.publish(
    sdk.WorkitemAPIServicePublishSpec(
        version="<version>",
        compute_resource_id="<compute-resource-id>",
        timeout_seconds=30,
        max_concurrency=1,
        rate_limit_per_min=60,
    )
)
enabled = service.enable()

print(published.service.status)
print(enabled.service.status)
package main

import (
	"context"
	"fmt"
	"os"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"),
		os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		panic(err)
	}
	workspace, err := client.Workspace(os.Getenv("WORKSPACE_ID"))
	if err != nil {
		panic(err)
	}
	service, err := workspace.WorkitemAPIService("<node-id>", "<version>")
	if err != nil {
		panic(err)
	}
	published, err := service.Publish(ctx, sdk.WorkitemAPIServicePublishSpec{
		Version:           "<version>",
		ComputeResourceID: "<compute-resource-id>",
		TimeoutSeconds:    30,
		MaxConcurrency:    1,
		RateLimitPerMin:   60,
	})
	if err != nil {
		panic(err)
	}
	enabled, err := service.Enable(ctx)
	if err != nil {
		panic(err)
	}

	fmt.Println(published.GetService().GetStatus())
	fmt.Println(enabled.GetService().GetStatus())
}

Invoke a service

Reuse the same service handle and provide the service name, service type, version, and a non-empty input payload. Receiving an HTTP response means the call completed at the transport layer; check the status, output payload, and error fields inside the returned result to determine business execution outcome.

response = service.invoke(
    sdk.WorkitemAPIServiceInvokeSpec(
        "<service-name>",
        "<service-type>",
        "<version>",
        {"<input-name>": "<input-value>"},
    )
)

print(response.result.status)
print(response.result.result)
print(response.result.error)
response, err := service.Invoke(ctx, sdk.WorkitemAPIServiceInvokeSpec{
	ServiceName: "<service-name>",
	Type:        "<service-type>",
	Version:     "<version>",
	Payload:     map[string]any{"<input-name>": "<input-value>"},
})
if err != nil {
	panic(err)
}

fmt.Println(response.GetResult().GetStatus())
fmt.Println(response.GetResult().GetResult())
fmt.Println(response.GetResult().GetError())

Disable a service

When retiring external invocations, disable the service and read back service details to confirm the updated status. The service handle controls API service enablement only; update or delete the underlying custom operator itself through Manage Custom Operators and Templates.

disabled = service.disable()
current = service.info()

print(disabled.service.status)
print(current.service.status)
disabled, err := service.Disable(ctx)
if err != nil {
	panic(err)
}
current, err := service.Info(ctx)
if err != nil {
	panic(err)
}

fmt.Println(disabled.GetService().GetStatus())
fmt.Println(current.GetService().GetStatus())

Next steps

Last updated on