当前位置：首页 > news >正文

AIP-233 批量方法：Create

news 来源：原创 2025/5/13 1:44:08

编号	233
原文链接	AIP-233: Batch methods: Create
状态	批准
创建日期	2019-06-18
更新日期	2025-03-06

有些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 。由于在用户数据保护方面存在难题，不建议在应答消息中返回请求内容，因此否决此选项。