フィールド マスクは、API 呼び出し元がリクエストで返すか更新するフィールドを一覧表示する方法です。FieldMask を使用すると、API は不要な処理を回避し、パフォーマンスを向上させることができます。フィールド マスクは、Google Sheets API の読み取りメソッドと更新メソッドの両方で使用されます。
フィールド マスクを使用した読み取り
スプレッドシートは大きくなることがあり、読み取りリクエストで返される Spreadsheet リソースのすべての部分が必要になることはほとんどありません。fields URL パラメータを使用すると、スプレッドシート API レスポンスで返される内容を制限できます。パフォーマンスを最大限に高めるには、返信で必要なフィールドのみを明示的にリストします。
fields パラメータの形式は、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 } } } } } ] }