# 查询连接器列表

列出当前工作区中你有读取权限的连接器。先通过此接口找到连接器 ID，再查询详情、更新、删除或创建数据任务。

```text
GET https://moi.matrixorigin.cn/newmoi/connectors/list
```

## 调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

下方示例使用：

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

## 查询参数

不传查询参数时，接口返回第 1 页的连接器。使用筛选参数缩小结果范围；使用 `page` 和 `page_size` 分页读取结果。

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `name` | string | 否 | 按名称筛选。 |
| `page` | integer | 否 | 页码。默认值为 `1`。 |
| `page_size` | integer | 否 | 每页数量。默认值为 `20`。 |
| `order_by` | string | 否 | 排序字段。未传时按创建时间倒序返回。 |
| `is_desc` | boolean | 否 | 设置 `order_by` 时，是否按降序排序。 |
| `keyword` | string | 否 | 关键字筛选。 |
| `source_type` | integer | 否 | 按单个数据源类型筛选。 |
| `source_type_list` | integer（整数数组） | 否 | 按多个数据源类型筛选；可重复传入。 |
| `status` | string | 否 | 按单个连接器状态筛选。 |
| `status_list` | string（字符串数组） | 否 | 按多个连接器状态筛选；可重复传入。 |
| `usage_type` | integer（整数数组） | 否 | 按连接器用途筛选。 |

## 请求示例

```bash
curl "https://moi.matrixorigin.cn/newmoi/connectors/list?page=1&page_size=20" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

如需按名称筛选，将 `name` 作为查询参数追加到地址中。

## 成功响应

成功时返回 `200`。从 `data.connectors[]` 中取得连接器信息，从 `data.total` 判断共有多少条匹配结果。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "connectors": [
      {
        "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"
          }
        }
      }
    ],
    "total": 1
  }
}
```

响应字段如下。

本文中，类型后的 `[]` 表示数组；字段路径中的 `[]` 表示数组中的每一项。

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

## 读取下一页

根据 `data.total` 和请求时的 `page_size` 计算最后一页，再依次增加 `page`。例如 `total` 为 `41`、`page_size` 为 `20` 时，依次请求第 `1`、`2`、`3` 页。

## 错误响应

```json
{
  "code": "ErrForbidden",
  "msg": "permission denied",
  "data": null
}
```

### 常见 HTTP 错误

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

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `ErrParamInvalid`
  - 查询参数格式无效。
  - 修正参数后重试。
* - `403`
  - `ErrForbidden`
  - 调用者没有读取连接器集合的权限。
  - 检查工作区和连接器授权。
* - `503`
  - `ErrCoreAuthorizeUnavailable`
  - 服务无法完成授权筛选。
  - 稍后重试；不要把空列表视为无连接器。
```

## 后续操作

保存目标连接器的 `id`，再[查询连接器详情](get-connector.md)。要继续选库表时[查看可浏览的连接器](../connector-data-sources/list-structured-data-sources.md)；要浏览文件时[查询文件列表](../connector-files/list-files.md)。