读取 Kafka 来源样本¶
从指定 Kafka 主题读取有限条消息,检查输入格式和字段。
POST https://api.moi.matrixorigin.cn/v5/connectors/structured/v1/source/sample
调用前准备¶
准备目标工作区的个人访问令牌及相应来源读取或导入运行权限,安装 jq 并设置示例变量。身份、环境和结果交接见公共说明。
请求体¶
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]}}')"
source_type 必须为 SOURCE_TYPE_KAFKA,不能使用小写 kafka。Kafka source 不携带 database、schema、table 或 collection。样本不会写入目标数据表。has_more 和 next_position 是本次采样信息;当前输入没有 cursor/position 参数,不能把它们当成常规分页令牌反复采样来保证遍历全部消息。
字段 |
类型 |
是否必填 |
说明 |
|---|---|---|---|
|
string |
是 |
当前工作区已启用且支持导入的连接器 ID。 |
|
object |
是 |
同一连接器的来源对象。 |
|
string |
是 |
与外层 connector_id 一致。 |
|
string |
是 |
当前动作允许的 API 大写枚举;不是 Worker 的小写名称。 |
|
integer |
是 |
1–100,不存在省略后自动补默认值的合同。 |
|
object |
是 |
选择单主题、多主题或名称模式。 |
|
string |
是 |
single、multiple 或 pattern。 |
|
string[] |
条件必填 |
single 时恰好一个非空主题;multiple 时至少一个且均非空。 |
|
string |
条件必填 |
pattern 时提供非空名称匹配模式。 |
成功响应¶
{
"code": "OK",
"msg": "OK",
"data": {
"rows": [
{
"value": {
"id": 1
}
}
],
"next_position": {
"offset": 1
},
"has_more": false
}
}
字段 |
类型 |
说明 |
|---|---|---|
|
string |
成功时为 OK;还须检查 HTTP 与业务代码。 |
|
string |
响应信息。 |
|
object |
当前来源结果。 |
|
array |
来源返回的原始 JSON 样本,保留键、值和格式信息。 |
|
JSON |
可选读取位置,形状由 Kafka 采样结果决定;不是本动作的可回传分页参数。 |
|
boolean |
本次采样是否还有更多结果;不等于导入任务状态。 |
错误响应¶
按错误与环境区分参数、能力、授权和运行状态;不要只凭 HTTP 200 判定业务成功。