# 查看算子 API 服务配置

查看指定算子版本是否已发布，以及调用该服务所需的名称、状态和输入定义。

```text
GET https://moi.matrixorigin.cn/newmoi/workflow/v2/workitems/catalog/$NODE_ID/api-service?version=$VERSION
```

## 调用前准备

先[查看算子列表](../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 | 是 | 算子版本。 |

## 请求示例

```bash
curl "https://moi.matrixorigin.cn/newmoi/workflow/v2/workitems/catalog/$NODE_ID/api-service?version=$VERSION" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

## 成功响应

响应返回服务配置。确认服务已启用后才能[调用服务](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",
      "input_schema": "{\"type\":\"object\",\"properties\":{\"sql\":{\"type\":\"string\"}}}"
    }
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `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 | `unpublished` 表示尚未发布，`ready` 表示可以调用，`disabled` 表示已停用。 |
| `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.input_schema` | string | 输入数据定义。按其中字段和类型填写调用请求的 `payload`。 |
| `data.service.output_schema` | string | 输出数据定义；有值时返回。 |
| `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.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` 缺失。
  - 检查路径和查询参数。
* - `401`
  - `ErrUnauthorized`
  - 个人访问令牌缺失或无效。
  - 检查个人访问令牌和工作区 ID。
* - `403`
  - `ErrForbidden`
  - 当前访问凭据没有读取服务配置的权限。
  - 使用有权限的访问凭据，或联系管理员授权。
* - `404`
  - `ErrNotFound`
  - 算子或对应服务不存在。
  - 检查算子 ID 和版本。
* - `500`
  - `ErrServer`
  - 服务端无法读取服务配置。
  - 记录请求时间和错误信息后重试。
* - `503`
  - `ErrServiceUnavailable`
  - 服务依赖暂不可用。
  - 稍后重试。
```

## 后续操作

需要变更发布内容时[发布算子 API 服务](publish-operator-api-service.md)；需要停用时[停用算子 API 服务](disable-operator-api-service.md)。