Máscaras de campo

As máscaras de campo são uma maneira de os autores de chamadas de API listarem os campos que uma solicitação precisa retornar. Usar uma máscara de campo permite que a API evite trabalho desnecessário e melhore a performance.

Uma máscara de campo pode ser especificada como um parâmetro de consulta de URL ou como um cabeçalho HTTP ou gRPC:

Parâmetro de consulta do URL	Cabeçalho HTTP ou gRPC
$fields ou fields	X-Goog-FieldMask

Sintaxe da máscara de campo

Os exemplos de máscara de campo a seguir são baseados nesse tipo de resposta de exemplo.

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;
}

Campos aninhados podem ser selecionados usando a sintaxe de ponto ou colocando-os entre parênteses.

Expressão	Saída
*	Retorna todos os campos e campos aninhados.
field1,field2	Retorna field1 e todos os campos aninhados de field2.
field1,field2.foo1	Retorna field1 e field2.foo1.
field1,field2(foo1)	Retorna field1 e field2.foo1.
field1,field2(foo1,foo2)	Retorna: field1 field2.foo1 field2.foo2
field1,field2(foo1,foo3(bar1,bar2))	Retorna: field1 field2.foo1 field2.foo3.bar1 field2.foo3.bar2