# 创建连接器

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

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

## 调用前准备

先在[数据源类型说明](../../../../../guides/ai-studio/data-sources/connectors.md#选择数据源类型)中选择数据源和用途，再使用[验证连接器配置](validate-connector.md)检查当前填写的连接信息。准备有目标工作区访问权限的个人访问令牌和目标工作区 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 | 是 | 数据源类型代码。可用类型与用途组合见[连接器](../../../../../guides/ai-studio/data-sources/connectors.md#选择数据源类型)。 |
| `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` 顶层键和类型专属字段替换为上表对应值。

## 请求示例

```bash
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`，后续导入或导出任务需要使用该值。创建成功不表示后续数据传输一定成功。

```json
{
  "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"` 才表示连接器已创建。

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

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

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

## 后续操作

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