数据下载异步任务接口¶
版本说明:本任务接口在 26.30 版本之后完全支持。
该接口根据成员提出的自然语言问题查询数据,将查询结果写入一个或多个 CSV 文件,再打包为 ZIP 文件供调用方下载。任务成功后还会返回本次实际生效的模型、指标、时间范围和业务条件等查询说明,便于调用方确认下载内容。
目录¶
整体流程¶
- 创建任务:提交查询问题及执行该问题的成员
memberUid,获得任务uid。 - 轮询结果:使用任务
uid查询任务详情,直到status变为2(成功)或3(失败)。建议设置合理的轮询间隔,避免连续高频请求。 - 核对查询:任务成功后读取
result.message,或按类别读取result.message_json,确认整个任务实际生效的模型、指标和查询条件。 - 下载文件:使用
result.url下载 ZIP 压缩包。链接为预签名地址,自任务完成起有效期约为 24 小时,建议及时下载并自行保存。
1. 创建数据下载任务¶
请求¶
POST /openapi/v1/async-tasks/
Authorization: "{连接密钥}"
Content-Type: application/json
{
"taskType": 22,
"params": {
"memberUid": "9e823ddce2314f0ba2b2a8a6599a71a1",
"text": "上个月华东区域营业额最高的前 10 个品牌",
"modelScope": "all"
}
}
请求参数¶
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| taskType | int | 是 | 任务类型,固定为 22。 |
| params | object | 是 | 数据下载任务的参数。 |
| params.memberUid | string | 是 | 执行查询的工作区成员 uid。查询权限、语言和数据访问范围均以该成员为准,且连接密钥必须有权访问其工作区。 |
| params.text | string | 是 | 自然语言查询问题,例如“今年 GMV”或“上个月华东区域营业额最高的前 10 个品牌”。 |
| params.modelScope | string | 否 | 模型范围,默认为 selected;传 all 时使用全部有权限的模型,详见下文。 |
模型范围(params.modelScope)¶
版本说明:该参数自服务端 26.37.0 起支持。
modelScope 为可选字符串,仅支持以下值:
| 值 | 行为 |
|---|---|
selected |
默认值,使用成员当前选择的模型;成员未选择模型时,沿用全部有权限模型的规则。省略参数与传入该值等价。 |
all |
本次任务使用成员全部有权限的模型,不受当前模型选择限制。模型、行和列权限仍然生效。 |
该参数只影响本次任务,不修改成员已保存的模型选择,也不会改变后续任务的默认行为。暂不支持指定模型列表。
下载任务在创建时根据该参数生成查询,后台下载继续使用已生成的查询。任务详情中的 params 为内部执行参数,不保证回显 modelScope。
除 selected 和 all 外的值(包括 null、空字符串、ALL、specified、布尔值、数字、数组和对象)都会在创建阶段被拒绝,不创建任务。统一响应示例:
{
"errcode": 400,
"errmsg": "modelScope 参数无效,请使用 \"selected\" 查询当前已选模型,或使用 \"all\" 查询全部有权限的模型"
}
创建成功响应示例(节选)¶
{
"errcode": 200,
"errmsg": "success",
"data": {
"uid": "8c706b8e-fc36-4dd9-902f-ef41da001b09",
"taskType": 22,
"result": null,
"status": 0
}
}
完整响应还会包含 params、creator、createdAt 和 updatedAt,字段定义与获取任务结果相同。data.params 是服务端生成下载文件时使用的执行参数,内容可能随版本调整。调用方应保存 data.uid 并使用它查询任务结果,不应依赖 data.params 的内部结构。任务创建后可能很快进入执行状态,因此创建响应中的 status 也可能已经是 1 或 2。
创建失败¶
任务不会被创建时,接口仍返回统一响应结构,errcode 为 400,errmsg 说明原因。例如:
{
"errcode": 400,
"errmsg": "任务参数缺少 memberUid"
}
常见原因包括缺少 text、缺少 memberUid、工作区成员不存在、连接密钥无权访问该成员所在工作区,或问题无法搜索出有效结果。
2. 获取任务结果¶
通过创建任务接口返回的任务 uid 轮询任务详情。
请求¶
GET /openapi/v1/async-tasks/{async_task_uid}/
Authorization: "{连接密钥}"
响应字段¶
| 参数 | 类型 | 说明 |
|---|---|---|
| errcode | int | OpenAPI 业务状态码。请求成功时为 200。 |
| errmsg | string | OpenAPI 业务状态说明。请求成功时为 success。 |
| data.uid | string | 异步任务 uid。 |
| data.taskType | int | 任务类型,数据下载任务为 22。 |
| data.params | object | 服务端执行参数。属于内部结构,不建议调用方解析或持久依赖。 |
| data.result | object/null | 任务结果。等待中或执行中时通常为空;成功和失败结构见下文。 |
| data.status | int | 任务状态:0 等待中、1 执行中、2 成功、3 失败。 |
| data.creator | int/null | 任务创建者的内部账号 ID。 |
| data.createdAt | string | 任务创建时间,ISO 8601 格式。 |
| data.updatedAt | string | 任务最后更新时间,ISO 8601 格式。 |
当
data.status为2或3时,任务已经结束,可以停止轮询。errcode=200只表示任务详情接口调用成功,任务本身是否成功应以data.status为准。
3. 成功结果说明¶
当 data.status=2 时,data.result 包含以下字段:
| 字段 | 类型 | 说明 |
|---|---|---|
| url | string | ZIP 文件的预签名下载地址,自任务完成起有效期约为 24 小时。 |
| errors | int[] | 下载失败的数据项下标,按服务端生成的数据项从 0 开始计数。空数组表示全部数据项下载成功;部分失败时 ZIP 中只包含成功项。 |
| message | string | 整个任务的业务查询汇总说明。只描述实际生效且可识别的内容,不包含 SQL、内部字段编号、成员数据权限规则或模型内部全局过滤等实现信息。 |
| message_json | object | 与 message 同级的结构化查询说明,按固定英文键分类,值为字符串数组。没有查询说明时为 {};历史结果可能缺少该字段。 |
如果所有数据项都下载失败,任务会进入失败状态,不会返回成功下载地址。
单个查询成功响应示例¶
下面的 params 使用空对象代替内部执行参数,实际响应中该字段可能包含更多内容。
{
"errcode": 200,
"errmsg": "success",
"data": {
"uid": "8c706b8e-fc36-4dd9-902f-ef41da001b09",
"taskType": 22,
"params": {},
"result": {
"url": "https://object-storage.example.com/openapi/8c706b8e.zip?X-Amz-Signature=...",
"errors": [],
"message": "生效模型为「门店销售」;查询指标为「营业额」;分组维度为「品牌」;时间范围为「下单日期」的「上个月」(2026-08-01 至 2026-08-31);维度及其他业务过滤条件为「区域为华东」;排序条件为「营业额降序」;结果数量限制为「前10名」。",
"message_json": {
"models": ["门店销售"],
"measures": ["营业额"],
"dimensions": ["品牌"],
"date_filters": ["「下单日期」的「上个月」(2026-08-01 至 2026-08-31)"],
"filters": ["区域为华东"],
"order": ["营业额降序"],
"limit": ["前10名"]
}
},
"status": 2,
"creator": 10001,
"createdAt": "2026-09-01T17:30:00+08:00",
"updatedAt": "2026-09-01T17:30:08+08:00"
}
}
message 汇总整个任务实际生效的查询信息,由任务生成的所有下载文件共同使用。
message 可能包含的内容¶
服务端根据实际查询结果按需组合下列内容;未生效、无法识别或没有返回的内容会被省略:
| 查询信息 | 中文示例 |
|---|---|
| 生效模型 | 生效模型为「门店销售」 |
| 查询指标 | 查询指标为「营业额」、「退款额」 |
| 分组维度 | 分组维度为「品牌」 |
| 时间范围及时间比较条件 | 时间范围为「下单日期」的「上个月」(2026-08-01 至 2026-08-31) |
| 维度及其他业务过滤条件 | 维度及其他业务过滤条件为「区域为华东」 |
| 指标过滤条件 | 指标过滤条件为「营业额大于1000」 |
| 排序条件 | 排序条件为「营业额降序」 |
| 结果数量限制 | 结果数量限制为「前10名」 |
| 占比等其他业务条件 | 其他业务条件为「品牌营业额占比」 |
对于衍生指标或融合多个模型的查询,说明会保留实际出现在下载结果中的指标,并合并相关来源模型;仅用于计算衍生结果的依赖指标不会被误报为下载结果指标。
查询说明和 CSV 中月份、季度、年份等时间标签使用 memberUid 对应成员的账户语言。英文成员会得到英文说明,例如:
The effective model was "Store Sales"; the queried measures were "Revenue"; the time range was "Order Date": "last month" (2026-08-01 to 2026-08-31).
message_json 字段说明¶
message_json 提供与 message 等价的业务说明,使用固定英文键名,所有值均为字符串数组(string[]),去重并保留首次出现的顺序。没有生效内容的键会被省略;没有查询说明时返回空对象 {}。数组中的文本与 message 使用相同的成员账户语言,键名不随语言变化。
| 键 | 说明 | 中文示例 |
|---|---|---|
| models | 生效模型名称 | ["门店销售"] |
| measures | 实际返回指标 | ["营业额", "退款额"] |
| dimensions | 分组维度 | ["品牌"] |
| date_filters | 时间维度、原始时间表达、解析日期及时间比较条件 | ["「下单日期」的「上个月」(2026-08-01 至 2026-08-31)"] |
| filters | 维度及其他业务过滤条件 | ["区域为华东"] |
| having | 指标过滤条件 | ["营业额大于1000"] |
| order | 排序字段和方向 | ["营业额降序"] |
| limit | 结果数量限制 | ["前10名"] |
| proportion | 占比等其他业务条件 | ["品牌营业额占比"] |
该对象用于分类读取和展示业务说明,不是可重新执行的查询表达式,不包含 SQL、内部字段编号、成员数据权限规则或模型内部全局过滤。调用方无需解析 message 文本,也不应依赖数组元素内部的文本格式进行查询。
上面的英文查询说明对应的结构化对象为:
{
"models": ["Store Sales"],
"measures": ["Revenue"],
"date_filters": ["\"Order Date\": \"last month\" (2026-08-01 to 2026-08-31)"]
}
多个查询及部分失败示例¶
一个问题可能生成多个可下载数据项。message 将全部查询说明与各下载结果实际返回的指标合并成任务级业务描述。例如原始数据项 0、1、2 中第 1 项下载失败时:
{
"url": "https://object-storage.example.com/openapi/4ccbb030.zip?X-Amz-Signature=...",
"errors": [1],
"message": "生效模型为「销售模型」、「库存模型」;查询指标为「营业额」、「库存量」。",
"message_json": {
"models": ["销售模型", "库存模型"],
"measures": ["营业额", "库存量"]
}
}
此时 ZIP 文件包含原始下标 0 和 2 对应的 CSV 文件,errors 记录失败项的原始下标。message 和 message_json 表示整个任务的查询内容,多个模型和下载文件共用一份说明,部分下载失败不会裁剪说明。文件级下载结果由 errors 表达,不能将说明数组下标与文件下标对应。
ZIP 文件说明¶
- 每个成功的数据项生成一个 CSV 文件,多个 CSV 文件会放在同一个 ZIP 压缩包中。
- CSV 表头和数据会使用平台的展示格式;时间标签根据成员账户语言格式化。
- 单次下载的数据行数受工作区、客户级配置或系统最大下载行数限制。
- 文件名由查询标题生成;存在多个 CSV 时,后续文件名会增加序号。
历史任务兼容¶
- 在支持结构化说明的版本部署前已创建、部署后才执行的任务,如果缺少结构化说明参数,成功时返回
message_json: {},原有message保持不变,不会从文本反推结构化内容。 - 已完成的历史任务结果不会回填,可能没有
message_json字段;调用方应兼容字段缺失或空对象。
在支持查询说明的版本部署前已创建、但部署后才开始执行的历史任务可能没有生成查询说明所需的内部参数。这类任务成功时仍会正常返回 url 和 errors,message 为:
数据查询和下载已完成。
4. 异常与失败结果¶
任务执行失败¶
当 data.status=3 时,data.result.message 为失败原因,且不会提供可用的 result.url。例如全部数据项下载失败:
{
"errcode": 200,
"errmsg": "success",
"data": {
"uid": "8c706b8e-fc36-4dd9-902f-ef41da001b09",
"taskType": 22,
"params": {},
"result": {
"message": "下载数据失败, 请检查 query 日志"
},
"status": 3,
"creator": 10001,
"createdAt": "2026-09-01T17:30:00+08:00",
"updatedAt": "2026-09-01T17:30:08+08:00"
}
}
任务也可能因 ZIP 打包失败或文件上传失败而进入失败状态。调用方应向最终用户展示合适的失败提示,并记录任务 uid 以便排查。
任务不存在¶
使用无效或不存在的任务 uid 查询时,响应示例如下:
{
"errcode": 400,
"errmsg": "任务不存在"
}
附录:任务状态说明¶
| 状态码 | 说明 | 调用方建议 |
|---|---|---|
| 0 | 等待中 | 继续轮询。 |
| 1 | 执行中 | 继续轮询。 |
| 2 | 成功 | 读取 result.message,并通过 result.url 下载。 |
| 3 | 失败 | 停止轮询,读取 result.message 获取失败原因。 |