创建连接器¶

在当前工作区保存一个外部数据源连接器。创建只保存连接信息，不会开始导入或导出数据。接口会检查连接信息；检查未通过时，连接器仍会保存，但状态为 failed。

POST https://api.moi.matrixorigin.cn/v5/connectors

调用前准备¶

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。
根据数据源类型说明确定数据源类型和用途。
按下方请求体准备该数据源的连接信息。一次请求只填写与所选数据源对应的一组 config 对象。

请求体¶

将 $AI_STUDIO_API_KEY、$WORKSPACE_ID 和示例中的连接信息替换为实际值。

输入示例

参数说明

标准 S3

参数	类型	是否必填	说明
`name`	string	是	连接器名称。去除首尾空白后不能为空；不能包含半角空格、`<` 或 `>`。
`source_type`	integer	是	数据源类型代码。标准 S3 填写 `5`，配置写在 `config.s3`。
`usage_type`	integer 或 array of integer	是	连接器用途。`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者。创建时必填。
`config`	object	是	连接信息。只填写一组与 `source_type` 对应的配置对象。
`config.s3.endpoint`	string	否	S3 服务地址。未填写时使用 S3 服务的默认地址。
`config.s3.access_key_id`	string	是	访问密钥 ID。
`config.s3.access_key_secret`	string	是	访问密钥。
`config.s3.bucket_name`	string	是	存储桶名称；可写为桶名/前缀，例如 `orders/import`。
`config.s3.region`	string	否	存储桶所在区域。
`config.s3.session_token`	string	否	使用临时凭据时填写的会话令牌。
`config.s3.path_style`	boolean	否	填 `true` 时使用路径样式地址；省略或填 `false` 时使用虚拟主机样式地址。

阿里云 OSS

参数	类型	是否必填	说明
`name`	string	是	连接器名称。去除首尾空白后不能为空；不能包含半角空格、`<` 或 `>`。
`source_type`	integer	是	数据源类型代码。阿里云 OSS 填写 `4`，配置写在 `config.oss`。
`usage_type`	integer 或 array of integer	是	连接器用途。`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者。创建时必填。
`config`	object	是	连接信息。只填写一组与 `source_type` 对应的配置对象。
`config.oss.endpoint`	string	是	OSS 服务地址。
`config.oss.access_key_id`	string	是	AccessKey ID。
`config.oss.access_key_secret`	string	是	AccessKey Secret。
`config.oss.bucket_name`	string	是	存储桶名称；可写为桶名/前缀，例如 `orders/import`。

MatrixOne

参数	类型	是否必填	说明
`name`	string	是	连接器名称。去除首尾空白后不能为空；不能包含半角空格、`<` 或 `>`。
`source_type`	integer	是	数据源类型代码。MatrixOne 填写 `3`，配置写在 `config.mo`。
`usage_type`	integer 或 array of integer	是	连接器用途。`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者。创建时必填。
`config`	object	是	连接信息。只填写一组与 `source_type` 对应的配置对象。
`config.mo.host`	string	是	MatrixOne 服务地址。
`config.mo.port`	integer	是	MatrixOne 服务端口。
`config.mo.username`	string	是	登录用户名。
`config.mo.password`	string	是	登录密码。
`config.mo.database`	string	否	默认数据库名称。

HDFS Simple

参数	类型	是否必填	说明
`name`	string	是	连接器名称。去除首尾空白后不能为空；不能包含半角空格、`<` 或 `>`。
`source_type`	integer	是	数据源类型代码。HDFS 填写 `7`，配置写在 `config.hdfs`。
`usage_type`	integer 或 array of integer	是	连接器用途。`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者。创建时必填。
`config`	object	是	连接信息。只填写一组与 `source_type` 对应的配置对象。
`config.hdfs.address`	string	是	NameNode 地址，可带 `hdfs://` 前缀。
`config.hdfs.auth_type`	integer	是	认证类型：`0` 为 Simple，`1` 为 Kerberos。Simple 认证填 `0`。
`config.hdfs.username`	string	Simple 时必填	Simple 认证使用的 HDFS 用户名。
`config.hdfs.file_path`	string	是	连接器可访问的 HDFS 基础目录，例如 `/data/orders`。

HDFS Kerberos

参数	类型	是否必填	说明
`name`	string	是	连接器名称。去除首尾空白后不能为空；不能包含半角空格、`<` 或 `>`。
`source_type`	integer	是	数据源类型代码。HDFS 填写 `7`，配置写在 `config.hdfs`。
`usage_type`	integer 或 array of integer	是	连接器用途。`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者。创建时必填。
`config`	object	是	连接信息。只填写一组与 `source_type` 对应的配置对象。
`config.hdfs.address`	string	是	NameNode 地址，可带 `hdfs://` 前缀。
`config.hdfs.auth_type`	integer	是	填 `1`。
`config.hdfs.kerberos_principal`	string	是	用于登录的用户主体。
`config.hdfs.keytab_content`	string（Base64 编码）	条件必填	Kerberos 认证时，未提供 `keytab_file` 时必填的 Keytab 内容。
`config.hdfs.krb5_conf_content`	string（Base64 编码）	条件必填	Kerberos 认证时，未提供 `krb5_conf_file` 时必填的 `krb5.conf` 内容。
`config.hdfs.proxy_user`	string	否	登录后使用的代理用户。
`config.hdfs.file_path`	string	是	连接器可访问的 HDFS 基础目录。

