| 编号 | 231 |
|---|---|
| 原文链接 | AIP-231: Batch methods: Get |
| 状态 | 批准 |
| 创建日期 | 2019-06-18 |
| 更新日期 | 2019-06-18 |
一些API允许用户获取一组特定资源在一个时间点（例如使用读事务）的状态。批量获取方法提供了这个功能。
指南
API 可以 按照以下模式支持批量获取：
rpc BatchGetBooks(BatchGetBooksRequest) returns (BatchGetBooksResponse) {option (google.api.http) = {get: "/v1/{parent=publishers/*}/books:batchGet"};
}
- 远程过程调用名字 必须 以
BatchGet开头，其余部分 应当 是所查询资源的复数形式。 - 请求和应答消息 必须 与远程过程调用名字一致，带有
Request和Response后缀。 - HTTP动词 必须 是
GET。 - HTTP URI 必须 以
:batchGet结尾。 - URI路径 应当 表示资源的集合，与简单CRUD操作使用的集合一致。如果操作跨越多个上级集合， 可以 使用破折号（
-）作为通配符。 google.api.http注解 不得 包含 body 键。- 操作 必须 是原子的： 必须 对全部资源成功或全部失败（不存在部分成功）。对于需要部分失败的场景， 应当 使用
List(AIP-132) 方法。- 如果操作涉及多个位置，并且存在位置不可用，操作 必须 失败。
请求消息
批量获取方法请求 应当 使用以下模式指定：
message BatchGetBooksRequest {// The parent resource shared by all books being retrieved.// Format: publishers/{publisher}// If this is set, the parent of all of the books specified in `names`// must match this field.string parent = 1 [(google.api.resource_reference) = {child_type: "library.googleapis.com/Book"}];// The names of the books to retrieve.// A maximum of 1000 books can be retrieved in a batch.// Format: publishers/{publisher}/books/{book}repeated string names = 2 [(google.api.field_behavior) = REQUIRED,(google.api.resource_reference) = {type: "library.googleapis.com/Book"}];
}
- 应当 包含
parent域（所查询的是顶级资源时除外），以便于包含在URI中，并支持单一权限检查。如果调用者设定了这个域，而所查询资源的上级名字与上级集合不一致，请求 必须 失败。- 如果请求只允许设定一个上级，域 应当 是必需域。
- 域 应当 标识所引用的资源类型。
- 域注释 应当 记录资源模式。
- 请求消息 必须 包含一个重复域，接受所查询资源的名字。这个域 应当 名为
names。- 如果请求没有提供资源名，API 应当 返回
INVALID_ARGUMENT错误。 - 域 应当 是必需域。
- 域 应当 标识所引用的资源类型。
- 域注释 应当 记录资源模式。
- 如果请求没有提供资源名，API 应当 返回
- 除
name之外的域 可以 从标准Get请求中“提升”。没有办法让这些域针对不同资源接受不同的值。如果需要这么做，请使用备选请求消息格式。 - 批量获取 不应 支持分页，因为跨API调用的事务难以实现和保证，并且请求已经定义了应答的具体范围。
- 请求消息 不得 包含任何其他必填域， 不应 包含其他可选域。本AIP或其他AIP另有描述的除外。
names域上方的注释 应当 记录所允许的最大请求数。
应答消息
批量获取方法的应答 应当 使用以下模式指定：
message BatchGetBooksResponse {// Books requested.repeated Book books = 1;
}
- 应答消息 必须 包含一个与所查询资源对应的重复域。
- 应答中资源的顺序 必须 与请求中资源名字的顺序相同。
嵌套请求对象
如果标准Get请求消息包含资源名字之外的域，并且这个域对所请求的不同资源有着不同的值，那么批量消息 可以 包含一个 repeated 标准Get请求消息域。除非确实需要，通常不建议这么做。
使用这种方式的批量获取方法的请求消息 应当 使用以下模式指定：
message BatchGetBooksRequest {// The parent resource shared by all books being retrieved.// Format: publishers/{publisher}// If this is set, the parent field in the GetBookRequest messages// must either be empty or match this field.string parent = 1 [(google.api.resource_reference) = {child_type: "library.googleapis.com/Book"}];// The requests specifying the books to retrieve.// A maximum of 1000 books can be retrieved in a batch.repeated GetBookRequest requests = 2[(google.api.field_behavior) = REQUIRED];
}
- 应当 包含一个
parent域。如果调用者设定了这个域，并且与某个所查询资源的名字中的上级集合不一致，请求 必须 失败。- 如果每个请求只允许设定一个上级，域 应当 是必需域。
- 域 应当 标识所引用的资源类型。
- 域的注释 应当 记录资源模式。
- 请求消息 必须 包含一个重复域，接受指定待获取资源的请求消息，如同标准Get方法。域 应当 名为
requests。- 域 应当 是必需域。
- 其他域 可以 从标准Get请求中“提升”，意味着该域可以在批量级别或子请求级别设置。与
parent类似，如果批量级别和子请求级别为同一域设置了值，值 必须 一致。 - 批量获取 不应 支持分页，因为跨API调用事务难以实现或保证，并且请求已经定义了应答的具体范围。
- 请求消息 不得 包含任何其他必填域， 不应 包含其他可选域。本AIP或其他AIP另有描述的除外。
requests域上方的注释 应当 记录所允许的最大请求数。
修订记录
- 2022-06-02 修改后缀描述，消除多余的“-”。
- 2020-09-16 建议注释
parent、names和requests域。 - 2020-08-27 删除关于顶级资源上级的建议。
- 2020-03-24 明确未发送资源名字时的行为。
- 2019-09-11 将优先推荐方案改为使用重复字符串域，而非重复标准Get请求消息。原推荐方案移至独立章节。
- 2019-08-01 将示例从“书架”更改为“出版商”，提供更好的资源所有权示例。