# 验证连接器配置

验证一个尚未保存或已编辑的连接器定义。验证只检查当前连接信息，不会创建或更新连接器。

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

## 调用前准备

准备与[创建连接器](create-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`：目标存储桶所在区域。

## 请求体

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

验证请求使用与创建连接器相同的字段。先传入实际连接信息，确认 `data.valid` 后再创建连接器。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `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 | 是 | 类型专属的连接地址和凭据。顶层键及全部字段与[创建连接器的类型专属配置字段](create-connector.md#类型专属配置字段)相同；不要把其中的密码或密钥写入日志。 |

### 配置类型对应关系

`config` 必须按 `source_type` 嵌套，不能将类型专属字段直接放在 `config` 下。下表覆盖当前创建表单中的全部连接器类型；各类型的完整字段、条件字段和认证分支见[创建连接器的类型专属配置字段](create-connector.md#类型专属配置字段)。

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

## 请求示例

下方是标准 S3 的可执行示例。验证其他类型时，保留外层结构，按上表替换 `source_type` 和 `config` 顶层键，并填写对应类型的完整字段。

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/connectors/validate" \
  -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\"
      }
    }
  }"
```

## 成功响应

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

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 请求被正确处理时为 `OK`。 |
| `msg` | string | 请求被正确处理时为 `OK`。 |
| `data.valid` | boolean | 当前连接定义是否通过校验。为否时不是 HTTP 请求失败，也不表示连接器已可用。 |

## 错误响应

`HTTP 200` 不一定表示验证通过。先检查 `code`，再检查 `data.valid`。

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

### 常见 HTTP 错误

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

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `ErrParamInvalid`
  - 请求体无效或名称含不允许字符。
  - 修正连接定义后重试。
* - `404`
  - `ErrNotFound`
  - 请求了当前未启用的数据源类型。
  - 选择当前可用的数据源类型。
* - `200`
  - `ErrServer`
  - 服务校验发生内部错误。
  - 检查 `code`，不要将其与 `data.valid: false` 混淆。
```

## 后续操作

`data.valid` 为 `true` 时，用同一份请求体[创建连接器](create-connector.md)。为 `false` 时，先修正 `config` 或用途后再重新验证，不要直接创建。