验证连接器配置¶

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

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

调用前准备¶

准备与创建连接器接口相同的连接器定义、有目标工作区访问权限的个人访问令牌和目标工作区 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	是	待验证的数据源类型代码。可用类型与用途组合见连接器。
`usage_type`	integer 或 integer[]	是	连接器用途，位掩码。取值：`1` = 导入，`2` = 导出。可传单个整数或整数数组，语义相同：`1` 与 `[1]` 均为仅导入，`2` 与 `[2]` 均为仅导出，`3` 与 `[1, 2]` 均为同时支持导入和导出。`0` 与 `[]` 非法。可用取值受 `source_type` 限制，不是所有数据源都支持全部用途；Langfuse 在创建表单中使用 `[1]`，不显示用途选择。
`config`	object	是	类型专属的连接地址和凭据。顶层键及全部字段与创建连接器的类型专属配置字段相同；不要把其中的密码或密钥写入日志。

配置类型对应关系¶

config 必须按 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`

请求示例¶

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

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\"
      }
    }
  }"

成功响应¶

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

响应字段如下。

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

错误响应¶

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

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

常见 HTTP 错误¶

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

后续操作¶

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

最后更新于 2026 年 8 月 22 日