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

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

Для сравнения того, что возвращается в теле ответа при отсутствии и при использовании маски поля, см. раздел Работа с частичными ресурсами .

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

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

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

В следующем примере запроса метода presentations.get используется маска поля slides.pageElements(objectId,size,transform) для извлечения только идентификатора объекта, Size и преобразования объекта pageElement на всех слайдах презентации:

GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)

Ответом на вызов этого метода является объект presentations , содержащий компоненты, запрошенные в маске поля:

{
  "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"
      }
    }
  ]
}