idempotencyKey 是你在提交时可选设置的字符串。再次发送同一个键,你会拿到第一次提交创建的任务;不会排入新的工作,也不会新增积分冻结。
各端点如何处理重复的键
单任务端点保留显式创建语义:你要求创建一个已存在的任务,因此会得到冲突。错误中的
error.details.taskId 是既有任务的 id,提交响应丢失时可用它查询结果。
位置网格
网格的idempotencyKey 会成为它的 id(省略时自动生成 UUID)。每个点位的任务键为 <grid id>:r<row>c<col>。以该 id 再次发送同一网格,会返回已存在的点位,只接纳缺失的点位。以同一 id 发送中心、尺寸或半径不同的网格时,坐标不同的点位会以 RESOURCE_ALREADY_EXISTS 失败;新网格请使用新键。
范围与长度
键的作用域是你的账户:其他账户可以使用相同的字符串,不会与你的冲突。
不要求 UUID 格式。
将结果与提交对应
如果没有发送键,任务对象中会省略
idempotencyKey,而不是返回 null。
键的生命周期
键在请求后至少保持占用 30 天,任务完成或失败后、24 小时轮询窗口关闭后也是如此。轮询返回404 不会释放键。同一次提交的传输重试请使用同一个键;同一工作的另一次独立运行请使用新键(例如追加 :r1 后缀)。
下一步
批次与网格
三个批量端点的对比。
错误
所有请求错误码。