AIP-234 批量方法：Update

一些API允许用户在单个事务中修改一系列资源。批量更新方法提供了这个功能。

指南

API 可以 使用下列两种模式支持批量更新：

以同步方式返回应答。

rpc BatchUpdateBooks(BatchUpdateBooksRequest) returns (BatchUpdateBooksResponse) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books:batchUpdate"
    body: "*"
  };
}

返回操作对象，以异步方式确定应答。

rpc BatchUpdateBooks(BatchUpdateBooksRequest) returns (google.longrunning.Operation) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books:batchUpdate"
    body: "*"
  };
  option (google.longrunning.operation_info) = {
    response_type: "BatchUpdateBooksResponse"
    metadata_type: "BatchUpdateBooksOperationMetadata"
  };
}

• 远程过程调用名字 必须 以 BatchUpdate 开头，其余部分 应当 是待更新资源的复数形式。
• 请求和应答消息 必须 与远程过程调用名字一致，并带有 Request 和 Response 后缀。
• 如果批量方法返回 google.longrunning.Operation ， 必须 设定 response_type 和 metadata_type 域。
• HTTP动词 必须 是 POST 。
• HTTP URI 必须 以 :batchUpdate 结尾。
• URI路径 应当 表示资源集合，与简单CRUD操作中使用的集合一致。如果操作跨越多个上级， 可以 使用破折号（ - ）作为通配符。
• google.api.http 注解中的body子句 应当 是 "*" 。

原子性和部分成功

• 批量更新方法 可以 是原子的（要求全部更新成功，要么全都不更新）或支持部分成功。选择时请考虑下列因素：
  • 保证原子性所需的复杂度：使用简单数据库事务的操作 应当 作为原子操作。涉及管理复杂资源的操作 应当 作为部分成功操作。
  • 终端用户体验：考虑API消费者视角。原子行为适合这个场景吗，这意味着少数条目有问题将导致大批量失败。
• 同步批量更新 必须 是原子的。
• 异步批量更新 可以 支持原子性或部分成功。
  • 如果支持部分成功，参考操作元数据消息要求。

请求消息

批量更新方法请求 应当 使用以下模式指定：

message BatchUpdateBooksRequest {
  // The parent resource shared by all books being updated.
  // Format: publishers/{publisher}
  // If this is set, the parent field in the UpdateBookRequest messages
  // must either be empty or match this field.
  string parent = 1 [
    (google.api.resource_reference) = {
      child_type: "library.googleapis.com/Book"
    }];

  // The request message specifying the resources to update.
  // A maximum of 1000 books can be modified in a batch.
  repeated UpdateBookRequest requests = 2
    [(google.api.field_behavior) = REQUIRED];
}

• 应当 包含一个 parent 域，待更新资源是顶级资源时除外。如果调用者设定了域，但与请求中某个子消息的 parent 域不一致，请求 必须 失败。
  • 如果每个请求只允许设置一个上级，域 应当 是必需域。
  • 域 应当 标识所引用的资源类型。
  • 域的注释 应当 记录资源模式。
• 请求消息 必须 包含一个重复域，接受设定待创建资源的消息，如同标准更新方法。域 应当 名为 requests 。
  • 域 应当 是必需域。
• 其他域 可以 从标准更新请求中“提升”，意味着这些域可以在批量级别或子消息级别设定。与 parent 类似，如果批量级别和子消息级别都对同一个域设定了值，值 必须 一致。
  • update_mask 通常是很适合提升的域。
• 请求消息 不得 包含任何其他必填域， 不应 任何其他可选域。本AIP或其他AIP另有要求的除外。
• requests 域上方的注释 应当 记录所允许的最大请求数。

应答消息

批量更新方法应答 应当 使用以下模式指定：

message BatchUpdateBooksResponse {
  // Books updated.
  repeated Book books = 1;
}

• 应答消息 必须 包含与待更新资源对应的重复域。

操作元数据消息

• metadata_type 消息 必须 要么与远程过程调用名字一致，并带有 OperationMetadata 后缀；要么在类型被多个批量方法共享时，以 Batch 前缀和 OperationMetadata 后缀命名。
• 如果批量更新方法支持部分成功，元数据消息 必须 包含 map<int32, google.rpc.Status> failed_requests 域，传递部分失败信息。
  • map中的键是批量请求 requests 域中子消息的下标。
  • map条目中的值 必须 是可能被通常标准更新方法调用返回的错误。
  • 如果失败的请求通过服务端重试最终成功，期间暂时的错误 不得 通过 failed_requests 传递。
  • 如果批量中的请求全部失败， 必须 将 Operation.error 设定为 code = google.rpc.Code.Aborted 和 message = "None of the requests succeeded, refer to the BatchUpdateBooksOperationMetadata.failed_requests for individual error details" 。
• 元数据消息 可以 包含其他域，传递操作进度信息。

适配部分成功

为了让现存批量API适配部分成功模式，API必须执行：

• 必须保持默认行为，避免不兼容的行为变化。
• 如果API返回 Operation ：
  • 请求消息 必须 包含 bool return_partial_success 域。
  • Operation metadata_type 必须 包含 map<int32, google.rpc.Status> failed_requests 域。
  • 如果请求的 bool return_partial_success 设定为真，API应当支持部分成功行为；否则应当继续保持默认的原子行为。
• 如果API直接同步返回应答：
  • 由于现存客户端将成功应答视为原子操作，现存API版本 不得 适配部分成功模式。
  • 必须 更新新版本，返回 Operation ，并遵守本文档描述的部分成功模式。

理由

要求同步批量方法是原子的

同步批量方法必须是原子的，这一要求来自于下列思考：

在本AIP的早期版本建议批量方法是原子的。没有直观的方法能在同步应答状态码中表达部分失败，因为成功暗示一切正常。因此在应答中添加新域表示部分失败，将造成破坏性变更，因为现存客户端会将成功应答解释为全部资源都已更新。

另一方面，如同AIP-193所描述， Operation 更适合表达部分状态。 Operation 的应答状态码不会传递具体的操作结果，客户端需要检查应答消息体，判断操作是否成功。

传递部分失败

本AIP推荐使用 map<int32, google.rpc.Status> failed_requests 域传递部分失败，其中键是失败请求在原始批量请求中的下标。其他考虑过的选项有：

• repeated google.rpc.Status 域。这个选项由于无法清晰确定条目所对应的原始请求而被否决。
• map<string, google.rpc.Status 域。其中键是失败请求的标识。该选项被否决的原因是：
  • 为了读取部分成功应答，客户端需要维护请求标识到请求对象的映射。
  • 如果服务无法保证多个批量请求中，同一请求的幂等性，通过请求标识来传递错误的行为可能违背AIP-155。
• repeated FailedRequest 域。其中 FailedRequest 包含单独的更新请求和 google.rpc.Status 。由于在用户数据保护方面存在难题，不建议在应答消息中返回请求内容，因此否决此选项。

修订记录

• 2025-03-06 添加部分成功行为详细指南，以及选择原子或部分成功方案的决策框架。
• 2022-06-02 修改后缀描述，消除多余的“-”。
• 2020-09-16 建议注释 parent 和 requests 域。
• 2020-08-27 删除关于顶级资源上级的建议。
• 2019-08-01 将示例从“书架”更改为“出版商”，提供更好的资源所有权示例。