# 用 REST API 把问数接进业务系统

使用 REST API 将数据问答接入业务系统。

AskTable 的接口统一挂在部署实例的 `/v1` 下，适合应用开发团队把问数接进业务系统、门户、服务流程或自动化平台。最少只要一个接口就能跑通：`POST /v1/integration/query`，传数据源和问题，拿回自然语言回答。

## 开始前

- 一个 AskTable 部署实例，以及它的对外地址。
- 一个项目 API-Key。只提问用 `asker` 类型；要调管理类接口（建数据源、改权限、删智能体）用 `admin` 类型。
- 创建位置：左侧主导航 → 「设置」 → 「API-Key」 → 「创建 API-KEY」。完整值只在创建时显示一次。
- 至少一个状态可用的数据源，以及它的 ID（形如 `ds_xxxxxxxx`）。
- 文档入口：底部头像 → 「文档」 → 「REST API」，直接打开该实例的 Redoc。

## 操作步骤

**确认接口根地址和文档地址**

假设 AskTable 地址是 `https://asktable.example.com`：

| 用途           | 地址                                          |
| ------------ | ------------------------------------------- |
| API 根路径      | `https://asktable.example.com/v1`           |
| 交互式文档（Redoc） | `https://asktable.example.com/v1/redoc`     |
| Swagger UI   | `https://asktable.example.com/v1/docs`      |
| OpenAPI 描述文件 | `https://asktable.example.com/openapi.json` |

接口和字段以当前实例的 Redoc 为准，不同版本可能有增减。

**带上认证头**

所有业务接口都用同一个请求头：

```text
Authorization: Bearer YOUR_API_KEY
```

`asker` 类型的 Key 只能走问数类接口（如 `POST /v1/integration/query`）；`admin` 类型才能调管理类接口。

**发起一次提问**

`POST /v1/integration/query` 是稳定的提问入口，成功返回 HTTP 201。`datasource_ids` 至少给一个，`question` 上限 4096 个字符：

```bash
curl -X POST 'https://asktable.example.com/v1/integration/query' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "datasource_ids": ["ds_xxxxxxxx"],
    "question": "你的数据问题"
  }'
```

需要按角色限制数据范围时，加上 `role_id` 和 `role_variables`：

```json
{
  "datasource_ids": ["ds_xxxxxxxx"],
  "role_id": "role_xxxxxxxx",
  "role_variables": { "dept_id": "D001" },
  "question": "你的数据问题"
}
```

**读返回体**

```json
{
  "conversation_id": "00000000-0000-0000-0000-000000000000",
  "answer": "自然语言回答，失败时为 null",
  "status": "success"
}
```

`status` 只有 `success` 和 `failed` 两个值。`conversation_id` 用于追溯这次调用，可以拿它到「所有对话」里打开同一条会话继续看。

**按需扩展到其他资源接口**

同一个 `/v1` 根下还有数据源、数据智能体、技能、角色、策略、对话、数据看板、画卷、模型组等资源接口。能调哪些由 Key 类型和项目权限决定，具体路径以 Redoc 为准。

**上生产前收口**

1. 每个应用或环境用独立的项目 API-Key，不共用管理员 Key。
2. 只在服务端调用，不要把 Key 放进浏览器、移动端或 iframe 页面。
3. 给请求设超时和重试上限，区分认证失败、权限拒绝、参数错误、数据源未就绪和服务超时。
4. 业务日志里记调用方、项目、时间、耗时、HTTP 状态和 `conversation_id`，不要记完整问题里的敏感数据。
5. `role_id` 和 `role_variables` 由服务端决定，不接受调用方直接传上来的任意值，避免被用来扩大数据范围。

## 关键约束

| 项目                                | 值或默认                               | 在哪里改                     |
| --------------------------------- | ---------------------------------- | ------------------------ |
| API 根路径                           | `/v1`                              | 无界面开关                    |
| 文档地址                              | `<你的站点>/v1/redoc`、`<你的站点>/v1/docs` | 底部头像 → 「文档」 → 「REST API」 |
| 认证头                               | `Authorization: Bearer <API-Key>`  | 调用方                      |
| `POST /v1/integration/query` 所需权限 | `priv_asker`（`asker` 类型 Key 即可）    | 「设置」 → 「API-Key」         |
| `datasource_ids`                  | 必填，至少一个                            | 请求体                      |
| `question`                        | 必填，最多 4096 个字符                     | 请求体                      |
| `role_id`                         | 选填，不传就不做权限过滤                       | 请求体                      |
| 成功状态码                             | 201                                | 无界面开关                    |
| `status` 取值                       | `success` 或 `failed`               | 响应体                      |
| 项目 API-Key 数量                     | 每个项目最多 10 个                        | 「设置」 → 「API-Key」         |

## 出问题怎么判断

| 现象                                               | 判定条件                            | 处理                                                           |
| ------------------------------------------------ | ------------------------------- | ------------------------------------------------------------ |
| 返回 HTTP 401，`code` 是 `AUTH_ERROR`                | Key 缺失、拼错或已删除                   | 重新创建项目 API-Key；确认请求头格式是 `Authorization: Bearer YOUR_API_KEY` |
| 返回 HTTP 403，`code` 是 `PERMISSION_DENIED`         | 用的是 `asker` Key 调了管理类接口，或项目角色不够 | 管理类调用换 `admin` Key；确认 Key 属于目标项目                             |
| 返回 HTTP 404，`code` 是 `DATASOURCE_NOT_FOUND`      | `datasource_ids` 里的 ID 在项目里不存在  | 到「数据源」页复制正确的 ID                                              |
| 返回 HTTP 400，`code` 是 `DATASOURCE_META_NOT_READY` | 数据源元数据还没就绪，`message` 里带当前状态     | 等同步完成，或到「数据源」页手动触发同步                                         |
| 返回 HTTP 422，`code` 是 `VALIDATION_ERROR`          | `message` 里逐条列出字段与原因            | 按字段改：`datasource_ids` 不能为空、`question` 不超 4096 字符             |
| `status` 是 `failed`，`answer` 是 `null`            | HTTP 状态正常但分析没跑完                 | 用 `conversation_id` 到「所有对话」里打开这条会话看原因；多为数据源或模型问题             |
| 拿返回的 `conversation_id` 打不开对话                     | 该 ID 属于别的项目，或会话已被删              | 确认 Key 与项目一致；`conversation_id` 不能跨项目使用                       |
| 接口地址报 404                                        | 请求路径少了或多了 `/v1` 前缀              | 单次提问的正确路径是 `POST /v1/integration/query`                      |

## 下一步

- 让 AI 客户端自己发现并调用这些能力：[MCP](https://docs.asktable.com/integrations/mcp)
- 在终端或脚本里直接操作：[命令行工具](https://docs.asktable.com/integrations/cli)
- 在扣子里配成插件给机器人用：[接入扣子 Coze](https://docs.asktable.com/integrations/coze)