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¶
Complete the endpoint, personal access token, and workspace setup in Use the SDK.
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.
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¶
Publish Workflow API Services (publish a full workflow as a dynamic service bound to an interactive page)