<span id="查看任务测试资源样例"></span>

# Observe task test resource samples

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

Read file, schema, and row samples in the current task's test resources. See [Common information](objects.md) for objects, variables, and environment boundaries.

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

<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/observe" \
  -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

This API first calls EnsureScratch and may create test databases/volumes before reading file/table samples. It is not a read-only health query. A volume returns up to 1000 files and a table up to 100 rows. Check total, row_count, and truncated rather than treating samples as complete sets. Regular identity scope conditions match preparation.

| 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": {
    "scope": "current_task",
    "database_name": "scratch_example",
    "volumes": [
      {
        "volume_id": 12,
        "files": [],
        "total": 0,
        "truncated": false
      },
      {
        "volume_id": 13,
        "files": [],
        "total": 0,
        "truncated": false
      }
    ],
    "tables": []
  }
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | OK on success. |
| `msg` | string | Response information. |
| `data` | object | Result of this operation. |
| `data.scope` | string | Observation scope; actual value returned by the server. |
| `data.database_name` | string | Test database. |
| `data.volumes` | object[] | File samples from input/output volumes. |
| `data.volumes[].volume_id` | integer | Volume ID. |
| `data.volumes[].files` | object[] | Current file list; verify file objects against Catalog definitions separately. |
| `data.volumes[].total` | integer | Total volume files. |
| `data.volumes[].truncated` | boolean | Whether the current file list is shorter than the total. |
| `data.tables` | object[] | Schema and row samples. |
| `data.tables[].name` | string | Table name. |
| `data.tables[].columns` | object[] | Column names and data types. |
| `data.tables[].row_count` | integer | Total table rows. |
| `data.tables[].rows` | array[] | Row values; retain JSON scalar types returned by the SQL driver. |
| `data.tables[].truncated` | boolean | Whether row samples are fewer than total rows. |

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

<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.
