tommwq.work/aip

AIP-132 标准方法:List

· [tommwq@126.com]
编号 132
原文链接 https://google.aip.dev/132
状态 批准
创建日期 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开头,其余部分 应当 是目标资源的复数形式。
  • 请求和应答消息 必须 与接口名字一致,带有 RequestResponse 后缀。
  • 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_sizepage_token 域。更多信息请参考AIP-158
    • page_size 域的注释 应当 记录最大允许值,以及省略(或设置为0)时的默认值。如果需要,API 可以 声明服务器将选择合理的默认值。默认值 可以 在将来发生改变。
    • 如果用户提供的值大于最大允许值,API 应当 将该值强制设定为最大允许值。
    • 如果用户提供了负值或其他无效值,API 必须 发送 INVALID_ARGUMENT 错误。
  • 必须 包含在所有List请求消息中包含 page_token 域。
  • 请求消息 可以 包含与List方法相关的常见设计模式的域,例如 string filterstring 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.baraddress.street

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

过滤

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

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

标记为已删除的资源

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

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

错误

参考错误,特别是何时使用 PERMISSION_DENIEDNOT_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 添加对标准方法中任意域的明确禁止。