AIP-132 标准方法：List

编号	132
原文链接	AIP-132: Standard methods: List
状态	批准
创建日期	2019-01-21
更新日期	2022-06-02

在许多API中，通常会向集合URI（例如 /v1/publishers/1/books ）发出GET请求，获取集合中资源的列表。

面向资源设计（AIP-121）提供List方法，遵循这一模式，也。这些接口接受上级集合（以及可能的一些其他参数），返回与输入匹配的应答列表。

指南

API 必须为资源提供List方法，除非资源是单例。List方法的目的是从有限集合（通常是一个集合，除非操作支持跨集合读取）中返回数据。

List方法使用以下模式：

rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {option (google.api.http) = {get: "/v1/{parent=publishers/*}/books"};option (google.api.method_signature) = "parent";
}

接口名字必须以单词List开头，其余部分应当是目标资源的复数形式。
请求和应答消息必须与接口名字一致，带有 Request 和 Response 后缀。
HTTP动词必须是 GET 。
目标资源集合应当映射到URI路径。
- 集合的上级资源应当称为 parent ，应当是URI路径中唯一的变量。所有剩余参数应当映射到URI查询参数。
- 集合标识符（例子中的 books ）必须是字面字符串。
必须省略 google.api.http 注解的 body 键。
如果目标资源不是顶级资源，应当只有一个 google.api.method_signature 注解，值为 parent 。如果目标资源是顶级资源，应当不适用 google.api.method_signature 注解，或者只有一个值为 "" 的 google.api.method_signature 注解。

请求消息

List方法实现了一个常见的请求消息模式：

message ListBooksRequest {// The parent, which owns this collection of books.// Format: publishers/{publisher}string parent = 1 [(google.api.field_behavior) = REQUIRED,(google.api.resource_reference) = {child_type: "library.googleapis.com/Book"}];// The maximum number of books to return. The service may return fewer than// this value.// If unspecified, at most 50 books will be returned.// The maximum value is 1000; values above 1000 will be coerced to 1000.int32 page_size = 2;// A page token, received from a previous `ListBooks` call.// Provide this to retrieve the subsequent page.//// When paginating, all other parameters provided to `ListBooks` must match// the call that provided the page token.string page_token = 3;
}

必须包含一个上级域，除非目标资源是顶级资源。上级域的名字应当是 parent 。
- 域应当注解为必需域。
- 域必须标识目标资源的资源类型。
必须在所有List请求消息中设定支持分页的 page_size 和 page_token 域。更多信息请参考AIP-158。
- page_size 域的注释应当记录最大允许值，以及省略（或设置为0）时的默认值。如果需要，API 可以声明服务器将选择合理的默认值。默认值可以在将来发生改变。
- 如果用户提供的值大于最大允许值，API 应当将该值强制设定为最大允许值。
- 如果用户提供了负值或其他无效值，API 必须发送 INVALID_ARGUMENT 错误。
必须包含在所有List请求消息中包含 page_token 域。
请求消息可以包含与List方法相关的常见设计模式的域，例如 string filter 和 string order_by 。
请求消息不得包含任何其他必需域，不应包含其他可选域，本AIP或其他AIP中要求的除外。

注意： 对于任何有权限查询集合的用户，List方法应当返回相同结果。Search方法在这方面的要求比较宽松。

应答消息

List方法实现了一个常见的应答消息模式：

message ListBooksResponse {// The books from the specified publisher.repeated Book books = 1;// A token, which can be sent as `page_token` to retrieve the next page.// If this field is omitted, there are no subsequent pages.string next_page_token = 2;
}

应答消息必须包含一个重复域，对应于目标资源。且不应包含任何其他重复域，另外AIP（例如AIP-217）中要求的除外。
- 应答应当包括完整资源数据，除非有充分理由（参考AIP-157）。
所有列表应答消息必须包含支持分页的 next_page_token 域。如果存在后续分页，必须设置这个域；如果应答表示最后一页，不得设置此域。更多信息请参考AIP-158。
消息可以包含一个 int32 total_size （或 int64 total_size ）域，表示集合中的资源数量。
- 该值可以是一个近似值（此时域应当明确记录这一点）。
- 如果使用过滤功能， total_size 域应当反映过滤后集合的大小。