创建连接器¶

在当前工作区保存一个外部数据源连接器。创建只保存连接信息，不会开始导入或导出数据。

POST https://moi.matrixorigin.cn/newmoi/connectors

调用前准备¶

先在数据源类型说明中选择数据源和用途，再使用验证连接器配置检查当前填写的连接信息。准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

下方示例使用：

$AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。
$WORKSPACE_ID：要创建连接器的工作区 ID，通过 X-Workspace-ID Header 传递。
$CONNECTOR_NAME：新连接器名称。
$S3_ENDPOINT：目标标准 S3 服务地址。
$S3_ACCESS_KEY_ID：目标标准 S3 的访问密钥 ID。
$S3_ACCESS_KEY_SECRET：目标标准 S3 的访问密钥。
$S3_BUCKET_NAME：要访问的存储桶名称。
$S3_REGION：目标存储桶所在区域。

config 按数据源类型嵌套。标准 S3 的 source_type 为 5，其连接配置必须写在 config.s3 中；不要将配置字段直接放在 config 下。

请求体¶

创建连接器时，需要同时指定名称、数据源类型、用途和该类型的连接配置。

本文中，类型后的 [] 表示数组，例如 integer[] 是整数数组。

字段	类型	是否必填	说明
`name`	string	是	连接器名称。
`source_type`	integer	是	数据源类型代码。可用类型与用途组合见连接器。
`usage_type`	integer 或 integer[]	是	连接器用途，位掩码。取值：`1` = 导入，`2` = 导出。可传单个整数或整数数组，语义相同：`1` 与 `[1]` 均为仅导入，`2` 与 `[2]` 均为仅导出，`3` 与 `[1, 2]` 均为同时支持导入和导出。`0` 与 `[]` 非法。可用取值受 `source_type` 限制，不是所有数据源都支持全部用途；Langfuse 在创建表单中使用 `[1]`，不显示用途选择。
`config`	object	是	类型专属连接配置。顶层键必须与 `source_type` 对应；标准 S3 使用 `s3`。不要把其中的密码或密钥写入日志。

配置类型对应关系¶

当前创建表单中的连接器类型如下。创建时，根据所选 source_type 在 config 中使用对应的顶层键；不要混用不同类型的配置字段。

`source_type`	连接器类型	`config` 顶层键
`3`	MatrixOne	`mo`
`4`	阿里云 OSS	`oss`
`5`	标准 S3	`s3`
`7`	HDFS	`hdfs`
`8`	Hive	`hive`
`9`	MySQL	`mysql`
`10`	SQL Server	`sqlserver`
`11`	Oracle	`oracle`
`12`	PostgreSQL	`postgresql`
`13`	MongoDB	`mongodb`
`14`	Langfuse	`langfuse`

类型专属配置字段¶

以下字段均位于对应的 config 顶层键中。

MatrixOne（`source_type: 3`）¶

参数	类型	是否必填	说明
`config.mo.host`	string	是	MatrixOne 服务地址。
`config.mo.port`	integer	是	MatrixOne 服务端口。
`config.mo.username`	string	是	登录用户名。
`config.mo.password`	string	是	登录密码。
`config.mo.database`	string	否	默认数据库名称。

阿里云 OSS（`source_type: 4`）¶

参数	类型	是否必填	说明
`config.oss.endpoint`	string	是	OSS Endpoint。控制台的“地区”选择会写入该字段。
`config.oss.access_key_id`	string	是	AccessKey ID。
`config.oss.access_key_secret`	string	是	AccessKey Secret。
`config.oss.bucket_name`	string	是	存储桶名称，或 `<桶名>/<前缀>`。包含前缀时，服务将第一个 `/` 前的内容作为存储桶，其余内容作为文件前缀。

标准 S3（`source_type: 5`）¶

参数	类型	是否必填	说明
`config.s3.endpoint`	string	否	S3 服务 Endpoint。
`config.s3.access_key_id`	string	是	访问密钥 ID。
`config.s3.access_key_secret`	string	是	访问密钥。
`config.s3.bucket_name`	string	是	存储桶名称，或 `<桶名>/<前缀>`。包含前缀时，服务将第一个 `/` 前的内容作为存储桶，其余内容作为文件前缀。
`config.s3.region`	string	否	存储桶所在区域。
`config.s3.session_token`	string	否	临时凭据的会话令牌。
`config.s3.path_style`	boolean	否	为 `true` 时使用路径样式的 S3 请求地址。

