AIP-233 批量方法：Create

有些API需要允许用户在单个事务中创建多个资源。批量Create方法提供了这个功能。

指南

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

以同步方式返回应答。

rpc BatchCreateBooks(BatchCreateBooksRequest) returns (BatchCreateBooksResponse) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books:batchCreate"
    body: "*"
  };
}

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

rpc BatchCreateBooks(BatchCreateBooksRequest) returns (google.longrunning.Operation) {
  option (google.api.http) = {
    post: "/v1/{parent=publishers/*}/books:batchCreate"
    body: "*"
  };
  option (google.longrunning.operation_info) = {
    response_type: "BatchCreateBooksResponse"
    metadata_type: "BatchCreateBooksOperationMetadata"
  };
}

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

原子性和部分成功

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

请求消息

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

message BatchCreateBooksRequest {
  // The parent resource shared by all books being created.
  // Format: publishers/{publisher}
  // If this is set, the parent field in the CreateBookRequest 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 create.
  // A maximum of 1000 books can be created in a batch.
  repeated CreateBookRequest requests = 2
    [(google.api.field_behavior) = REQUIRED];
}

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

应答消息

批量创建方法的应答 应当 使用以下模式指定：

message BatchCreateBooksResponse {
  // Books created.
  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 BatchCreateBooksOperationMetadata.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 添加部分成功行为详细指南，以及选择原子或部分成功方案的决策框架。
• 2023-04-18 修改建议，允许返回部分成功。
• 2022-06-02 修改后缀描述，消除多余的“-”。
• 2020-09-16 建议注释 parent 和 requests 域。
• 2020-08-27 删除关于顶级资源上级的建议。
• 2019-08-01 将示例从“书架”更改为“出版商”，提供更好的资源所有权示例。