フィールド マスク

フィールド マスクは、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