<span id="准备任务测试资源"></span>

# Prepare task test resources

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

Prepare or reuse temporary databases and input/output volumes for the current task. See [Common information](objects.md) for objects, variables, and environment boundaries.

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

<span id="调用前准备"></span>

## Before you call this API

Retain injected service URLs, credentials, Workspace, and short-lived authorization in the current generation task environment. Use complete original authorization header values. Install jq and set the example variables.

<span id="请求体"></span>

## Request body

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```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} Parameters

The example derives scope from authorization in the task environment. A regular Product identity path also exists but requires explicit task_id, context_id, effective_role_id, and other scope conditions. A PAT does not replace task scope. Existing resources must match user, role, and conversation bindings. Preparation may create a database and input/output volumes; it does not publish a workflow.

| Fields | Type | Required | Description |
| --- | --- | --- | --- |
| `task_id` | string | Optional in task mode | Derived from verified task identity; explicit values must match. |
| `context_id` | string | Optional in task mode | Derived from verified task identity; explicit values must match. |
| `effective_role_id` | string | Optional in task mode | Derived from verified task identity; explicit values must match. |
| `catalog_id` | integer | No | Catalog for resource creation. 0 resolves the default Catalog, which must resolve to a positive value. |

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

<span id="成功响应"></span>

## Successful response

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```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} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | Response information. |
| `data` | object | Result of this operation. |
| `data.workspace_id` | string | Resource workspace. |
| `data.task_id` | string | Owning task. |
| `data.user_id` | string | Owning user. |
| `data.effective_role_id` | string | Effective role. |
| `data.context_id` | string | Owning conversation. |
| `data.operation_id` | string | Resource operation identifier. |
| `data.catalog_id` | integer | Catalog ID。 |
| `data.database_name` | string | Test database name. |
| `data.database_id` | integer | Test database ID. |
| `data.input_volume_id` | integer | Input volume ID. |
| `data.output_volume_id` | integer | Output volume ID. |
| `data.state` | string | Lease state; active in the example. |

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

<span id="错误响应"></span>

## Error response

Handle HTTP status and business fields. History and recovery have dedicated errors; see [Errors and environments](objects.md#错误与环境). Retain identity, source references, and operation identifiers, then check state before proceeding. Do not automatically switch workspace, candidate, or confirmation key.
