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

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

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

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

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

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

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