HDFS（`source_type: 7`）¶

参数	类型	是否必填	说明
`config.hdfs.address`	string	是	NameNode 地址。可带 `hdfs://` 前缀。
`config.hdfs.auth_type`	integer	是	认证类型：`0` 为 Simple，`1` 为 Kerberos。
`config.hdfs.username`	string	Simple 时是	Simple 认证的用户名。
`config.hdfs.kerberos_principal`	string	Kerberos 时是	Kerberos Principal。
`config.hdfs.keytab_file`	string	Kerberos 时条件必填	Keytab 文件路径；未提供 `keytab_content` 时使用。
`config.hdfs.keytab_content`	string（Base64）	Kerberos 时条件必填	Keytab 内容；提供后优先于 `keytab_file`。
`config.hdfs.krb5_conf_file`	string	Kerberos 时条件必填	`krb5.conf` 文件路径；未提供 `krb5_conf_content` 时使用。
`config.hdfs.krb5_conf_content`	string（Base64）	Kerberos 时条件必填	`krb5.conf` 内容；提供后优先于 `krb5_conf_file`。
`config.hdfs.proxy_user`	string	否	Kerberos 认证后的代理用户。
`config.hdfs.file_path`	string	否	连接器访问的基础路径。

Hive（`source_type: 8`）¶

参数	类型	是否必填	说明
`config.hive.addresses`	string（字符串数组）	是	HiveServer2 地址，最多三个，格式为 `host:port`。
`config.hive.auth_type`	integer	是	认证类型：`0` 为 LDAP，`1` 为 Kerberos。
`config.hive.username`	string	LDAP 时是	LDAP 用户名。
`config.hive.password`	string	LDAP 时是	LDAP 密码。
`config.hive.client_principal`	string	Kerberos 时是	客户端 Kerberos Principal。
`config.hive.service_principal`	string	Kerberos 时是	HiveServer2 服务 Principal。
`config.hive.keytab_data`	string（Base64）	Kerberos 时是	Keytab 内容。
`config.hive.krb5_conf_data`	string（Base64）	Kerberos 时是	`krb5.conf` 内容。

当前连接器页面仅提供 LDAP 和 Kerberos 两种 Hive 认证方式，不提供 NONE 认证选项。

MySQL（`source_type: 9`）和 SQL Server（`source_type: 10`）¶

参数	类型	是否必填	说明
`config.mysql.host`	string	是	MySQL 数据库主机地址。
`config.sqlserver.host`	string	是	SQL Server 数据库主机地址。
`config.mysql.port`	integer	是	MySQL 数据库端口。
`config.sqlserver.port`	integer	是	SQL Server 数据库端口。
`config.mysql.username`	string	是	MySQL 登录用户名。
`config.sqlserver.username`	string	是	SQL Server 登录用户名。
`config.mysql.password`	string	是	MySQL 登录密码。
`config.sqlserver.password`	string	是	SQL Server 登录密码。
`config.mysql.database`	string	否	MySQL 默认数据库名称。
`config.sqlserver.database`	string	否	SQL Server 默认数据库名称。

Oracle（`source_type: 11`）¶

参数	类型	是否必填	说明
`config.oracle.host`	string	是	Oracle 主机地址。
`config.oracle.port`	integer	是	Oracle 端口。
`config.oracle.username`	string	是	登录用户名。
`config.oracle.password`	string	是	登录密码。
`config.oracle.service_name`	string	是	Oracle Service Name。

PostgreSQL（`source_type: 12`）¶

参数	类型	是否必填	说明
`config.postgresql.host`	string	是	PostgreSQL 主机地址。
`config.postgresql.port`	integer	是	PostgreSQL 端口。
`config.postgresql.username`	string	是	登录用户名。
`config.postgresql.password`	string	是	登录密码。
`config.postgresql.database`	string	是	数据库名称。

MongoDB（`source_type: 13`）¶

