Маски полей — это способ для вызывающих API перечислить поля, которые запрос должен вернуть или обновить. Использование FieldMask позволяет API избежать ненужной работы и повышает производительность. Маска поля используется как для методов чтения, так и для обновления в API Google Slides.
Чтение с маской поля
Презентации могут быть большими, и зачастую вам не нужна каждая часть ресурса Presentation возвращаемая запросом на чтение. Вы можете ограничить то, что возвращается в ответе API Slides, используя параметр URL-адреса fields . Для повышения производительности явно указывайте в ответе только те поля, которые вам нужны .
Формат параметра полей такой же, как кодировка JSON FieldMask . Короче говоря, несколько различных полей разделяются запятыми, а подполя — точкой. Имена полей могут быть указаны в CamelCase или Separated_by_underscores . Для удобства несколько подполей одного типа можно указать в круглых скобках.
В следующем примере presentations.get используется маска поля slides.pageElements(objectId,size,transform) для получения только идентификатора объекта, Size и преобразования объекта pageElement на всех слайдах презентации:
GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)
Ответом на вызов этого метода является объект Presentation содержащий компоненты, запрошенные в маске поля:
{
"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"
}
}
]
}