异步任务与幂等
保存任务身份、轮询最终状态,并避免重复提交资源变更。
受理响应
许多写请求返回任务对象,HTTP 200 仍只是受理成功。保存 data.id 与 data.resource_id,使用 GET /api/v1/operations/{operation_id} 查询。
| 状态 | 客户端处理 |
|---|---|
| queued | 继续等待,尚未完成交付 |
| running | 展示阶段、进度和消息 |
| succeeded | 再读取资源的确认状态 |
| failed / interrupted | 展示真实错误,修复后按原任务重试 |
任务日志可能包含多阶段进度,不能只靠百分比判断虚拟机或网络实际就绪。资源电源状态与活动任务分别存在。
幂等键
契约支持的写操作可携带 Idempotency-Key。同一次业务动作生成一次并保存,因网络超时重发时使用相同键和相同请求内容;新业务动作使用新键。不要在每次 HTTP 重试时换键。
请求超时先查询已保存的任务或资源,确认是否已经受理;有记录的失败使用 POST /api/v1/operations/{operation_id}/retry,并遵循目标操作的可重试条件。
当前没有可供第三方订阅的通用事件/Webhook 回调。使用受控间隔轮询即可,终止后停止轮询,不依赖通用事件订阅接口。
