# 更新连接器

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

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

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

## 调用前准备

先[查看连接器详情](get-connector.md#成功响应)，确认要修改的连接器。准备有目标工作区访问权限的[个人访问令牌](../../../../../guides/genesis/api-keys.md#创建和管理个人访问令牌)、[目标工作区 ID](../../../../../guides/ai-studio/resource-center/workspace.md#复制工作区-id) 和连接器 ID。

## 路径参数和请求体

将 `$AI_STUDIO_API_KEY`、`$WORKSPACE_ID`、`$CONNECTOR_ID` 和要更新的字段替换为实际值。

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} 输入示例

::::{tab-set}
:::{tab-item} 修改名称

```bash
curl -X PUT "https://api.moi.matrixorigin.cn/v5/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\"
  }"
```

:::
:::{tab-item} 修改数据源类型或连接信息

将 `$CONNECTOR_ID` 和新数据源的连接信息替换为实际值。

```bash
curl -X PUT "https://api.moi.matrixorigin.cn/v5/connectors/$CONNECTOR_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "source_type": 5,
    "config": {
      "s3": {
        "endpoint": "https://s3.example.com",
        "access_key_id": "$S3_ACCESS_KEY_ID",
        "access_key_secret": "$S3_ACCESS_KEY_SECRET",
        "bucket_name": "orders/import",
        "region": "us-east-1"
      }
    }
  }'
```

:::
:::{tab-item} 修改用途

类型与字段的完整对应关系和认证分支见[按数据源填写连接信息](create-connector.md#请求体)。修改时注意两点：
- 修改 source_type 时，必须同时传入与新类型匹配的完整 config。
- 只要传入 config，就会整体替换已保存的连接配置。即使只改一两个字段，也要把需要保留的字段一并提交（可先[查看连接器详情](get-connector.md#成功响应)取当前值）。
将 `$CONNECTOR_ID` 和用途替换为实际值。

```bash
curl -X PUT "https://api.moi.matrixorigin.cn/v5/connectors/$CONNECTOR_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "usage_type": [1, 2]
  }'
```

:::
::::

:::::
:::::{tab-item} 参数说明

::::{tab-set}
:class: mo-api-parameter-table

:::{tab-item} 修改名称

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `connector_id` | string | 是 | 要更新的连接器 ID。 |
| `name` | string | 否 | 新连接器名称。 |

:::
:::{tab-item} 修改数据源类型或连接信息

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `connector_id` | string | 是 | 要更新的连接器 ID。 |
| `source_type` | integer | 是 | 新数据源的类型代码；标准 S3 为 `5`。 |
| `config.s3` | object | 是 | 标准 S3 的连接信息。 |
| `config.s3.endpoint` | string | 是 | S3 服务端点。 |
| `config.s3.access_key_id` | string | 是 | 访问密钥 ID。 |
| `config.s3.access_key_secret` | string | 是 | 访问密钥。 |
| `config.s3.bucket_name` | string | 是 | Bucket 名称或路径前缀。 |
| `config.s3.region` | string | 是 | 区域。 |

:::
:::{tab-item} 修改用途

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `connector_id` | string | 是 | 要更新的连接器 ID。 |
| `usage_type` | array of integer | 是 | 新的连接器用途。`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者；也接受整数 `1`、`2`、`3`。不修改用途时不要传本字段，也不要传 `0` 或 `[]`。可选用途取决于数据源，参见[数据源类型说明](../../../../../guides/ai-studio/data-sources/connectors.md#选择数据源类型)。 |

:::
::::

:::::
::::::
:::::::

## 成功响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

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

:::::
::::::
:::::::

## 错误响应

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} 响应示例

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

:::::
:::::{tab-item} 字段说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 错误代码。始终检查该字段；只有 `OK` 才表示更新完成。 |
| `msg` | string | 可读错误信息。 |
| `data` | null | 错误响应中为 `null`。 |

:::::
::::::
:::::::

## 后续操作

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