/v1 的控制平面 origin。资源 ID 应保存在私有恢复记录中,不进入公共报告。未认证返回 401,应用 Token 返回 403 owner_token_required。
列出操作
GET /v1/resource-operations 返回 200、{operations:[...],next_offset:number|null}。查询参数 limit 为 1–100 整数,默认 50;offset 为非负整数,默认 0。结果按 updated_at 倒序、id 升序排列。并发更新可能使记录移动页面,不构成稳定审计快照。接口列出所有状态,不只 unknown。
响应不暴露完整原始 detail 或凭据。创建响应丢失后,不保证一定有 Provider 标识。
检查单个操作
GET /v1/resource-operations/{id} 返回 200,包含上面的操作字段,但没有列表专用 provider/session_state,并增加 reviews。Reviews 最多包含最新 50 项,按创建时间倒序,每项包含 id、action、note、created_at,没有审阅历史分页参数。
404 resource_operation_not_found。使用详情时另行查询 Session,不要假定包含列表的两个关联字段。
记录审阅或请求对账
POST /v1/resource-operations/{id}/review 接受严格请求体:
只有 state 为 unknown 的操作接受审阅。错误名 resource_operation_not_pending 不表示名为 pending 的状态也符合条件。
以下请求重新开放处理,不表示清理已经确认:
- Session 正在 closing 或操作 kind=delete:关闭 Session。
- Kind=checkpoint:按 Sandbox scope 暂停 Session。
- Kind=restore:恢复 Session。
- 其他情况:调用 Session provisioning 对账路径。
400 invalid_request;操作不存在或属于其他租户返回 404;当前 state 不是 unknown 返回 409 resource_operation_not_pending。接口没有 Idempotency-Key 支持,操作仍为 unknown 时重复接受审阅可能新增多条记录。响应丢失先查询最新 reviews 和状态,再决定是否再次动作。
Acknowledge 不会将 unknown 改为 completed/deleted,reopen 不保证自动尝试已执行。确认实际清理前保留未解决资源 ID。Provider 调查与核对见对账流程。
来源:操作查询与审阅派发、路由参数、生命周期对账。源码和 schema 审阅不证明本轮真实云恢复验收通过。
跟踪同一未解决操作的审阅过程
假设操作最初为state: unknown、review_state: automatic,还没有审阅记录。下面描述的是审阅记录变化,不断言 Provider 结果:
attempt_count 记录生命周期尝试,不是审阅次数,acknowledge/reopen 本身不会递增它。最新 50 条 reviews 是有界历史,详情中看不到旧 note 不证明从未记录过该审阅。应保存自己的私有操作/动作意图,并将其与服务端回执区分。
处理响应,不自动重放变更
SDK 对非成功 HTTP 响应抛出异常,但
200 中包含 reconciliation_error 时仍正常返回对象。SDK 调用后必须检查该字段与 state。运维判断路径见应用对账流程。
路由与事务审阅在隔离 schema 中使用真实 PostgreSQL,通过了当前源码处理器的 30 项检查,包含八次受控生命周期派发。验证范围包括分页/投影、租户/角色拒绝、可审阅状态、重复审阅、提交先于派发、派发优先级、错误响应及 50 条历史上限。生命周期回调使用 stub,不代表实际云对账成功。临时 schema 已删除。
下一步:HTTP 总览、Session 生命周期。