フィールド マスクを使用する

フィールド マスクは、リクエストで返されるフィールドまたは更新されるフィールドを API 呼び出し元がリスト表示するための方法です。 FieldMask を使用すると、API は不要な処理を回避してパフォーマンスを向上させることができます。フィールド マスクは、Google スライド API の読み取りメソッドと更新メソッドの両方で使用されます。

フィールド マスクを使用しない場合と使用する場合のレスポンス本文で返される内容の比較については、部分リソースの操作をご覧ください。

フィールド マスクを使用した読み取り

プレゼンテーションは大きくなる可能性があり、読み取りリクエストによって返される presentations リソースのすべての部分が必要になるとは限りません。fields URL パラメータを使用して、スライド API レスポンスで返される内容を制限できます。最適な パフォーマンスを得るには、返信に必要なフィールドのみを 明示的にリスト表示します。

fields パラメータの形式は、FieldMask の JSON エンコードと同じです。 簡単に言うと、複数の異なるフィールドはカンマ区切りで、サブフィールドはドットで区切られます。フィールド名は camelCase または separated_by_underscores で指定できます。便宜上、同じ型の複数のサブフィールドをかっこで囲んでリスト表示できます。

次の presentations.get メソッド リクエストの例では、 slides.pageElements(objectId,size,transform)のフィールド マスクを使用して、プレゼンテーション内のすべてのスライドの pageElement オブジェクトのオブジェクト ID、 Size、および 変換 のみを取得します。

GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)

このメソッド呼び出しのレスポンスは、 presentations オブジェクト フィールド マスクでリクエストされたコンポーネントを含むです。

{
  "slides": [
    {
      "pageElements": [
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311708,
            "translateY": 744575,
            "unit": "EMU"
          }
        },
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311700,
            "translateY": 2834125,
            "unit": "EMU"
          }
        }
     ]
    }
  ]
}

フィールド マスクを使用した更新

オブジェクトの特定のフィールドのみを更新し、他のフィールドは変更したくない場合があります。 presentations.batchUpdate メソッド内の更新リクエストでは、フィールド マスクを使用して、変更されるフィールドを API に伝えます。更新リクエストは、フィールド マスクで指定されていないフィールドを無視し、現在の値をそのまま使用します。

更新されたメッセージでフィールドを指定せずに、フィールドをマスクに追加することで、フィールドの設定を解除することもできます。これにより、フィールドに以前設定されていた値がクリアされます。

更新フィールド マスクの構文は、読み取りフィールド マスクと同じです。

次の例では、 UpdateShapePropertiesRequest メソッドを使用して、図形の塗りつぶしの色を DARK1 テーマの色に変更し、 図形の輪郭線の設定を解除します。

POST https://slides.googleapis.com/v1/presentations/presentationId:batchUpdate
 
{
  "requests": [
    {
      "updateShapeProperties": {
        "objectId": OBJECT_ID,
        "shapeProperties": {
          "shapeBackgroundFill": {
            "solidFill": {
              "color": {
                "themeColor": "DARK1"
              }
            }
          }
        },
        "fields": "shapeBackgroundFill.solidFill.color,outline"
      }
    }
  ]
}