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

フィールド マスクを使用すると、API 呼び出し元がリクエストの対象となるフィールドを 返すことができます使用 FieldMask これにより、API で不要な作業が回避され、パフォーマンスが向上します。フィールド マスク は、Google Sheets API の read メソッドと update メソッドの両方で使用されます。

フィールド マスクを使用して読み取る

プレゼンテーションはサイズが大きい場合があり、多くの場合、プレゼンテーションの Presentation リソースが含まれています。1 つのリクエストで返される内容を制限することで、 Google スライド API レスポンス（fields URL パラメータを使用）。ベスト プラクティス パフォーマンス、 必要なフィールドのみを明示的に列挙する 返信します。

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

次の presentations.get リクエストの例では、次のフィールド マスクを使用しています。 オブジェクト ID のみを取得する slides.pageElements(objectId,size,transform)。 Size、 変換 /pageElement 次の点に注意してください。

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 テーマカラーに変更し、シェイプの Outline:

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