Полевые маски

Маски полей — это способ для вызывающих API перечислить поля, которые должен вернуть запрос. Использование маски поля позволяет API избежать ненужной работы и повышает производительность.

Маску поля можно указать либо как параметр URL-запроса, либо как заголовок HTTP или gRPC:

Параметр URL-запроса	Заголовок 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