参数	类型	是否必填	说明
`config.mongodb.host`	string	是	MongoDB 主机地址。
`config.mongodb.port`	integer	是	MongoDB 端口。
`config.mongodb.authMode`	string	是	认证方式：`userpass` 或 `none`。
`config.mongodb.user`	string	`userpass` 时是	登录用户名。
`config.mongodb.password`	string	`userpass` 时是	登录密码。
`config.mongodb.authSource`	string	`userpass` 时是	认证数据库。
`config.mongodb.replicaSet`	string	否	副本集名称。
`config.mongodb.readPreference`	string	否	读取偏好。
`config.mongodb.readConcern`	string	否	读取关注级别。可选 `majority` 或 `snapshot`。

Langfuse（`source_type: 14`）¶

参数	类型	是否必填	说明
`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`。

创建 Langfuse 连接器时按以下边界提供字段：

连接器用途： 创建表单不提供用途选择，提交时使用导入用途。
Trace 同步范围： 在 Trace 同步任务中配置 sync_historical、start_from 和 observation_fields。
会话识别与结束： 在 Trace 同步任务中配置 user_id_source、user_id_metadata_key、session_idle_timeout_sec、session_end_strategy、session_end_metadata_key 和 session_end_metadata_value。
轮询与窗口： 在 Trace 同步任务中配置 poll_interval_sec、settled_delay_sec、window_overlap_sec、max_pages_per_tick 和 max_window_span_sec。创建连接器时不要传入这些字段。
服务端维护： 不要传入 secret_key_ref、database_name 或 target_table。

下方请求以标准 S3 为例。其他类型保留相同的外层请求结构，并将 source_type、config 顶层键和类型专属字段替换为上表对应值。

请求示例¶

curl -X POST "https://moi.matrixorigin.cn/newmoi/connectors" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d "{
    \"name\": \"$CONNECTOR_NAME\",
    \"source_type\": 5,
    \"usage_type\": [1],
    \"config\": {
      \"s3\": {
        \"endpoint\": \"$S3_ENDPOINT\",
        \"access_key_id\": \"$S3_ACCESS_KEY_ID\",
        \"access_key_secret\": \"$S3_ACCESS_KEY_SECRET\",
        \"bucket_name\": \"$S3_BUCKET_NAME\",
        \"region\": \"$S3_REGION\"
      }
    }
  }"

成功响应¶

当响应中的 code 为 OK 时，连接器已保存。记录 data.id，后续导入或导出任务需要使用该值。创建成功不表示后续数据传输一定成功。

{
  "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.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`	string（字符串数组）	初始关联任务列表。
`data.usage_type`	integer（整数数组）	已保存的用途列表，由服务端从位掩码展开。示例：`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者。
`data.config`	object	已保存的类型专属连接配置。敏感字段可能不返回；字段未返回不表示已保存的凭据被清空。

错误响应¶

HTTP 200 不一定表示创建成功。始终检查响应中的 code；只有 code: "OK" 才表示连接器已创建。

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

常见 HTTP 错误¶

HTTP 状态码	错误代码	常见原因	建议操作
`400`	`ErrParamInvalid`	请求体无效，或名称含不允许字符。	修正 JSON 和连接器名称。
`404`	`ErrNotFound`	请求了当前未启用的数据源类型。	选择当前可用的数据源类型。
`200`	`ErrServer`	服务未能创建连接器。	检查 `code`；此时连接器未创建，可稍后重试。
`503`	`ErrServer`	服务暂时无法完成创建。	稍后重试。

后续操作¶

记录 data.id。先根据 data.status 决定下一步：状态可用时，按 data.usage_type 分别前往导入任务的创建任务或导出任务的创建任务；状态为失败时，先查询连接器详情或更新连接器处理配置，不要直接创建任务。需要核对保存结果时，用 data.id 查询连接器详情。

最后更新于 2026 年 8 月 22 日

创建连接器¶

调用前准备¶

请求体¶

配置类型对应关系¶

类型专属配置字段¶

MatrixOne（source_type: 3）¶

阿里云 OSS（source_type: 4）¶

标准 S3（source_type: 5）¶

HDFS（source_type: 7）¶

Hive（source_type: 8）¶

MySQL（source_type: 9）和 SQL Server（source_type: 10）¶

Oracle（source_type: 11）¶

PostgreSQL（source_type: 12）¶

MongoDB（source_type: 13）¶

Langfuse（source_type: 14）¶