连接器¶

连接器保存访问外部文件或结构化数据源所需的定义。完成本页操作后，你可以创建连接器并测试连接，保存连接器 ID，并浏览后续导入任务需要的来源信息。

前提条件¶

已准备 Product API Base URL、个人访问令牌和工作区 ID。
已确认目标数据源类型、网络入口和凭据。
当前身份具有连接器创建和读取权限。

数据源类型和 config 字段由当前环境注册的连接器能力决定。不要从其他类型的示例复制枚举或凭据字段。

连接器如何工作¶

准备连接定义
→ 校验网络与凭据
→ 创建连接器并保存 connector_id
→ 浏览数据库、Schema、表或文件
→ 创建导入或导出任务

连接测试成功只证明该定义在测试时可以访问数据源，不会创建传输任务，也不保证后续连接持续可用。

方法与路径	用途
`GET /connectors/list`	列出连接器
`POST /connectors/get`	根据 ID 读取连接器
`POST /connectors/validate`	校验尚未保存或已编辑的连接定义
`POST /connectors`	创建连接器
`PUT /connectors/{connector_id}`	更新连接器
`DELETE /connectors/{connector_id}`	删除连接器
`GET /connectors/structured/v1/sources`	列出结构化导入支持的来源能力

测试连接¶

下面是请求结构。将 source_type、usage_type 和 config 替换为当前环境为目标数据源返回或要求的值：

curl -X POST "$PRODUCT_API_BASE_URL/connectors/validate" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "<CONNECTOR_NAME>",
    "source_type": <SOURCE_TYPE>,
    "usage_type": [<USAGE_TYPE>],
    "config": {
      "<CONFIG_FIELD>": "<CONFIG_VALUE>"
    }
  }'

字段	类型	必需	说明
`name`	string	是	连接器名称。
`source_type`	integer	是	数据源类型。使用当前连接器能力返回的值。
`usage_type`	integer[]	是	连接器用途。不要从 `source_type` 推断。
`config`	object	按类型	网络地址、凭据和类型专属选项。只发送当前类型支持的字段。

成功响应中的 data.valid 表示本次校验结果：

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "valid": true
  }
}

valid: false 是业务校验未通过，不应视为连接器已经可用。检查数据源地址、网络、凭据和类型专属错误后再提交。

创建连接器¶

确认定义可以校验后，将同一请求体发送到创建接口：

curl -X POST "$PRODUCT_API_BASE_URL/connectors" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d @connector.json

成功响应返回连接器：

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "<CONNECTOR_ID>",
    "name": "<CONNECTOR_NAME>",
    "source_type": 0,
    "status": "<STATUS>",
    "related_task_ids": [],
    "usage_type": []
  }
}

保存 data.id。status 是已保存连接器的当前状态；创建请求成功并不替代后续数据源访问校验。

浏览结构化来源¶

结构化来源通常按以下顺序浏览：

GET /connectors/structured/v1/sources：读取可用来源能力。
POST /connectors/structured/v1/source/databases：使用 connector_id 和 source_type 列出数据库。
POST /connectors/structured/v1/source/schemas：增加 database 选择 Schema。
POST /connectors/structured/v1/source/objects：列出表或集合。
POST /connectors/structured/v1/source/schema：读取所选对象的字段结构。

旧的 /connectors/db/... 接口族仍提供数据库、Schema 和表浏览。构造导入任务时，应使用同一来源发现流程返回的标识和字段，不要混合两套来源对象。

安全和删除¶

连接器配置可能包含数据库密码、访问密钥或 Token。不要把完整请求体、响应头或连接器配置写入应用日志。读取接口不返回明文密钥时，不要将其当作配置丢失。

删除连接器前检查 related_task_ids，并确认导入或导出任务已经停止或迁移。删除连接器不会自动删除已经写入数据目录的数据。

常见问题¶

现象	先检查	下一步
`valid` 为 `false`	数据源地址、凭据、网络和 `source_type`	修正连接定义后重新测试连接，不直接创建任务。
创建后状态异常	创建响应的 `status` 和连接器详情	重新读取连接器，并按错误信息检查配置。
无法列出数据库或表	连接器 ID、来源类型和上一步返回的数据库/Schema	从结构化来源列表重新开始，避免手工拼接标识。
无法删除连接器	`related_task_ids` 和任务状态	先处理相关任务，再重新提交删除。

下一步¶

最后更新于 2026 年 8 月 14 日