Open API Quick Start 快速上手
本文档帮助你在 5 分钟内完成第一次 API 调用，从提问到拿到分析结果。
前提条件
在开始之前，你需要准备以下信息：
| 准备项 | 说明 | 获取方式 |
|---|
| API 基础地址 | 接口请求的 Base URL | 见下方说明 |
| appSecretKey | 应用密钥，用于获取认证 Token | 管理员在用户管理页面生成 |
| tenantId | 租户 ID | Settings 配置页查看 |
| userId | 用户 ID | Settings 配置页查看 |
| domainId | 分析域 ID | 分析域设置页 URL 中获取 |
API 基础地址（Base URL）
| 环境 | Base URL |
|---|
| 国内 SaaS | https://api.clickzetta.com/clickzetta-campaign-data
https://api.clickzetta.com/clickzetta-campaign-data |
| 海外版（新加坡） | https://ap-southeast-1-alicloud.api.singdata.com/clickzetta-campaign-data
https://ap-southeast-1-alicloud.api.singdata.com/clickzetta-campaign-data |
| 私有化部署（OP） | 请联系对接人获取，每个环境不同 |
获取 appSecretKey
进入 管理 → 用户管理，选择对应用户，点击编辑，在「App Secret Key」区域点击 + 生成Key 即可。
获取 tenantId 和 userId
点击左下角头像，进入 Settings 配置页：
在配置页中可以看到 Tenant ID 和 User ID：
获取 domainId
在分析域卡片上，点击设置按钮（齿轮图标）：
进入设置页后，查看浏览器地址栏 URL，末尾的数字即为 domainId：
完整流程（curl 版）
第一步：获取 Token
详细参数见 → GenerateAuthToken
curl "https://api.clickzetta.com/clickzetta-campaign-data/open/api/v1/appSecretKey/generateAuthToken?appSecretKey=YOUR_SECRET_KEY"
返回：
{
"success": true,
"data": {
"token": "eyJhbGciOiJIUzI1NiJ9..."
}
}
记下
data.token
data.token
，后续所有请求都需要用到。
第二步：创建会话（可选）
详细参数见 → CreateSession
如果你已有 sessionId，可跳过这一步。
curl -X POST "https://api.clickzetta.com/clickzetta-campaign-data/open/session/safe_new?tenantId=YOUR_TENANT_ID&userId=YOUR_USER_ID&loginToken=YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"tenantId": YOUR_TENANT_ID,
"userId": YOUR_USER_ID,
"domainId": YOUR_DOMAIN_ID,
"title": "我的第一次 API 调用",
"loginToken": "YOUR_TOKEN"
}'
返回：
{
"success": true,
"data": 4729
}
data
data
就是你的
sessionId
sessionId
。
第三步：提问
详细参数见 → Text2InsightQuery
curl -X POST "https://api.clickzetta.com/clickzetta-campaign-data/open/text2insight/query?tenantId=YOUR_TENANT_ID&userId=YOUR_USER_ID&loginToken=YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"tenantId": YOUR_TENANT_ID,
"userId": YOUR_USER_ID,
"domainId": YOUR_DOMAIN_ID,
"sessionId": YOUR_SESSION_ID,
"msg": "给我看下过去6个月各区域的销售额趋势",
"loginToken": "YOUR_TOKEN"
}'
返回：
{
"success": true,
"data": {
"questionId": 34339,
"sessionId": 4729,
"status": "running"
}
}
记下
data.questionId
data.questionId
。
第四步：轮询结果
详细参数见 → SafeQuestionPoll
每隔 2 秒调用一次，直到最后一条消息的
dataType
dataType
为
finish
finish
、
finish_stop
finish_stop
或
error
error
。
curl -X POST "https://api.clickzetta.com/clickzetta-campaign-data/open/safe_question_poll?tenantId=YOUR_TENANT_ID&userId=YOUR_USER_ID&loginToken=YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"tenantId": YOUR_TENANT_ID,
"userId": YOUR_USER_ID,
"domainId": YOUR_DOMAIN_ID,
"questionId": YOUR_QUESTION_ID,
"loginToken": "YOUR_TOKEN"
}'
当分析完成时，返回中会包含完整的
responses
responses
数组。关于如何解读这些返回内容，请参考
理解返回结果。
完整流程（Python 版）
import requests
import time
import json
# === 配置 ===
BASE_URL = "https://api.clickzetta.com/clickzetta-campaign-data" # 国内 SaaS 环境
APP_SECRET_KEY = "your_app_secret_key"
TENANT_ID = 10
USER_ID = 1
DOMAIN_ID = 106
# === 第一步：获取 Token ===
resp = requests.get(
f"{BASE_URL}/open/api/v1/appSecretKey/generateAuthToken",
params={"appSecretKey": APP_SECRET_KEY}
)
token = resp.json()["data"]["token"]
print(f"✓ 获取 Token 成功")
# === 第二步：创建会话 ===
resp = requests.post(
f"{BASE_URL}/open/session/safe_new",
params={"tenantId": TENANT_ID, "userId": USER_ID, "loginToken": token},
json={"tenantId": TENANT_ID, "userId": USER_ID, "domainId": DOMAIN_ID,
"title": "API Quick Start", "loginToken": token}
)
session_id = resp.json()["data"]
print(f"✓ 创建会话成功，sessionId = {session_id}")
# === 第三步：提问 ===
resp = requests.post(
f"{BASE_URL}/open/text2insight/query",
params={"tenantId": TENANT_ID, "userId": USER_ID, "loginToken": token},
json={"tenantId": TENANT_ID, "userId": USER_ID, "domainId": DOMAIN_ID,
"sessionId": session_id, "msg": "给我看下过去6个月各区域的销售额趋势", "loginToken": token}
)
question_id = resp.json()["data"]["questionId"]
print(f"✓ 提问成功，questionId = {question_id}")
# === 第四步：轮询结果 ===
print("⏳ 等待分析完成...")
poll_count = 0
max_polls = 180 # 最多轮询 180 次（360 秒）
while poll_count < max_polls:
time.sleep(2)
poll_count += 1
resp = requests.post(
f"{BASE_URL}/open/safe_question_poll",
params={"tenantId": TENANT_ID, "userId": USER_ID, "loginToken": token},
json={"tenantId": TENANT_ID, "userId": USER_ID, "domainId": DOMAIN_ID,
"questionId": question_id, "loginToken": token}
)
data = resp.json()["data"]
responses = data.get("responses", [])
if not responses:
continue
last_type = responses[-1].get("dataType", "")
if last_type in ("finish", "finish_stop", "error"):
print(f"✓ 分析完成（轮询 {poll_count} 次）")
break
# === 展示结果 ===
print("\n" + "=" * 60)
print("分析结果：")
print("=" * 60)
for i, r in enumerate(responses):
data_type = r.get("dataType", "unknown")
if data_type == "summary":
# 分析总结
summary = r.get("modelRes", {}).get("data", {}).get("summaryData") or r.get("message", "")
print(f"\n📊 分析总结：\n{summary}")
elif data_type == "metric":
# 指标计算
message = r.get("message", "")
print(f"\n📈 指标：{message}")
elif data_type == "echarts_plus":
# 图表
message = r.get("message", "")
sql = r.get("modelRes", {}).get("data", {}).get("calculateSql", "")
print(f"\n📉 图表：{message}")
if sql:
print(f" SQL: {sql[:100]}...")
elif data_type == "error":
print(f"\n❌ 错误：{r.get('message', '')}")
运行效果
执行上面的 Python 脚本，你会看到类似这样的输出：
✓ 获取 Token 成功
✓ 创建会话成功，sessionId = 4729
✓ 提问成功，questionId = 34339
⏳ 等待分析完成...
✓ 分析完成（轮询 36 次）
============================================================
分析结果：
============================================================
📈 指标：Metric: 过去6个月各区域总销售额
📉 图表：各区域销售额趋势 (2025.07-2026.01)
SQL: SELECT region AS 区域, month AS 月份, SUM(sales) AS 销售额 FROM ...
📊 分析总结：
**各区域销售额趋势分析：**
- 华东区域持续领先，占总销售额 42%
- 华南区域增速最快，环比增长 15%
...
下一步
