# 试运行自定义算子

使用给定输入执行一次自定义算子测试，并返回本次测试记录。仅已启用的 Python 代码类型算子可以试运行。

```text
POST https://moi.matrixorigin.cn/newmoi/workflow/v2/custom-operators/$OPERATOR_ID/test-run
```

## 调用前准备

先[查询自定义算子详情](get-custom-operator.md)，确认要测试的算子已启用且为 Python 代码类型。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和自定义算子 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：目标工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$OPERATOR_ID`：要试运行的自定义算子 ID，从[查询自定义算子列表](list-custom-operators.md)响应中取得，并写入请求地址。

## 路径参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `operator_id` | integer | 是 | 要试运行的自定义算子 ID，必须大于 `0`。 |

## 请求体

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `input` | object | 否 | 测试输入；省略时使用空对象。 |
| `wait_timeout_seconds` | integer | 否 | 等待测试结果的秒数。 |

## 请求示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/workflow/v2/custom-operators/$OPERATOR_ID/test-run" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "MatrixOne"
    },
    "wait_timeout_seconds": 30
  }'
```

## 成功响应

响应返回本次测试记录。检查测试状态、输出和错误信息，以确认算子是否按预期运行。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "test_run": {
      "operator_id": 123,
      "node_id": "moi:custom.operator:workspace:text_counter",
      "version": "v1",
      "task_id": "task_01",
      "case_id": "case_01",
      "status": "succeeded",
      "runtime_input": {
        "text": "MatrixOne"
      },
      "runtime_output": {
        "count": 9
      }
    }
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.test_run.operator_id` | integer | 本次测试的自定义算子 ID。 |
| `data.test_run.node_id` | string | 本次测试使用的算子 ID。 |
| `data.test_run.version` | string | 本次测试使用的算子版本。 |
| `data.test_run.task_id` | string | 本次测试任务 ID。 |
| `data.test_run.case_id` | string | 本次测试记录 ID。 |
| `data.test_run.status` | string | 测试运行状态。 |
| `data.test_run.case_result` | string | 测试案例结果；有值时返回。 |
| `data.test_run.runtime_input` | object | 实际输入；有值时返回。 |
| `data.test_run.runtime_output` | object | 实际输出；有值时返回。 |
| `data.test_run.case_error` | string | 测试错误信息；有错误时返回。 |
| `data.test_run.node_detail` | object | 本次测试中算子的执行节点详情；有值时返回。 |
| `data.test_run.node_detail.node.flow_id` | string | 执行节点所属流程。 |
| `data.test_run.node_detail.node.name` | string | 执行节点名称。 |
| `data.test_run.node_detail.node.node_key` | string | 执行节点标识。 |
| `data.test_run.node_detail.node.node_type` | string | 执行节点类型。 |
| `data.test_run.node_detail.node.display_name` | string | 执行节点显示名称。 |
| `data.test_run.node_detail.node.workitem_id` | string | 工作项标识；有值时返回。 |
| `data.test_run.node_detail.node.node_execution_id` | string | 节点执行标识；有值时返回。 |
| `data.test_run.node_detail.run.status` | string | 节点执行状态。 |
| `data.test_run.node_detail.run.started_at` | string | 开始时间；有值时返回。 |
| `data.test_run.node_detail.run.ended_at` | string | 结束时间；有值时返回。 |
| `data.test_run.node_detail.run.error` | string | 执行错误；有值时返回。 |
| `data.test_run.node_detail.run.duration_ms` | integer | 节点执行耗时，单位为毫秒；有值时返回。 |
| `data.test_run.node_detail.run.runtime_input` | object | 节点实际输入。 |
| `data.test_run.node_detail.run.runtime_output` | object | 节点实际输出。 |
| `data.test_run.node_detail.run.config` | object | 节点配置。 |
| `data.test_run.node_detail.run.runtime_vars` | object | 节点运行变量；有值时返回。 |
| `data.test_run.node_detail.run.metrics` | object | 节点运行指标；有值时返回。 |
| `data.test_run.node_detail.run.developer_logs` | object | 节点开发日志；有值时返回。 |
| `data.test_run.developer_logs` | object | 开发日志；服务提供时返回。 |
| `data.test_run.wait_timeout_seconds` | integer | 本次测试等待结果的秒数。 |

## 错误响应

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

### 常见 HTTP 错误

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

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `ErrParamInvalid`
  - 算子 ID 或请求体无效，算子未启用，或算子不是可试运行的 Python 代码类型。
  - 检查算子配置和测试输入。
* - `401`
  - `ErrUnauthorized`
  - 个人访问令牌缺失或无效。
  - 检查个人访问令牌和工作区 ID。
* - `403`
  - `ErrForbidden`
  - 当前身份没有试运行权限。
  - 使用有权限的凭据，或联系管理员授权。
* - `404`
  - `ErrNotFound`
  - 算子不存在。
  - 检查算子 ID。
* - `500`
  - `ErrServer`
  - 服务暂时无法执行测试。
  - 记录错误信息后重试。
* - `503`
  - `ErrServiceUnavailable`
  - 依赖服务暂时不可用。
  - 稍后重试。
```

## 后续操作

完成后[查询自定义算子详情](get-custom-operator.md)确认当前状态。