# 查询连接器表

列出结构化数据源中的表或集合。响应中的 `object_kind` 用于判断对象类型。

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

## 调用前准备

按以下顺序准备查询条件：

1. [查询连接器数据库](list-databases.md)，准备数据库名称。
2. 查看可浏览的连接器，确认目标条目的 `enabled` 和 `capabilities.list_tables` 均为 `true`。
3. 如果 `capabilities.list_schemas` 为 `true`，先[获取数据库分类](list-schemas.md)并传入返回的分类名称；否则省略 `schema`。

下方示例使用：

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

## 请求体

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `connector_id` | string | 是 | 已保存的连接器 ID。 |
| `source_type` | string | 是 | 结构化来源类型。 |
| `database` | string | 是 | 数据库名称。 |
| `schema` | string | 否 | 数据库分类名称；仅在来源具有该分类层级时提供。 |

## 请求示例

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

来源具有该分类层级时，在请求体中加入 `"schema":"$SCHEMA"`。

## 成功响应

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

成功时返回 `200`。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "objects": [
      {
        "database": "sales",
        "schema": "public",
        "table": "orders",
        "display_name": "orders",
        "object_kind": "table"
      }
    ],
    "endpoint_results": []
  }
}
```

响应字段如下。

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

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.objects` | object（对象数组） | 当前数据库和分类下的结构化对象。 |
| `data.objects[].database` | string | 对象所属数据库，[查询连接器表结构](get-table-schema.md)时原样传入。 |
| `data.objects[].schema` | string | 对象所属数据库分类；不适用时可能省略。需要时原样传入表结构查询。 |
| `data.objects[].table` | string | 表名称；按对象类型返回，表结构查询时原样传入。 |
| `data.objects[].collection` | string | 集合名称；按对象类型返回，表结构查询时原样传入。 |
| `data.objects[].display_name` | string | 用于展示的对象名称。 |
| `data.objects[].object_kind` | 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`
  - 服务未能列出对象。
  - 保留脱敏错误信息后重试。
```

## 后续操作

选定对象后，带上对象标识[查询连接器表结构](get-table-schema.md)。