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

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

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

Чтение с маской поля

Презентации могут быть большими, и зачастую вам не нужна каждая часть ресурса presentations возвращаемая запросом на чтение. Вы можете ограничить то, что возвращается в ответе 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)

Ответом на вызов этого метода является объект 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, какие поля изменяются. Запрос на обновление игнорирует любые поля, которые не указаны в маске полей, оставляя для них текущие значения.

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

Синтаксис масок полей обновления аналогичен синтаксису масок полей чтения.

Маска поля * рассматривается как подстановочный знак и является сокращением для указания каждого поля в сообщении. Синтаксис подстановочных знаков может привести к нежелательным результатам, если 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"
      }
    }
  ]
}