# 查询连接器数据库

列出一个结构化连接器可访问的数据库。先查看可浏览的连接器，从可用条目中取得连接器 ID 和来源类型。

```text
POST https://moi.matrixorigin.cn/newmoi/connectors/structured/v1/source/databases
```

## 调用前准备

先[查看可浏览的连接器](list-structured-data-sources.md)，选择 `enabled` 为 `true` 且 `capabilities.list_databases` 为 `true` 的条目。准备有目标工作区访问权限的个人访问令牌和目标工作区 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：要查询的工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$CONNECTOR_ID` 和 `$SOURCE_TYPE`：查看可浏览的连接器接口返回的连接器 ID 和来源类型；两者必须来自同一条返回记录。

## 请求体

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `connector_id` | string | 是 | 已保存的连接器 ID。 |
| `source_type` | string | 是 | 结构化来源类型。 |

## 请求示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/connectors/structured/v1/source/databases" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d "{
    \"connector_id\": \"$CONNECTOR_ID\",
    \"source_type\": \"$SOURCE_TYPE\"
  }"
```

## 成功响应

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

成功时返回 `200`。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "databases": [
      {
        "name": "sales",
        "display_name": "sales"
      }
    ],
    "endpoint_results": []
  }
}
```

响应字段如下。

类型后的 `[]` 表示数组。例如，`string[]` 是字符串数组。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.databases` | object（对象数组） | 数据库引用。 |
| `data.databases[].name` | string | 数据库名称，后续请求的 `database` 使用该值。 |
| `data.databases[].display_name` | string | 用于展示的数据库名称。 |
| `data.endpoint_results` | JSON[] | 当前返回空数组。 |

## 错误响应

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

### 常见 HTTP 错误

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

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `ErrParamInvalid`
  - 缺少字段，或 `source_type` 与连接器不匹配。
  - 使用同一条能力记录返回的 `connector_id` 和 `source_type`。
* - `501`
  - `STRUCTURED_CONNECTOR_SERVICE_UNAVAILABLE`
  - 当前服务未提供结构化数据源发现。
  - 暂时无法使用本组接口。
* - `200`
  - `STRUCTURED_LOAD_FEATURE_DISABLED`
  - 当前工作区未启用结构化数据源功能。
  - 检查该工作区是否可使用此功能。
* - `200`
  - `STRUCTURED_LOAD_MONGODB_DISABLED`
  - 当前工作区未启用 MongoDB 结构化发现。
  - 不要继续调用该 MongoDB 连接器的发现接口。
* - `500`
  - `ErrServer`
  - 服务未能列出数据库。
  - 保留脱敏错误信息后重试。
```

## 后续操作

若所选连接器的 `capabilities.list_schemas` 为可用，继续[获取数据库分类](list-schemas.md)；否则直接[查询连接器表](list-tables.md)。请求时带上本步取得的数据库标识。