Hive LDAP

参数	类型	是否必填	说明
`name`	string	是	连接器名称。去除首尾空白后不能为空；不能包含半角空格、`<` 或 `>`。
`source_type`	integer	是	数据源类型代码。Hive 填写 `8`，配置写在 `config.hive`。
`usage_type`	integer 或 array of integer	是	连接器用途。`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者。创建时必填。
`config`	object	是	连接信息。只填写一组与 `source_type` 对应的配置对象。
`config.hive.addresses`	array of string	是	HiveServer2 地址列表。至少填写一个 `host:port`。
`config.hive.auth_type`	integer	是	认证类型：`0` 为 LDAP，`1` 为 Kerberos。LDAP 认证填 `0`。
`config.hive.username`	string	LDAP 时必填	LDAP 用户名。
`config.hive.password`	string	LDAP 时必填	LDAP 密码。

Hive Kerberos

参数	类型	是否必填	说明
`name`	string	是	连接器名称。去除首尾空白后不能为空；不能包含半角空格、`<` 或 `>`。
`source_type`	integer	是	数据源类型代码。Hive 填写 `8`，配置写在 `config.hive`。
`usage_type`	integer 或 array of integer	是	连接器用途。`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者。创建时必填。
`config`	object	是	连接信息。只填写一组与 `source_type` 对应的配置对象。
`config.hive.addresses`	array of string	是	HiveServer2 地址列表，至少填写一个 `host:port`。
`config.hive.auth_type`	integer	是	填 `1`。
`config.hive.client_principal`	string	是	用于登录的用户主体。
`config.hive.service_principal`	string	是	HiveServer2 服务主体。
`config.hive.keytab_data`	string	是	Keytab 内容。
`config.hive.krb5_conf_data`	string	是	`krb5.conf` 内容。

MySQL

参数	类型	是否必填	说明
`name`	string	是	连接器名称。去除首尾空白后不能为空；不能包含半角空格、`<` 或 `>`。
`source_type`	integer	是	数据源类型代码。MySQL 填写 `9`，配置写在 `config.mysql`。
`usage_type`	integer 或 array of integer	是	连接器用途。`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者。创建时必填。
`config`	object	是	连接信息。只填写一组与 `source_type` 对应的配置对象。
`config.mysql.host`	string	是	MySQL 数据库主机地址。
`config.mysql.port`	integer	是	MySQL 数据库端口。
`config.mysql.username`	string	是	登录用户名。
`config.mysql.password`	string	是	登录密码。
`config.mysql.database`	string	是	要连接的数据库名称。连接器创建后仅浏览和导入该数据库。

SQL Server

参数	类型	是否必填	说明
`name`	string	是	连接器名称。去除首尾空白后不能为空；不能包含半角空格、`<` 或 `>`。
`source_type`	integer	是	数据源类型代码。SQL Server 填写 `10`，配置写在 `config.sqlserver`。
`usage_type`	integer 或 array of integer	是	连接器用途。`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者。创建时必填。
`config`	object	是	连接信息。只填写一组与 `source_type` 对应的配置对象。
`config.sqlserver.host`	string	是	SQL Server 数据库主机地址。
`config.sqlserver.port`	integer	是	SQL Server 数据库端口。
`config.sqlserver.username`	string	是	登录用户名。
`config.sqlserver.password`	string	是	登录密码。
`config.sqlserver.database`	string	否	要在连接时打开的数据库名称。省略时先连接到 SQL Server 实例，后续可浏览可访问的数据库。

Oracle

