# 连接器

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

## 前提条件

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

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

## 连接器如何工作

```text
准备连接定义
→ 校验网络与凭据
→ 创建连接器并保存 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` 替换为当前环境为目标数据源返回或要求的值：

```bash
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` 表示本次校验结果：

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

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

## 创建连接器

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

```bash
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
```

成功响应返回连接器：

```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` 是已保存连接器的当前状态；创建请求成功并不替代后续数据源访问校验。

## 浏览结构化来源

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

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

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

## 安全和删除

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

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

## 常见问题

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

## 下一步

- [创建并跟踪导入或导出任务](import-export-tasks.md)
- [确认目标数据库、表和卷](databases-tables.md)
- [使用 Product SDK 管理连接器](../../../sdk/product-sdk/guides/connectors-import-export.md)