Маски полей — это способ для вызывающих API перечислить поля, которые запрос должен вернуть или обновить. Использование FieldMask позволяет API избежать ненужной работы и повышает производительность. Маска поля используется как для методов чтения, так и для методов обновления в API Google Slides.
Для сравнения содержимого тела ответа при отсутствии и наличии маски поля см. раздел «Работа с частичными ресурсами» .
Чтение с использованием полевой маски
Презентации могут быть большими, и часто вам не нужна вся информация о presentations возвращаемая запросом на чтение. Вы можете ограничить объем возвращаемого в ответе API Slides содержимого, используя параметр URL fields . Для достижения наилучшей производительности явно перечисляйте в ответе только те поля, которые вам необходимы .
The format of the fields parameter is the same as the JSON encoding of a FieldMask . Stated briefly, multiple different fields are comma-separated and subfields are dot-separated. Field names can be specified in camelCase or separated_by_underscores . For convenience, multiple subfields from the same type can be listed within parentheses.
В приведенном ниже примере запроса метода presentations.get используется маска поля slides.pageElements(objectId,size,transform) для получения только идентификатора объекта, Size и преобразования объекта pageElement на всех слайдах презентации:
GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)
В ответ на этот вызов метода выводится объект presentations содержащий компоненты, запрошенные в поле mask:
{
"slides": [
{
"pageElements": [
{
"objectId": "OBJECT_ID",
"size": {
"width": {
"magnitude": 3000000,
"unit": "EMU"
},
"height": {
"magnitude": 3000000,
"unit": "EMU"
}
},
"transform": {
"scaleX": 1,
"scaleY": 1
"translateX": 311708,
"translateY": 744575,
"unit": "EMU"
}
},
{
"objectId": "OBJECT_ID",
"size": {
"width": {
"magnitude": 3000000,
"unit": "EMU"
},
"height": {
"magnitude": 3000000,
"unit": "EMU"
}
},
"transform": {
"scaleX": 1,
"scaleY": 1
"translateX": 311700,
"translateY": 2834125,
"unit": "EMU"
}
}
]
}
]
}Обновление с маской поля
Иногда необходимо обновить только определенные поля объекта, оставив остальные поля без изменений. Запросы на обновление внутри метода presentations.batchUpdate используют маски полей, чтобы сообщить API, какие поля изменяются. Запрос на обновление игнорирует любые поля, не указанные в маске поля, оставляя их с текущими значениями.
Также можно удалить значение поля, не указывая его в обновленном сообщении, а добавив поле в маску. Это очистит любое значение, которое поле имело ранее.
Синтаксис для обновления масок полей такой же, как и для чтения масок полей.
В следующем примере метод UpdateShapePropertiesRequest используется для изменения цвета заливки фигуры на цвет темы DARK1 и удаления контура фигуры:
POST https://slides.googleapis.com/v1/presentations/presentationId:batchUpdate
{
"requests": [
{
"updateShapeProperties": {
"objectId": OBJECT_ID,
"shapeProperties": {
"shapeBackgroundFill": {
"solidFill": {
"color": {
"themeColor": "DARK1"
}
}
}
},
"fields": "shapeBackgroundFill.solidFill.color,outline"
}
}
]
}