分页、异步任务与幂等

一次请求返回部分列表、一个任务 ID 或连接超时后，客户端往往需要继续发送请求。本页说明怎样延续这三类调用，同时避免漏读数据、无界轮询和重复创建资源。

处理分页

Product API 没有统一分页字段。先查看目标接口的参数和响应，再选择对应模式。

分页模式

常见请求字段

常见响应字段

下一页处理

页码

page、page_size

page、page_size、total

增加页码，直到已读取数量达到 total 或结果为空。

偏移量

offset、limit

offset、limit、total

将本次实际读取数量加入 offset。

页令牌

page_token、page_size

next_page_token

将服务端返回的非空令牌原样传入下一次请求。

游标

cursor、limit

next_cursor

将非空游标原样传回，不解析或自行修改。

分页参数可能位于 Query，也可能位于 JSON 请求体。不要把一个接口的分页字段机械复制到另一个接口。

页码和偏移量

使用页码或偏移量时：

  1. 在每次请求中显式设置页面大小或读取数量；

  2. 记录已处理的资源 ID，避免列表在翻页期间变化时重复处理；

  3. 设置最大页数或最大读取数量，防止异常响应造成无限循环；

  4. 只有接口明确保证排序时，才依赖结果顺序。

total 描述的是接口定义的列表总量或当前查询快照，不代表所有并发变化都会反映在当前遍历中。需要一致快照时，应以目标接口提供的版本、游标或其他一致性机制为准。

页令牌和游标

页令牌和游标是不透明值。客户端只需要保存、传回并判断是否为空：

首次请求不传 page_token 或 cursor
→ 处理本页结果
→ 保存 next_page_token 或 next_cursor
→ 非空时原样请求下一页
→ 为空时结束

不要解码、拼接、截断或在不同筛选条件之间复用令牌。修改筛选、工作区或排序后，应重新开始分页。

处理异步任务

创建、运行、导入、导出、SQL、计算实例和智能体调用可能在首个 HTTP 响应后继续执行。客户端需要区分以下阶段：

提交请求
→ 保存任务、执行或查询 ID
→ 查询当前状态
→ 处理等待输入、取消或失败
→ 进入成功终态
→ 读取并验证结果

保存后续请求需要的标识符

接口可能返回 task_id、run_id、execution_id、statement_id 或其他资源 ID。保存接口实际返回的字段，并同时记录：

  • 调用的接口、方法和工作区；

  • 提交时间；

  • 本地业务操作 ID；

  • 服务端返回的请求 ID 或任务 ID；

  • 当前已知状态。

不同接口中的 id 含义可能不同。例如 A2A 顶层 JSON-RPC id 用于关联请求，任务 ID 位于 result.id。不要根据字段名称相同就混用标识符。

轮询状态

轮询时应设置：

  • 整体截止时间，而不只是单次 HTTP 超时；

  • 最大请求次数；

  • 两次请求之间的等待和随机抖动；

  • 允许继续等待、需要用户输入、成功、失败和取消等状态分类；

  • 调用方取消时的停止条件。

客户端遇到未知状态时，应保守地保持任务未完成并停止自动推进。不要把未知状态当作成功，也不要无界轮询。

读取并验证结果

任务进入成功终态后，还需要按接口说明读取结果、产物、文件统计或查询输出。状态成功不一定表示结果位于状态响应中，也不保证业务应用需要的内容完整。

例如：

  • 工作流运行完成后读取运行结果、产物或数据血缘；

  • 导入任务完成后检查成功和失败的导入任务文件及行数；

  • SQL 查询完成后按结果分页读取数据；

  • A2A 任务完成后按 Part 类型读取 Artifact。

使用幂等能力

幂等表示同一逻辑操作被重复提交时，服务能够识别重复请求并避免产生第二个等价结果。它不是 Product API 所有写接口的共同保证。

当前接口可能使用不同形式：

形式

使用条件

Idempotency-Key Header

仅当接口页明确说明支持该 Header 时使用。

请求体中的 idempotency_key 或类似字段

使用接口规定的字段名、作用域和格式。

A2A params.idempotencyKey

发送智能体消息且目标 A2A 契约支持时使用。

服务端资源版本或期望版本

用于检测并发更新冲突，不等同于创建操作的幂等键。

为同一次业务操作重试时保持幂等键稳定；新操作使用新键。不要把一个键跨用户、工作区、接口或不同请求体长期复用。

即使接口支持幂等，客户端仍应保存首次返回的资源或任务 ID。服务端如果返回重复请求标志或原有结果，应继续跟踪该结果，而不是创建另一条业务记录。

超时后怎样处理

网络超时只表示客户端没有及时取得完整响应，不能证明服务端没有接受请求。

  1. 如果已经取得资源、任务或运行标识，先查询该对象。

  2. 如果接口支持幂等，并且本地保留了同一幂等键，可以按接口规则重试同一请求。

  3. 如果接口不支持幂等，先通过列表、详情或业务操作记录查找可能已经创建的结果。

  4. 无法确认结果时，停止自动重试并记录诊断信息，避免重复写入或重复产生费用。

对创建、运行、发布、导入、导出、SQL 执行和外部工具调用，不能仅因为单次请求超时就生成新 ID 并立即重发。

下一步

最后更新于