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

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

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

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

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

次の spreadsheets.get リクエスト この例では、フィールド マスクとして sheets.properties(sheetId,title,sheetType,gridProperties) を使用しています。 シート ID、タイトル、 SheetType、 GridProperties / SheetProperties 次の点に注意してください。

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