# 分页、异步任务与幂等

一次请求返回部分列表、一个任务 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` 描述的是接口定义的列表总量或当前查询快照，不代表所有并发变化都会反映在当前遍历中。需要一致快照时，应以目标接口提供的版本、游标或其他一致性机制为准。

### 页令牌和游标

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

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

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

## 处理异步任务

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

```text
提交请求
→ 保存任务、执行或查询 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 并立即重发。

## 下一步

- [根据状态码和错误对象决定下一步](status-error-codes.md)
- [为安全操作配置有界重试](rate-limits-retries.md)
- [运行、查询和取消工作流](../product-api/workflows-workitems-lineage/run-query-cancel.md)