# 获取数据库分类

列出数据库中的分类名称。这里的“分类”对应部分数据库中的 Schema；只有能力接口中 `list_schemas` 为 `true` 的连接器需要执行这一步。

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

## 调用前准备

先[查询连接器数据库](list-databases.md)，准备返回的数据库名称；确认查看可浏览的连接器接口中该条目的 `enabled` 和 `capabilities.list_schemas` 均为 `true`。不支持这一分类层级的连接器跳过此页，直接查询对象。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：要查询的工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$CONNECTOR_ID` 和 `$SOURCE_TYPE`：查看可浏览的连接器接口返回的连接器 ID 和来源类型。
- `$DATABASE`：查询数据库接口返回的 `data.databases[].name`。

## 请求体

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `connector_id` | string | 是 | 已保存的连接器 ID。 |
| `source_type` | string | 是 | 结构化来源类型。 |
| `database` | string | 是 | 由数据库发现接口返回的数据库名称。 |

## 请求示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/connectors/structured/v1/source/schemas" \
  -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\",
    \"database\": \"$DATABASE\"
  }"
```

## 成功响应

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

成功时返回 `200`。

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

响应字段如下。

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.schemas` | object（对象数组） | 数据库分类；不支持该层级的来源可返回空数组。 |
| `data.schemas[].name` | string | 分类名称，后续[查询连接器表](list-tables.md)的 `schema` 使用该值。 |
| `data.schemas[].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`
  - 服务未能列出数据库分类。
  - 保留脱敏错误信息后重试。
```

## 后续操作

选定分类后，带上数据库与分类标识[查询连接器表](list-tables.md)。