写操作与错误

通过 API 修改状态的程序都遵守同一套规则：先查询服务端的能力，写请求带幂等键与期望版本，按统一的格式读取错误。本页逐条介绍这些规则以及承载它们的字段。

先查询能力复制标题链接

调用业务方法前，先调用 ServerInfoService/GetServerInfo。响应有两个字段：

• 没有 API 版本号可以比较。
• 需要某个能力的操作在能力列表里找不到它时，应该让这一个操作失败，而不是拒绝整个服务端。
• kibo 在每条命令前做精确的字符串匹配，缺失时退出码为 14。

写操作的约定复制标题链接

有两个字段让写请求可以安全地重发、安全地并发：幂等键让重发的请求不会重复执行，期望版本让请求不会覆盖别人的修改。

幂等键复制标题链接

除了下面列出的两个请求，每个写请求都带一个客户端生成的命令 ID（幂等键）：

不符合上表格式的命令 ID，v0.3.x 仍然接受，v0.4.0 起返回不可重试的 invalid_argument。部署方怎样查出这些调用方，见从 v0.2.x 升级到 v0.3.0。

下面这些 ID 有额外的限制：

• GetWorkspaceCommand 与 GetVolumeCommand 读取已有的命令，ID 不受这些规则限制。
• Go SDK 的 kibotos.ValidateCommandID 检查上表的格式和保留前缀；程序要自己调用，SDK 发送请求时不检查。kibo 在发送前检查 --command-id。

命令 ID 只出现在请求消息里，不是 HTTP 头。请在提交前把它保存下来。

服务端把命令 ID 与输入和已有的记录比较：

• 用相同的命令 ID 和相同的输入再次提交，返回第一次的结果，不会重复执行。失败也一样：命令失败后用同一个 ID 重发，只会回放这次失败。
• 一个命令 ID 对应一次尝试。结果未知或命令还在执行时，保持原 ID 重发；错误详情带 command_settled 时，失败已确定，要重试就换新 ID。
• 命令 ID 由对象推导时（比如防止重复创建），让它带上会随尝试变化的部分，比如已失败的次数，否则失败一次后再也跑不起来。
• 用相同的命令 ID 但不同的输入提交，返回 already_exists。
• CreateWorkspace 与 UpdateWorkspaceNetworkPolicy 比较输入时不看 network_policy.revision：这个值由服务端分配，请求里填什么都被忽略。

RevokeEnrollment 与 RetainLaunchRevision 没有命令 ID：它们的效果本身可以重复施加。重复撤销不改变结果，重复保留到同一时刻也一样。

命令的返回时机复制标题链接

命令什么时候返回，取决于命令本身：

版本校验复制标题链接

修改已有对象的请求带一个期望版本。对象的当前版本与期望不一致时服务端拒绝，避免覆盖别人的修改。

Workspace API 的请求：

Operator API 的请求：

ResizeWorkspaceWritableLayer 与 ResizeVolume 没有期望版本，只有命令 ID 和目标容量。

版本不一致时返回什么错误，取决于是哪个版本：

到期时间在 Workspace 状态不允许修改时也返回 failed_precondition，用错误详情里的 observed_workspace 区分这两种情况，见到期时间。

修改已删除对象的 labels 或 annotations 同样返回 failed_precondition。

收到这两种错误后，重新读取对象状态再决定下一步，不要自动用新版本重放旧请求。

错误格式复制标题链接

错误使用 Connect 的标准错误码。错误详情中附带 kibotos.ctrl.v1.ErrorDetail，按下面这些字段决定怎样处理：

stage、message 等其他字段与全部原因见 API 参考中的 ErrorDetail 与 FailureReason。

kibo 优先按 reason 决定退出码，其次按标准错误码。退出码见 kibo 退出码。

下一步复制标题链接

• 认证：获得并续期 Operator 身份。
• 数据面：会话凭证与对 node 的调用。
• 能力名：所有能力及其含义。
• 错误：各失败原因的含义与处理。