预测卡片异步任务接口¶
版本说明:本任务接口自 v25.15.0 版本起引入
该接口用于获取预测卡片结果,支持自定义预测参数和时间范围。
目录¶
整体流程¶
使用预测卡片接口的典型流程如下:
- 创建任务:调用创建接口,传入问题和预测参数,获得任务 uid
- 轮询结果:使用任务 uid 轮询获取结果接口,直到任务完成
- 解析结果:任务成功后,获取预测数据并展示
1. 创建预测任务¶
请求方式¶
POST /openapi/v1/async-tasks/
Authorization: "{连接密钥}"
请求参数¶
{
"taskType": 13,
"params": {
"memberUid": "{memberUid}",
"text": "{text}",
"confidenceInterval": 0.95,
"forecastRange": ["2025-01-01", "2025-02-01"],
"trainRange": ["2024-01-01", "2025-02-01"]
}
}
参数说明¶
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| taskType | int | 是 | 任务类型,固定值 13 代表预测任务 |
| memberUid | string | 是 | 工作区中成员的 uid,需放置在请求体内 |
| text | string | 是 | 成员提出的问题,例如 "今年GMV",需放置在请求体内 |
| confidenceInterval | float | 否 | 置信区间,默认值为 0.95 |
| forecastRange | list | 是 | 预测时间范围,长度为 2,分别为开始日期与结束日期 |
| trainRange | list | 是 | 训练时间范围,长度为 2,分别为开始日期与结束日期 |
返回结果¶
| 参数 | 类型 | 说明 |
|---|---|---|
| uid | string | 异步任务 uid,用于后续获取任务结果 |
| taskType | int | 任务类型 |
| params | dict | 任务参数 |
| result | dict | 任务结果(创建时为空) |
| status | int | 任务状态,0: 等待中, 1: 正在执行, 2: 成功, 3: 失败 |
| creator | string | 任务创建者 |
| createdAt | string | 任务创建时间 |
| updatedAt | string | 任务更新时间 |
2. 获取预测任务结果¶
通过创建任务接口返回的任务 uid,以轮询方式调用本接口获取结果。
提示:当任务状态(status)为 2(成功)或 3(失败)时,代表任务已完成,可停止轮询。
请求方式¶
GET /openapi/v1/async-tasks/{async_task_uid}/
Authorization: "{连接密钥}"
返回结果¶
| 参数 | 类型 | 说明 |
|---|---|---|
| uid | string | 异步任务 uid,用于后续获取任务结果 |
| taskType | int | 任务类型 |
| params | dict | 任务参数 |
| result | dict | 任务结果 |
| result.status | string | 查询结果状态 |
| result.data | list | 查询结果,当任务状态为 2 时,该字段会返回查询结果 |
| result.key | string | 查询结果缓存 key,当任务状态为 2 时,该字段会返回缓存 key |
| result.message | string | 错误原因,当任务状态为 3 或 4 时,该字段会返回查询失败的原因 |
| status | int | 任务状态,0: 等待中, 1: 正在执行, 2: 成功, 3: 查询数据失败, 4: 预测模型失败, 5: 任务被取消, 6: 任务已过期 |
| creator | string | 任务创建者 |
| createdAt | string | 任务创建时间 |
| updatedAt | string | 任务更新时间 |
附录:状态码说明¶
| 状态码 | 说明 |
|---|---|
| 0 | 等待中 |
| 1 | 执行中 |
| 2 | 成功 |
| 3 | 查询数据失败 |
| 4 | 预测模型失败 |
| 5 | 任务被取消 |
| 6 | 任务已过期 |