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

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

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

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

Authorization: Bearer YOUR_API_KEY

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

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

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：

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

{
  "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 由服务端决定，不接受调用方直接传上来的任意值，避免被用来扩大数据范围。