AIP-231 批量方法：Get

一些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 错误。
  • 域 应当 是必需域。
  • 域 应当 标识所引用的资源类型。
  • 域注释 应当 记录资源模式。
• 除 name 之外的域 可以 从标准获取请求中“提升”。没有办法让这些域针对不同资源接受不同的值。如果需要这么做，请使用备选请求消息格式。
• 批量获取 不应 支持分页，因为跨API调用的事务难以实现和保证，并且请求已经定义了应答的具体范围。
• 请求消息 不得 包含任何其他必填域， 不应 包含其他可选域。本AIP或其他AIP另有描述的除外。
• names 域上方的注释 应当 记录所允许的最大请求数。

应答消息

批量获取方法的应答 应当 使用以下模式指定：

message BatchGetBooksResponse {
  // Books requested.
  repeated Book books = 1;
}

• 应答消息 必须 包含一个与所查询资源对应的重复域。
• 应答中资源的顺序 必须 与请求中资源名字的顺序相同。

嵌套请求对象

如果标准获取请求消息包含资源名字之外的域，并且这个域对所请求的不同资源有着不同的值，那么批量消息 可以 包含一个 repeated 标准获取请求消息域。除非确实需要，通常不建议这么做。

使用这种方式的批量获取方法的请求消息 应当 使用以下模式指定：

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 域。如果调用者设定了这个域，并且与某个所查询资源的名字中的上级集合不一致，请求 必须 失败。
  • 如果每个请求只允许设定一个上级，域 应当 是必需域。
  • 域 应当 标识所引用的资源类型。
  • 域的注释 应当 记录资源模式。
• 请求消息 必须 包含一个重复域，接受指定待获取资源的请求消息，如同标准获取方法。域 应当 名为 requests 。
  • 域 应当 是必需域。
• 其他域 可以 从标准获取请求中“提升”，意味着该域可以在批量级别或子请求级别设置。与 parent 类似，如果批量级别和子请求级别为同一域设置了值，值 必须 一致。
• 批量获取 不应 支持分页，因为跨API调用事务难以实现或保证，并且请求已经定义了应答的具体范围。
• 请求消息 不得 包含任何其他必填域， 不应 包含其他可选域。本AIP或其他AIP另有描述的除外。
• requests 域上方的注释 应当 记录所允许的最大请求数。

修订记录

• 2022-06-02 修改后缀描述，消除多余的“-”。
• 2020-09-16 建议注释 parent 、 names 和 requests 域。
• 2020-08-27 删除关于顶级资源上级的建议。
• 2020-03-24 明确未发送资源名字时的行为。
• 2019-09-11 将优先推荐方案改为使用重复字符串域，而非重复标准获取请求消息。原推荐方案移至独立章节。
• 2019-08-01 将示例从“书架”更改为“出版商”，提供更好的资源所有权示例。