# 准备任务测试资源

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

为当前任务准备或复用临时数据库与输入、输出卷。相关对象、变量及环境边界见[公共说明](objects.md)。

```text
POST https://api.moi.matrixorigin.cn/v5/workflow/v2/workflow-test-scratch/ensure
```

## 调用前准备

在当前生成任务执行环境中保留注入的服务地址、凭据、工作区和短期授权。授权头使用完整原值。安装 jq 并设置示例所用变量。

## 请求体

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

```bash
curl -X POST "${MOI_ENDPOINT%/}/workflow/v2/workflow-test-scratch/ensure" \
  -H "X-API-Key: $MOI_API_KEY" \
  -H "X-Workspace-ID: $MOI_WORKSPACE_ID" \
  -H "X-MOI-Runtime-Authorization: $MOI_RUNTIME_AUTHORIZATION" \
  -H 'Content-Type: application/json' \
  --data-binary "$(jq -n  '{}')"
```

:::::
:::::{tab-item} 参数说明

示例在任务环境中由授权派生范围。普通 Product 身份路径仍存在，但必须显式提供并满足 task_id、context_id、effective_role_id 等范围条件，不能把 PAT 视为任务范围的替代品。已有资源的用户、角色和对话绑定须一致；准备资源可能创建数据库和输入、输出卷，不会发布工作流。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `task_id` | string | 任务模式可省略 | 由校验后的任务身份取得；显式值必须一致。 |
| `context_id` | string | 任务模式可省略 | 由校验后的任务身份取得；显式值必须一致。 |
| `effective_role_id` | string | 任务模式可省略 | 由校验后的任务身份取得；显式值必须一致。 |
| `catalog_id` | integer | 否 | 创建资源的 Catalog；0 时解析默认 Catalog，解析后必须为正数。 |

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "workspace_id": "workspace-1",
    "task_id": "task-1",
    "user_id": "user-1",
    "effective_role_id": "role-1",
    "context_id": "context-1",
    "operation_id": "operation-example",
    "catalog_id": 1,
    "database_name": "scratch_example",
    "database_id": 11,
    "input_volume_id": 12,
    "output_volume_id": 13,
    "state": "active"
  }
}
```

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 OK。 |
| `msg` | string | 响应信息。 |
| `data` | object | 本动作结果。 |
| `data.workspace_id` | string | 资源工作区。 |
| `data.task_id` | string | 所属任务。 |
| `data.user_id` | string | 所属用户。 |
| `data.effective_role_id` | string | 有效角色。 |
| `data.context_id` | string | 所属对话。 |
| `data.operation_id` | string | 资源操作标识。 |
| `data.catalog_id` | integer | Catalog ID。 |
| `data.database_name` | string | 测试数据库名称。 |
| `data.database_id` | integer | 测试数据库 ID。 |
| `data.input_volume_id` | integer | 输入卷 ID。 |
| `data.output_volume_id` | integer | 输出卷 ID。 |
| `data.state` | string | 租约状态；示例为 active。 |

:::::
::::::
:::::::

## 错误响应

按 HTTP 状态和业务字段处理。历史查询与恢复另有专用错误代码，见[错误与环境](objects.md#错误与环境)。先保留身份、来源引用和操作标识，核对状态后处理；不自动改换工作区、候选或确认键。
