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

AIP-231 批量方法：Get

news 来源：原创 2025/4/25 3:46:59

编号	231
原文链接	AIP-231: Batch methods: Get
状态	批准
创建日期	2019-06-18
更新日期	2019-06-18

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

应答消息

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

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

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

嵌套请求对象

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

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

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