# 查看可浏览的连接器

列出当前工作区中可浏览数据库、表或集合的连接器，并显示每个连接器支持的查询操作。选择可用连接器后，再查询数据库、Schema、对象和字段结构。

```text
GET https://moi.matrixorigin.cn/newmoi/connectors/structured/v1/sources
```

## 调用前准备

准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。响应仅包含你有使用权限的连接器。

下方示例使用：

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

### 支持的来源与发现路径

当前结构化发现支持 Hive、MySQL、SQL Server、Oracle、PostgreSQL 和 MongoDB。下表说明各类型的对象发现路径；实际调用时，仍以响应中标记为 `true` 的能力为准。

| 连接器类型 | `source_type` | 发现路径 | 对象标识 |
| --- | --- | --- | --- |
| Hive | `SOURCE_TYPE_HIVE` | 数据库 → 表 → 表结构 | `table` |
| MySQL | `SOURCE_TYPE_MYSQL` | 数据库 → 表 → 表结构 | `table` |
| SQL Server | `SOURCE_TYPE_SQLSERVER` | 数据库 → Schema → 表 → 表结构 | `schema`、`table` |
| Oracle | `SOURCE_TYPE_ORACLE` | 数据库 → Schema → 表 → 表结构 | `schema`、`table` |
| PostgreSQL | `SOURCE_TYPE_POSTGRESQL` | 数据库 → Schema → 表 → 表结构 | `schema`、`table` |
| MongoDB | `SOURCE_TYPE_MONGODB` | 数据库 → 集合 → 表结构 | `collection` |

MatrixOne 虽可作为数据库连接器创建，但当前不会通过此接口返回，不能使用本组接口查询其数据库、表或表结构。

## 请求示例

```bash
curl "https://moi.matrixorigin.cn/newmoi/connectors/structured/v1/sources" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

## 成功响应

本文中，字段路径中的 `[]` 表示数组中的每一项。例如，`data.sources[].connector_id` 表示 `data.sources` 数组中每一项的 `connector_id` 字段。

成功时返回 `200`。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "sources": [
      {
        "connector_id": "conn_01",
        "connector_name": "orders_mysql",
        "source_type": "SOURCE_TYPE_MYSQL",
        "enabled": true,
        "disabled_reason": "",
        "capability_profile_hash": "capability-profile-hash",
        "capabilities": {
          "list_databases": true,
          "list_schemas": false,
          "list_tables": true,
          "describe_schema": true,
          "sample": false,
          "backfill_start_resolve": false,
          "hive_partitions": false,
          "mongodb_flatten": false
        }
      }
    ]
  }
}
```

响应字段如下。

类型后的 `[]` 表示数组。例如，`object[]` 是对象数组。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.sources` | object（对象数组） | 当前工作区中可用于或可评估结构化发现的连接器。 |
| `data.sources[].connector_id` | string | 连接器 ID。后续发现接口使用该 ID。 |
| `data.sources[].connector_name` | string | 连接器名称。 |
| `data.sources[].source_type` | string | 结构化来源类型。 |
| `data.sources[].enabled` | boolean | 是否可继续调用该条目对应的发现接口。仅可用条目进入后续步骤。 |
| `data.sources[].disabled_reason` | string | 不可用时的原因。值为 `STRUCTURED_LOAD_MONGODB_DISABLED` 时，当前工作区不能使用 MongoDB 结构化发现；该条目不应继续调用后续接口。 |
| `data.sources[].capability_profile_hash` | string | 当前能力描述的摘要。能力配置变化时，该值可能变化；创建结构化导入任务时，将该值填入 `consistency_contract.capability_profile_hash`。能力信息不可用时可能省略。 |
| `data.sources[].capabilities` | object | 当前连接器可调用的结构化来源能力。只对标记为 `true` 的能力发起对应请求。 |
| `data.sources[].capabilities.list_databases` | boolean | 是否可查询数据库。 |
| `data.sources[].capabilities.list_schemas` | boolean | 是否可查询数据库 Schema。 |
| `data.sources[].capabilities.list_tables` | boolean | 是否可查询表或集合。 |
| `data.sources[].capabilities.describe_schema` | boolean | 是否可查询表或集合的字段结构。 |
| `data.sources[].capabilities.sample` | boolean | 是否支持来源数据采样。 |
| `data.sources[].capabilities.backfill_start_resolve` | boolean | 是否支持解析结构化导入的回填起点。 |
| `data.sources[].capabilities.hive_partitions` | boolean | 是否支持查询 Hive 分区。 |
| `data.sources[].capabilities.mongodb_flatten` | boolean | 是否支持 MongoDB 的扁平化映射能力。 |

## 错误响应

```json
{
  "code": "STRUCTURED_CONNECTOR_SERVICE_UNAVAILABLE",
  "msg": "service unavailable",
  "data": null
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 30 28 30

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `501`
  - `STRUCTURED_CONNECTOR_SERVICE_UNAVAILABLE`
  - 当前服务未提供结构化数据源发现。
  - 暂时无法使用本组接口。
* - `200`
  - `STRUCTURED_LOAD_FEATURE_DISABLED`
  - 当前工作区未启用结构化数据源功能。
  - 检查该工作区是否可使用此功能。
* - `500`
  - `ErrServer`
  - 服务未能列出可用连接器。
  - 保留脱敏错误信息后重试。
```

## 后续操作

选定已保存连接器后，用其 ID [查询连接器数据库](list-databases.md)。仅当该连接器在列表中的能力标记支持列举数据库时继续。