# 查询连接器详情

根据连接器 ID 读取一个已保存连接器。用此接口确认当前名称、状态、用途和关联任务；更新或删除前也应先读取详情。

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

## 调用前准备

准备有目标工作区访问权限的个人访问令牌、目标工作区 ID，以及列表或创建接口返回的连接器 ID。

下方示例使用：

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

## 请求体

请求体只需要连接器 ID。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `id` | string | 是 | 连接器 ID。 |

## 请求示例

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

## 成功响应

成功时返回 `200`。为保护凭据，响应可能省略配置中的敏感字段；字段未返回不表示已保存的凭据被清空。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "conn_01",
    "name": "s3-orders-import",
    "source_type": 5,
    "created_at": 1735632000,
    "updated_at": 1735718400,
    "status": "active",
    "username": "reader",
    "related_task_ids": ["task_01"],
    "usage_type": [1],
    "config": {
      "s3": {
        "endpoint": "https://s3.example.com",
        "bucket_name": "orders",
        "region": "us-east-1"
      }
    }
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.id` | string | 连接器 ID。 |
| `data.name` | string | 连接器名称。 |
| `data.source_type` | integer | 数据源类型代码。 |
| `data.created_at` | integer | 创建时间的 Unix 时间戳。 |
| `data.updated_at` | integer | 更新时间的 Unix 时间戳。 |
| `data.status` | string | 连接器当前状态。 |
| `data.username` | string | 配置中的用户名。 |
| `data.related_task_ids` | string（字符串数组） | 关联的数据任务 ID。 |
| `data.usage_type` | integer（整数数组） | 已保存的用途列表，由服务端从位掩码展开。示例：`[1]` 仅导入，`[2]` 仅导出，`[1, 2]` 同时支持两者。 |
| `data.config` | object | 类型专属连接配置；顶层键与完整字段见[创建连接器的类型专属配置字段](create-connector.md#类型专属配置字段)，响应中的字段以实际数据源类型为准。 |

## 错误响应

```json
{
  "code": "ErrParam",
  "msg": "invalid parameter",
  "data": null
}
```

### 常见 HTTP 错误

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

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `ErrParam`
  - 请求体缺少 `id`。
  - 传入连接器 ID。
* - `500`
  - `ErrServer`
  - 服务未能读取连接器。
  - 稍后重试。
```

## 后续操作

需要改配置时[更新连接器](update-connector.md)。用途含导入且连接器支持文件列举时，可[查询文件列表](../connector-files/list-files.md)；要浏览库表时[查看可浏览的连接器](../connector-data-sources/list-structured-data-sources.md)。