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

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

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

プレゼンテーションはサイズが大きい場合があり、読み取りリクエストで返される Presentation リソースのすべての部分が必要とは限りません。fields URL パラメータを使用すると、Slides API のレスポンスで返される要素を制限できます。パフォーマンスを最適化するには、レスポンスで必要なフィールドのみを明示的に指定します。

フィールド パラメータの形式は、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)

このメソッド呼び出しのレスポンスとして返される Presentation オブジェクトには、フィールド マスクでリクエストされたコンポーネントが含まれます。

{
  "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"
      }
    }
  ]
}