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

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

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

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

フィールド パラメータの形式は、FieldMask の JSON エンコードと同じです。つまり、異なる複数のフィールドはコンマで、サブフィールドはドットで区切ります。フィールド名は camelCase または separated_by_underscores で指定できます。また、同じ種類のサブフィールドは丸括弧の中に列記しておくと便利です。

次の spreadsheets.get リクエストの例では、sheets.properties(sheetId,title,sheetType,gridProperties) のフィールド マスクを使用して、スプレッドシート内のすべてのシートの SheetProperties オブジェクトのシート ID、タイトル、SheetType、GridProperties のみを取得します。

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)

このメソッド呼び出しのレスポンスとして返される Spreadsheet オブジェクトには、フィールド マスクでリクエストされたコンポーネントが含まれます。sheetType=OBJECT には gridProperties が含まれていないことに注意してください。

{
  "sheets": [
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "TITLE",
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 1000,
          "columnCount": 25
        }
      }
    },
    {
      "properties": {
        "sheetId": SHEET_ID,
        "title": "TITLE",
        "sheetType": "OBJECT"
      }
    }
  ]
}

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

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

アップデート メッセージでフィールドを指定せず、そのフィールドをマスクに追加して、そのフィールドを未設定にすることもできます。この操作によって、以前フィールドに設定した値はすべてクリアされます。

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

次の例では、AddSheetRequest を使用して、Grid タイプの新しいシートを追加し、最初の行を固定し、新しいシートのタブの色を赤にします。

POST https://sheets.googleapis.com/v1/spreadsheets/spreadsheetId:batchUpdate

{
  "spreadsheetId": "SPREADSHEET_ID",
  "replies": [
    {
      "addSheet": {
        "properties": {
          "sheetId": SHEET_ID,
          "title": "TITLE",
          "index": 6,
          "sheetType": "GRID",
          "gridProperties": {
            "rowCount": 1000,
            "columnCount": 26,
            "frozenRowCount": 1
          },
          "tabColor": {
            "red": 0.003921569
          },
          "tabColorStyle": {
            "rgbColor": {
              "red": 0.003921569
            }
          }
        }
      }
    }
  ]
}