# 更新连接器

更新已保存连接器的名称、用途、数据源类型或配置。只传入需要修改的字段，其他字段保持原值。

```text
PUT https://moi.matrixorigin.cn/newmoi/connectors/{connector_id}
```

## 调用前准备

先[查询连接器详情](get-connector.md)，确认要修改的连接器。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和连接器 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：目标工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$CONNECTOR_ID`：要更新的连接器 ID。
- `$NEW_CONNECTOR_NAME`：更新后的连接器名称。

如果修改 `source_type` 或 `config`，请传入与目标数据源类型匹配的完整嵌套配置。完整的类型、字段和认证分支见[创建连接器的类型专属配置字段](create-connector.md#类型专属配置字段)。不要传入 `usage_type: 0` 或空数组；省略 `usage_type` 才表示保持原用途。

## 路径参数

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `connector_id` | string | 要更新的连接器 ID。 |

## 请求体

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

请求体中的所有字段均为可选。示例仅修改连接器名称。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 否 | 新连接器名称。 |
| `source_type` | integer | 否 | 新数据源类型代码。修改时请同时传入与新类型匹配的 `config`。可用类型见[连接器](../../../../../guides/ai-studio/data-sources/connectors.md#选择数据源类型)。 |
| `usage_type` | integer 或 integer[] | 否 | 新用途，位掩码。取值：`1` = 导入，`2` = 导出。可传单个整数或整数数组，语义相同：`1` 与 `[1]`、`2` 与 `[2]`、`3` 与 `[1, 2]`。省略本字段表示保持原用途；不要传 `0` 或 `[]`。可用取值受目标 `source_type` 限制；Langfuse 在编辑表单中不显示此项。 |
| `config` | object | 否 | 类型专属连接配置。传入时替换已保存的连接配置；顶层键和完整字段见[创建连接器的类型专属配置字段](create-connector.md#类型专属配置字段)。 |

## 请求示例

```bash
curl -X PUT "https://moi.matrixorigin.cn/newmoi/connectors/$CONNECTOR_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d "{
    \"name\": \"$NEW_CONNECTOR_NAME\"
  }"
```

## 成功响应

当响应中的 `code` 为 `OK` 时，更新请求已完成。响应中的 `data` 为 `null`，请重新[查询连接器详情](get-connector.md)确认结果。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": null
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data` | null | 该接口不返回更新后的连接器对象。 |

## 错误响应

`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`；此时更新未完成，可稍后重试。
```

## 后续操作

本接口成功时 `data` 为 `null`。用同一 `connector_id` [查询连接器详情](get-connector.md)确认名称、用途和状态。若改过连接配置，可先[验证连接器配置](validate-connector.md)再用于任务。需要移除时，确认无关联任务后[删除连接器](delete-connector.md)。