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

AIP-132 标准方法：List

article 2025/1/31 1:21:10

编号	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 域应当反映过滤后集合的大小。