字段掩码

字段掩码是一种供 API 调用方列出请求应返回的字段的方式。使用字段掩码可让 API 避免不必要的工作，从而提高性能。

字段掩码可以指定为网址查询参数，也可以指定为 HTTP 或 gRPC 标头：

网址查询参数	HTTP 或 gRPC 标头
$fields 或 fields	X-Goog-FieldMask

字段掩码语法

以下字段掩码示例基于此示例响应类型。

message ExampleResponse {
  message Foo {
    string foo1 = 1;
    string foo2 = 2;
    Bar foo3 = 3;
  }

  message Bar {
    string bar1 = 1;
    string bar2 = 2;
    string bar3 = 3;
  }

  string field1 = 1;
  repeated Foo field2 = 2;
}

可以使用点语法或将嵌套字段括在英文圆括号中来选择嵌套字段。

表达式	输出
*	返回所有字段和嵌套字段。
field1,field2	返回 field1 和 field2 的所有嵌套字段。
field1,field2.foo1	返回 field1 和 field2.foo1。
field1,field2(foo1)	返回 field1 和 field2.foo1。
field1,field2(foo1,foo2)	返回： field1 field2.foo1 field2.foo2
field1,field2(foo1,foo3(bar1,bar2))	返回： field1 field2.foo1 field2.foo3.bar1 field2.foo3.bar2