Open API 开放接口
这是什么
Open API 让你可以通过标准 HTTP 接口调用 Analytics Agent 的数据分析能力。你只需发送一个自然语言问题，系统会自动完成数据查询、指标计算、知识检索和可视化生成，最终返回结构化的分析结果。
简单来说：把 Analytics Agent 的对话能力变成了一个可编程的接口。
适用场景
| 场景 | 说明 |
|---|
| 嵌入内部系统 | 在你的业务系统中集成数据问答能力，用户通过自然语言提问，后台调用 API 异步获取分析结果并展示 |
| 自动化工作流 | 将 API 接入自动化流程中，定时或按事件触发数据分析，获取结构化结果后由你的系统进行后续处理（如生成报告、写入数据库等） |
| 自研应用集成 | 在自研的 BI 工具或数据中台中调用 Agent 的分析能力，获取指标计算结果和 SQL，再由你的应用完成展示和渲染 |
你能得到什么
调用 API 后，你会获得与在 Analytics Agent 页面中提问一样的分析过程和结果，包括：
- 知识检索结果 — Agent 查阅知识库后返回的业务规则和定义条目
- 指标计算结果 — 语义层 DSL（metricDsl）和物理层 DSL（physicalMetricDsl）
- SQL 语句 — Agent 生成的查询 SQL（可在你的系统中执行以获取数据）
- 图表元信息 — 图表类型、列定义和对应 SQL（需你的应用自行执行 SQL 并渲染图表）
- 分析总结 — Markdown 格式的文字总结，包含数据解读
注意：API 返回的是分析过程数据和结构化结果，图表渲染、报告排版等展示层工作需要你的应用自行完成。
5 分钟快速体验
完整的端到端示例请参考 → Quick Start 快速上手
核心流程只有 4 步：
① 获取 Token → ② 创建会话 → ③ 提问 → ④ 轮询拿结果
最简代码（Python）：
import requests, time
BASE = "https://api.clickzetta.com/clickzetta-campaign-data" # 国内 SaaS 环境
SECRET_KEY = "your_app_secret_key"
# ① 获取 Token
token = requests.get(f"{BASE}/open/api/v1/appSecretKey/generateAuthToken",
params={"appSecretKey": SECRET_KEY}).json()["data"]["token"]
# ② 创建会话
session_id = requests.post(f"{BASE}/open/session/safe_new",
params={"tenantId": 10, "userId": 1, "loginToken": token},
json={"tenantId": 10, "userId": 1, "domainId": 106,
"title": "API 测试", "loginToken": token}
).json()["data"]
# ③ 提问
question_id = requests.post(f"{BASE}/open/text2insight/query",
params={"tenantId": 10, "userId": 1, "loginToken": token},
json={"tenantId": 10, "userId": 1, "domainId": 106,
"sessionId": session_id, "msg": "过去6个月各区域销售额趋势", "loginToken": token}
).json()["data"]["questionId"]
# ④ 轮询拿结果
while True:
result = requests.post(f"{BASE}/open/safe_question_poll",
params={"tenantId": 10, "userId": 1, "loginToken": token},
json={"tenantId": 10, "userId": 1, "domainId": 106,
"questionId": question_id, "loginToken": token}
).json()
responses = result["data"]["responses"]
last_type = responses[-1].get("dataType", "")
if last_type in ("finish", "finish_stop", "error"):
break
time.sleep(2)
# 打印最终结果
for r in responses:
print(f"[{r.get('dataType')}] {r.get('message', '')[:80]}")
API 接口列表
更多指南
