Используйте маски полей

Маски полей позволяют вызывающим API перечислить поля, которые должен вернуть или обновить запрос. Использование FieldMask позволяет API избежать ненужной работы и повышает производительность. Маска полей используется как для методов чтения, так и для методов обновления в API Google Таблиц.

Читать с полевой маской

Электронные таблицы могут быть большими, и часто не требуется вся часть ресурса Spreadsheet возвращаемого запросом на чтение. Вы можете ограничить количество возвращаемых данных в ответе API Таблиц, используя параметр URL fields . Для достижения наилучшей производительности явно перечисляйте в ответе только необходимые поля .

Формат параметра fields совпадает с JSON-кодировкой FieldMask . Если коротко, несколько различных полей разделяются запятыми, а подполя — точками. Имена полей можно указывать в верблюжьем регистре или с использованием подчёркивания . Для удобства несколько подполей одного типа можно заключить в скобки.

В следующем примере запроса spreadsheets.get используется маска поля sheets.properties(sheetId,title,sheetType,gridProperties) для извлечения только идентификатора листа, заголовка, 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
            }
          }
        }
      }
    }
  ]
}