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

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

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

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

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

В приведенном ниже примере запроса 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
            }
          }
        }
      }
    }
  ]
}