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

排序

List方法 可以 允许客户端设定排序规则；此时请求消息 应当 包含 string order_by 域。

• 域列表值 应当 使用逗号分隔例如： "foo,bar" 。
• 默认采用升序排列。要使用降序排列，需要添加一个 " desc" 后缀。如 "foo desc, bar" 。
• 语法中的冗余空格没有意义。 "foo, bar desc" 、 " foo , bar desc " 和 "foo,bar desc" 是等价的。
• 子域用 . 字符指定，例如 foo.bar 或 address.street 。

注意： 只有存在明确需求时，才设置排序规则。总有机会设置排序规则，但删除排序是一种破坏性变更。

过滤

List方法 可以 允许客户端设置过滤规则；此时请求消息 应当 包含 string filter 域。过滤功能在AIP-160详细介绍。

注意： 只有存在明确需求时才设置过滤规则。总有机会设置过滤规则，但删除过滤规则是一种破坏性变更。

标记为已删除的资源

一些API需要“软删除”资源，将它们标记为已删除或待删除（并有选择的在将来清除）。

这样的API 不应 默认在List请求中包含已删除的资源。使用软删除的API 应当 在List请求中包含 bool show_deleted 域，在域设置时，包含已删除的资源。

错误

参考错误，特别是何时使用 PERMISSION_DENIED 和 NOT_FOUND 错误。

进一步阅读

• 关于分页的详细信息，请参考AIP-158。
• 关于列出多个上层集合的资源，请参考AIP-159。

修订记录

• 2023-03-22 修改指南措辞，提及AIP-159。
• 2023-03-17 对齐AIP-122，让 Get 成为 必须 。
• 2022-11-04 将错误指南汇总到AIP-193。
• 2022-06-02 修改关于后缀的描述，消除多余的“-”。
• 2020-09-02 添加关于过滤规则的AIP的链接。
• 2020-08-14 添加关于权限拒绝场景的错误指南。
• 2020-06-08 添加关于返回完整资源的指南。
• 2020-05-19 删除用文档记录排序行为的要求。
• 2020-04-15 添加关于List权限的指南。
• 2019-10-18 添加关于注释的指南。
• 2019-08-01 将示例从“shelves”改为“publishers”，提供更好的资源所有权示例。
• 2019-07-30 添加用文档记录排序行为的指南。
• 2019-05-29 明确禁止在标准方法中使用任意域。