AIP-157 部分应答

有时，资源可能很大，或者计算成本很高，API需要让用户选择返回哪些域。

指南

API 可以 根据下列两种方式之一支持部分应答：

域掩码参数

域掩码（ google.protobuf.FieldMask ）可以用来让用户对返回的域进行细粒度控制。API 应当 通过旁路支持掩码。例如，可以通过HTTP查询参数、HTTP头或gRPC元数据条目指定参数。Google Cloud API将域掩码指定为系统参数。

域掩码 不应 声明在请求中。

• 域掩码参数的值 必须 是 google.protobuf.FieldMask 。
• 域掩码参数 必须 是可选的：
  • 应当 支持显式值 "*" ，此时 必须 返回所有域。
  • 如果省略域掩码参数， 必须 默认为 "*" ，另有说明的除外。
• API 可以 使用非终止重复域的读掩码（与写掩码不同），但不强制这样做。

注意 修改域掩码参数默认值是破坏性变更。

视图枚举

API也 可以 通过视图枚举提供部分应答。视图枚举适用于API希望向用户发布少量几种域组合的情况：

enum BookView {
  // The default / unset value.
  // The API will default to the BASIC view.
  BOOK_VIEW_UNSPECIFIED = 0;

  // Include basic metadata about the book, but not the full contents.
  // This is the default value (for both ListBooks and GetBook).
  BOOK_VIEW_BASIC = 1;

  // Include everything.
  BOOK_VIEW_FULL = 2;
}

• 枚举 应当 在请求消息中声明为 view 域。
• 枚举名字 应当 以 -View 结尾。
• 枚举 应当 至少包含名为 BASIC 和 FULL 的值（当然也 可以 有其他值）。
• 必须 支持 UNSPECIFIED 值（不是错误），且API 必须 在文档中记录未设定值的行为。
  • 对于List接口，有效默认值 应当 是 BASIC 。
  • 对于Get接口，有效默认值 应当 是 BASIC 或 FULL 。
• 枚举 应当 定义在proto文件顶层（因为可能被多个请求使用，例如 Get 和 List ）。有关顶层枚举的更多指南，请参考AIP-126。
• API 可以 随时向视图添加域。API 不得 从视图中删除域（这是破坏性变更）。

注意 如果服务需要（或可能需要）提供重叠但不相同的多个视图，可能存在名字空间冲突。此时服务 应当 将视图枚举嵌套在单独的资源中。

读掩码作为请求域

警告 将读掩码作为请求消息中的单个域（例如： google.protobuf.FieldMask read_mask ）的方案 已废弃 。

修订记录

• 2023-05-09 修正顶层枚举示例，并链接到AIP-126。
• 2022-03-14 更新关于默认值和如何设定读掩码的指南。
• 2021-10-06 更新系统参数指南。
• 2021-03-04 添加关于冲突视图枚举的指南。