查询连接器列表¶

列出当前工作区中你有读取权限的连接器。先通过此接口找到连接器 ID，再查询详情、更新、删除或创建数据任务。

GET https://moi.matrixorigin.cn/newmoi/connectors/list

调用前准备¶

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

下方示例使用：

$AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。
$WORKSPACE_ID：要查询的工作区 ID，通过 X-Workspace-ID Header 传递。

查询参数¶

不传查询参数时，接口返回第 1 页的连接器。使用筛选参数缩小结果范围；使用 page 和 page_size 分页读取结果。

参数	类型	是否必填	说明
`name`	string	否	按名称筛选。
`page`	integer	否	页码。默认值为 `1`。
`page_size`	integer	否	每页数量。默认值为 `20`。
`order_by`	string	否	排序字段。未传时按创建时间倒序返回。
`is_desc`	boolean	否	设置 `order_by` 时，是否按降序排序。
`keyword`	string	否	关键字筛选。
`source_type`	integer	否	按单个数据源类型筛选。
`source_type_list`	integer（整数数组）	否	按多个数据源类型筛选；可重复传入。
`status`	string	否	按单个连接器状态筛选。
`status_list`	string（字符串数组）	否	按多个连接器状态筛选；可重复传入。
`usage_type`	integer（整数数组）	否	按连接器用途筛选。

请求示例¶

curl "https://moi.matrixorigin.cn/newmoi/connectors/list?page=1&page_size=20" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

如需按名称筛选，将 name 作为查询参数追加到地址中。

成功响应¶

成功时返回 200。从 data.connectors[] 中取得连接器信息，从 data.total 判断共有多少条匹配结果。

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "connectors": [
      {
        "id": "conn_01",
        "name": "s3-orders-import",
        "source_type": 5,
        "created_at": 1735632000,
        "updated_at": 1735718400,
        "status": "active",
        "username": "reader",
        "related_task_ids": ["task_01"],
        "usage_type": [1],
        "config": {
          "s3": {
            "endpoint": "https://s3.example.com",
            "bucket_name": "orders",
            "region": "us-east-1"
          }
        }
      }
    ],
    "total": 1
  }
}

响应字段如下。

本文中，类型后的 [] 表示数组；字段路径中的 [] 表示数组中的每一项。

字段	类型	说明
`code`	string	成功时为 `OK`。
`msg`	string	成功时为 `OK`。
`data.connectors`	object（对象数组）	当前筛选条件下的连接器。
`data.connectors[].id`	string	连接器 ID。
`data.connectors[].name`	string	连接器名称。
`data.connectors[].source_type`	integer	数据源类型代码。
`data.connectors[].created_at`	integer	创建时间的 Unix 时间戳。
`data.connectors[].updated_at`	integer	更新时间的 Unix 时间戳。
`data.connectors[].status`	string	连接器当前状态。
`data.connectors[].username`	string	配置中的用户名。
`data.connectors[].related_task_ids`	string（字符串数组）	关联的数据任务 ID。
`data.connectors[].usage_type`	integer（整数数组）	已保存的用途列表，由服务端从位掩码展开。示例：`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者。
`data.connectors[].config`	object	类型专属连接配置；顶层键与完整字段见创建连接器的类型专属配置字段，响应中的字段以实际数据源类型为准。
`data.total`	integer	匹配条件的连接器总数。

读取下一页¶

根据 data.total 和请求时的 page_size 计算最后一页，再依次增加 page。例如 total 为 41、page_size 为 20 时，依次请求第 1、2、3 页。

错误响应¶

{
  "code": "ErrForbidden",
  "msg": "permission denied",
  "data": null
}

常见 HTTP 错误¶

HTTP 状态码	错误代码	常见原因	建议操作
`400`	`ErrParamInvalid`	查询参数格式无效。	修正参数后重试。
`403`	`ErrForbidden`	调用者没有读取连接器集合的权限。	检查工作区和连接器授权。
`503`	`ErrCoreAuthorizeUnavailable`	服务无法完成授权筛选。	稍后重试；不要把空列表视为无连接器。

后续操作¶

保存目标连接器的 id，再查询连接器详情。要继续选库表时查看可浏览的连接器；要浏览文件时查询文件列表。

最后更新于 2026 年 8 月 22 日