参数	类型	是否必填	说明
`name`	string	是	连接器名称。去除首尾空白后不能为空；不能包含半角空格、`<` 或 `>`。
`source_type`	integer	是	数据源类型代码。Oracle 填写 `11`，配置写在 `config.oracle`。
`usage_type`	integer 或 array of integer	是	连接器用途。`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者。创建时必填。
`config`	object	是	连接信息。只填写一组与 `source_type` 对应的配置对象。
`config.oracle.host`	string	是	Oracle 主机地址。
`config.oracle.port`	integer	是	Oracle 端口。
`config.oracle.username`	string	是	登录用户名。
`config.oracle.password`	string	是	登录密码。
`config.oracle.service_name`	string	是	要连接的 Oracle 服务名称。

PostgreSQL

参数	类型	是否必填	说明
`name`	string	是	连接器名称。去除首尾空白后不能为空；不能包含半角空格、`<` 或 `>`。
`source_type`	integer	是	数据源类型代码。PostgreSQL 填写 `12`，配置写在 `config.postgresql`。
`usage_type`	integer 或 array of integer	是	连接器用途。`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者。创建时必填。
`config`	object	是	连接信息。只填写一组与 `source_type` 对应的配置对象。
`config.postgresql.host`	string	是	PostgreSQL 主机地址。
`config.postgresql.port`	integer	是	PostgreSQL 端口。
`config.postgresql.username`	string	是	登录用户名。
`config.postgresql.password`	string	是	登录密码。
`config.postgresql.database`	string	是	要连接的数据库名称。连接器创建后仅浏览和导入该数据库。

MongoDB

参数	类型	是否必填	说明
`name`	string	是	连接器名称。去除首尾空白后不能为空；不能包含半角空格、`<` 或 `>`。
`source_type`	integer	是	数据源类型代码。MongoDB 填写 `13`，配置写在 `config.mongodb`。
`usage_type`	integer 或 array of integer	是	连接器用途。`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者。创建时必填。
`config`	object	是	连接信息。只填写一组与 `source_type` 对应的配置对象。
`config.mongodb.host`	string	是	MongoDB 主机地址。
`config.mongodb.port`	integer	是	MongoDB 端口。
`config.mongodb.authMode`	string	是	认证方式：`userpass` 为用户名和密码认证，`none` 为不认证。
`config.mongodb.user`	string	authMode 为 userpass 时必填	`authMode` 为 `userpass` 时的登录用户名。
`config.mongodb.password`	string	否	`authMode` 为 `userpass` 时的登录密码。
`config.mongodb.authSource`	string	authMode 为 userpass 时必填	`authMode` 为 `userpass` 时保存认证用户的数据库名称，例如 `admin`。
`config.mongodb.replicaSet`	string	否	副本集名称。
`config.mongodb.readPreference`	string	否	读取节点偏好，可选 `primary`、`primaryPreferred`、`secondary`、`secondaryPreferred` 或 `nearest`。
`config.mongodb.readConcern`	string	否	读取一致性级别，可选 `majority` 或 `snapshot`。

Langfuse

参数	类型	是否必填	说明
`name`	string	是	连接器名称。去除首尾空白后不能为空；不能包含半角空格、`<` 或 `>`。
`source_type`	integer	是	数据源类型代码。Langfuse 填写 `14`，配置写在 `config.langfuse`。
`usage_type`	integer 或 array of integer	是	连接器用途。`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者。创建时必填。
`config`	object	是	连接信息。只填写一组与 `source_type` 对应的配置对象。
`config.langfuse.host`	string	是	Langfuse 服务地址。
`config.langfuse.public_key`	string	是	Langfuse Public Key。
`config.langfuse.secret_key`	string	是	Langfuse Secret Key。该值仅用于提交和校验，不会在后续详情响应中返回。
`config.langfuse.pull_mode`	string	否	拉取模式。可选 `langfuse_v1` 或 `langfuse_v2`；省略时使用 `langfuse_v1`。

成功响应¶

成功时返回 200。服务会保存连接器；检查未通过时，连接器仍会保存，但状态为 failed。记录 data.id，并按 data.status 决定是否继续创建任务。

响应示例

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

字段说明

字段	类型	说明
`code`	string	成功时为 `OK`。
`msg`	string	成功时为 `OK`。
`data`	object	已保存的连接器。
`data.id`	string	新连接器 ID。
`data.name`	string	已保存的连接器名称。
`data.source_type`	integer	已保存的数据源类型代码。
`data.created_at`	integer	创建时间的 Unix 时间戳。
`data.updated_at`	integer	更新时间的 Unix 时间戳。
`data.status`	string	当前连接器状态。创建后为 `active` 或 `failed` 时，先根据该状态决定是否继续创建任务。
`data.username`	string	创建该连接器的用户名称。
`data.related_task_ids`	array of string	关联导入任务 ID 列表。新建连接器时为空数组。
`data.usage_type`	array of integer	已保存的用途列表：`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者。
`data.config`	object	已保存的连接配置对象。对象结构由 `source_type` 决定。

错误响应¶

响应示例

{
  "code": "ErrParamInvalid",
  "msg": "invalid connector parameters",
  "data": null
}

字段说明

字段	类型	说明
`code`	string	错误代码。
`msg`	string	可读错误信息。
`data`	null	错误响应中为 `null`。

后续操作¶

记录 data.id，并按 data.status 决定下一步：状态可用时，按 data.usage_type 前往创建连接器文件导入任务或创建导出任务；状态为失败时，先查看连接器详情或更新连接器处理配置，不要直接创建任务。

最后更新于 2026 年 9 月 28 日