读取 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 参数,不能把它们当成常规分页令牌反复采样来保证遍历全部消息。

字段

类型

是否必填

说明

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 时提供非空名称匹配模式。

成功响应

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

字段

类型

说明

code

string

成功时为 OK;还须检查 HTTP 与业务代码。

msg

string

响应信息。

data

object

当前来源结果。

data.rows

array

来源返回的原始 JSON 样本,保留键、值和格式信息。

data.next_position

JSON

可选读取位置,形状由 Kafka 采样结果决定;不是本动作的可回传分页参数。

data.has_more

boolean

本次采样是否还有更多结果;不等于导入任务状态。

错误响应

按错误与环境区分参数、能力、授权和运行状态;不要只凭 HTTP 200 判定业务成功。

最后更新于