# 读取 Kafka 来源样本

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

从指定 Kafka 主题读取有限条消息，检查输入格式和字段。

```text
POST https://api.moi.matrixorigin.cn/v5/connectors/structured/v1/source/sample
```

## 调用前准备

准备目标工作区的个人访问令牌及相应来源读取或导入运行权限，安装 jq 并设置示例变量。身份、环境和结果交接见[公共说明](objects.md)。

## 请求体

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

```bash
curl -X POST "https://api.moi.matrixorigin.cn/v5/connectors/structured/v1/source/sample" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  --data-binary "$(jq -n --arg v0 "$CONNECTOR_ID" --arg v1 "$CONNECTOR_ID" --arg v2 "$KAFKA_TOPIC" '{"connector_id":$v0,"source":{"connector_id":$v1,"source_type":"SOURCE_TYPE_KAFKA"},"limit":5,"kafka_sample":{"topic_mode":"single","topics":[$v2]}}')"
```

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

source_type 必须为 SOURCE_TYPE_KAFKA，不能使用小写 kafka。Kafka source 不携带 database、schema、table 或 collection。样本不会写入目标数据表。has_more 和 next_position 是本次采样信息；当前输入没有 cursor/position 参数，不能把它们当成常规分页令牌反复采样来保证遍历全部消息。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `connector_id` | string | 是 | 当前工作区已启用且支持导入的连接器 ID。 |
| `source` | object | 是 | 同一连接器的来源对象。 |
| `source.connector_id` | string | 是 | 与外层 connector_id 一致。 |
| `source.source_type` | string | 是 | 当前动作允许的 API 大写枚举；不是 Worker 的小写名称。 |
| `limit` | integer | 是 | 1–100，不存在省略后自动补默认值的合同。 |
| `kafka_sample` | object | 是 | 选择单主题、多主题或名称模式。 |
| `kafka_sample.topic_mode` | string | 是 | single、multiple 或 pattern。 |
| `kafka_sample.topics` | string[] | 条件必填 | single 时恰好一个非空主题；multiple 时至少一个且均非空。 |
| `kafka_sample.topic_pattern` | string | 条件必填 | pattern 时提供非空名称匹配模式。 |

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

## 成功响应

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

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "rows": [
      {
        "value": {
          "id": 1
        }
      }
    ],
    "next_position": {
      "offset": 1
    },
    "has_more": false
  }
}
```

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 OK；还须检查 HTTP 与业务代码。 |
| `msg` | string | 响应信息。 |
| `data` | object | 当前来源结果。 |
| `data.rows` | array | 来源返回的原始 JSON 样本，保留键、值和格式信息。 |
| `data.next_position` | JSON | 可选读取位置，形状由 Kafka 采样结果决定；不是本动作的可回传分页参数。 |
| `data.has_more` | boolean | 本次采样是否还有更多结果；不等于导入任务状态。 |

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

## 错误响应

按[错误与环境](objects.md#错误与环境)区分参数、能力、授权和运行状态；不要只凭 HTTP 200 判定业务成功。
