Маски полей — это способ для вызывающих API перечислить поля, которые запрос должен вернуть или обновить. Использование FieldMask позволяет API избежать ненужной работы и повышает производительность. Маска поля используется как для методов чтения, так и для методов обновления в API Google Таблиц.
Чтение с маской поля
Таблицы могут быть большими, и зачастую вам не нужна каждая часть ресурса Spreadsheet , возвращаемая запросом на чтение. Вы можете ограничить то, что возвращается в ответе API Таблиц, используя параметр URL- fields . Для повышения производительности явно указывайте в ответе только те поля, которые вам нужны .
Формат параметра полей такой же, как кодировка JSON FieldMask . Короче говоря, несколько различных полей разделяются запятыми, а подполя — точкой. Имена полей могут быть указаны в CamelCase или Separated_by_underscores . Для удобства несколько подполей одного типа можно указать в круглых скобках.
В следующем примере запроса 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
}
}
}
}
}
]
}