# 管理 WorkItem 服务

使用 AI Studio SDK 管理指定 WorkItem 节点和版本的 API 服务。服务的发布、启用、调用、状态查询和停用均绑定同一节点 ID 与版本号。

(sdk-ai-studio-workitem-api-service-flow)=
## 任务流程

先按节点 ID 和版本号获取服务句柄，再提交发布配置并启用服务；启用后可发起业务调用，不再对外提供服务时停用并回读服务状态确认已生效。

```text
节点 ID + 版本 + 计算资源 ID
             │
             ▼
       发布并启用服务
             │
             ▼
     发起调用并检查业务状态
             │
             ▼
    停用服务并回读状态确认
```

(sdk-ai-studio-workitem-api-service-prepare)=
## 准备

1. 已完成 [使用 SDK](../../../quickstart/ai-studio/sdk.md) 中的服务地址、个人访问令牌与工作区配置。
2. **节点 ID 与版本号**：使用在 [管理自定义算子与模板](自定义算子和工作流模板.md#sdk-ai-studio-workflow-design-create-operator) 中创建并通过测试的自定义算子节点 ID 与版本，或按 [查看工作流节点定义](查看工作流节点定义.md#sdk-ai-studio-workflow-nodes-s1) 从节点目录查询目标节点 ID 与版本。
3. **计算资源 ID 与调用参数**：按 [管理计算资源](../资源中心/管理计算实例.md) 或 [读取资源清单](../资源中心/读取资源清单.md) 取得目标计算资源 ID，并按算子输入定义准备服务名称、服务类型与非空输入负载。

(sdk-ai-studio-workitem-api-service-publish)=
## 发布并启用服务

以下示例传入计算资源 ID、超时时间、最大并发数和每分钟请求限额发布服务，随后启用该服务。在接入正式业务流量前，先检查返回的服务状态或执行连通性验证。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
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)
```

::::

::::{tab-item} Go
:sync: go

```go
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())
}
```

::::

:::::

(sdk-ai-studio-workitem-api-service-invoke)=
## 调用服务

复用同一服务句柄，传入服务名称、服务类型、版本号和非空业务输入负载。HTTP 请求返回仅表示调用响应已送达，业务执行成败需根据响应对象中的状态、输出内容与错误字段判断。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
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)
```

::::

::::{tab-item} Go
:sync: go

```go
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())
```

::::

:::::

(sdk-ai-studio-workitem-api-service-disable)=
## 停用服务

停止接收外部调用时，停用该服务并重新读取服务详情以确认状态变更已完成。服务句柄仅管理 API 服务的启用与停用状态；底层自定义算子本身的更新或删除按 [管理自定义算子与模板](自定义算子和工作流模板.md) 处理。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

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

print(disabled.service.status)
print(current.service.status)
```

::::

::::{tab-item} Go
:sync: go

```go
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())
```

::::

:::::

(sdk-ai-studio-workitem-api-service-next)=
## 下一步

- [发布工作流 API 服务](发布工作流API服务.md)（将整条工作流发布为动态服务并绑定交互页面）
- [运行并跟踪工作流](运行并跟踪工作流.md)
- [查看工作流产物与血缘](查看工作流产物和数据血缘.md)
