# 发布算子 API 服务

将指定版本的算子发布为可调用的 API 服务。发布成功后保存服务名称；服务已启用后可以调用。

```text
POST https://moi.matrixorigin.cn/newmoi/workflow/v2/workitems/catalog/$NODE_ID/api-service
```

## 调用前准备

先[查看算子列表](../operator-catalog/list-operators.md)，确认要发布的算子及其版本。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID、算子 ID 和版本。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：目标工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$NODE_ID`：要发布的算子 ID。
- `$VERSION`：要发布的算子版本。

## 路径参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `node_id` | string | 是 | 要发布的算子 ID。可从[查看算子列表](../operator-catalog/list-operators.md)响应中取得。 |

## 请求体

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `version` | string | 是 | 要发布的算子版本。 |
| `compute_resource_id` | string | 否 | 为服务指定计算资源 ID。 |
| `timeout_seconds` | integer | 否 | 单次调用超时时间，单位为秒。不传或传 `0` 时为 `30`，最大值为 `300`。 |
| `max_concurrency` | integer | 否 | 最大并发调用数，不能为负数。 |
| `rate_limit_per_min` | integer | 否 | 每分钟最大调用数，不能为负数。 |

## 请求示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/workflow/v2/workitems/catalog/$NODE_ID/api-service" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d "{
    \"version\": \"$VERSION\",
    \"timeout_seconds\": 30
  }"
```

## 成功响应

响应返回服务标识、状态、调用地址和配置。发布成功后服务可以调用；将返回的服务名称原样用于[调用服务](invoke-operator-api-service.md)。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "service": {
      "api_service_id": "api_2e859efcedc1e0efea48b465b2197784",
      "node_id": "moi:data.sql.process",
      "version": "v1",
      "service_name": "operator-api-37f61ebdaa18aa51",
      "status": "ready",
      "method": "POST",
      "path": "/newmoi/workflow/v2/workitems/catalog/moi:data.sql.process/api-service/invoke",
      "compute_resource_id": ""
    }
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.service.api_service_id` | string | 服务 ID。 |
| `data.service.operator_id` | integer | 已发布的自定义算子 ID。 |
| `data.service.node_id` | string | 已发布的算子 ID。 |
| `data.service.version` | string | 已发布的算子版本。 |
| `data.service.service_name` | string | 服务名称。 |
| `data.service.status` | string | 服务状态。`ready` 表示可以调用。 |
| `data.service.result_mode` | string | 服务的结果返回模式。 |
| `data.service.auth_mode` | string | 服务的认证模式。 |
| `data.service.method` | string | 调用服务使用的 HTTP 方法。 |
| `data.service.path` | string | 调用服务的相对路径。 |
| `data.service.workflow_id` | string | 服务关联的工作流 ID；有值时返回。 |
| `data.service.workflow_def_id` | string | 服务关联的工作流定义 ID；有值时返回。 |
| `data.service.workflow_version_id` | string | 服务关联的工作流版本 ID；有值时返回。 |
| `data.service.compute_resource_id` | string | 使用的计算资源 ID；仅在有值时返回。 |
| `data.service.timeout_seconds` | integer | 单次调用超时时间，单位为秒；有值时返回。 |
| `data.service.max_concurrency` | integer | 最大并发调用数；有值时返回。 |
| `data.service.rate_limit_per_min` | integer | 每分钟最大调用数；有值时返回。 |
| `data.service.input_schema` | string | 输入 schema 的序列化内容；有值时返回。 |
| `data.service.output_schema` | string | 输出 schema 的序列化内容；有值时返回。 |
| `data.service.invoke` | object | 调用服务所需的信息；有值时返回。 |
| `data.service.deployment` | object | 服务部署信息；有值时返回。 |

## 错误响应

```json
{
  "code": "ErrParamInvalid",
  "msg": "请求参数无效",
  "data": null
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 24 36 28

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `ErrParamInvalid`
  - 算子 ID、`version` 或请求体无效；`timeout_seconds` 超过 `300` 秒也会失败。
  - 检查路径参数和请求字段。
* - `401`
  - `ErrUnauthorized`
  - 个人访问令牌缺失或无效。
  - 检查个人访问令牌和工作区 ID。
* - `403`
  - `ErrForbidden`
  - 当前访问凭据没有发布权限，或不能使用指定计算资源。
  - 使用有权限的访问凭据，或联系管理员授权。
* - `404`
  - `ErrNotFound`
  - 算子或版本不存在。
  - 检查算子 ID 和版本。
* - `409`
  - `ErrConflict`
  - 服务配置与已有资源冲突。
  - 先[查看服务配置](get-operator-api-service.md)，再调整请求。
* - `500`
  - `ErrServer`
  - 服务端无法发布服务。
  - 记录请求时间和错误信息后重试。
* - `503`
  - `ErrServiceUnavailable`
  - 服务依赖暂不可用。
  - 稍后重试。
```

## 后续操作

完成后[查看算子 API 服务配置](get-operator-api-service.md)确认当前状态。