Полевые маски

REST API Менеджера рекламы использует маски полей для частичного чтения и записи. Это может повысить производительность за счет ограничения объема передаваемых данных. Маски полей представлены списком имен полей, разделенных запятыми. Например:

startTime,endTime,targeting.geoTargeting

Читать маски

Маски чтения определяют, какие поля присутствуют в ответе API. Установить маску чтения по вашему запросу можно двумя способами:

1. Параметр запроса fields :

   curl https://admanager.googleapis.com/v1/networks/123456/adUnits?fields=adUnits,nextPageToken,totalSize
   

2. HTTP-заголовок X-Goog-FieldMask :

   curl -H "X-Goog-FieldMask: adUnits,nextPageToken,totalSize" \
       https://admanager.googleapis.com/v1/networks/123456/adUnits
   

Примечание. В строках маски поля поддерживаются как camelCase , так и snake_case .

Маски чтения по умолчанию

Некоторые методы API включают маску поля по умолчанию для полей, возврат которых требует больших затрат. Методы списка являются примером этого. По умолчанию они не включают поле totalSize .

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

Обновить маски

Маски обновления определяют, какие поля будут изменены в запросе обновления ( PATCH ). Если установлена ​​маска обновления, будут обновляться только поля в маске, независимо от того, какие поля установлены в теле запроса.

Маски обновления задаются как параметры запроса. Например:

curl -X PATCH https://admanager.googleapis.com/v1/networks/1234/order/4567?updateMask=displayName

Обход поля

Маски полей могут указывать поля внутри сущности с помощью расширения . символ для обхода. Это тот же синтаксис, который используется Filters .

Маски полей всегда относятся к объекту ответа. Например, маска для чтения LineItem может включать в себя primaryGoal.units . Соответствующая маска для перечисления LineItems — lineItems.primaryGoal.units .

Вы можете указать как поле целиком, так и одно из его подполей. Оба primaryGoal и primaryGoal.units действительны.

Это также относится к повторяющимся полям. Маска поля LineItem creativePlaceholders.size действительна и включает только поле size для каждого CreativePlaceholder .

Примечание. Маски полей не позволяют получить доступ к определенному элементу повторяющегося поля по индексу. Это приводит к ошибке INVALID_ARGUMENT .

Подстановочные знаки

Предупреждение. Использование подстановочного знака в маске обновления не обеспечивает прямой совместимости. Подстановочный знак очистит все поля, которые неизвестны вашему клиенту.

Маски полей поддерживают символ * , обозначающий все поля в сообщении. Следующие примеры демонстрируют использование подстановочных знаков при перечислении Orders . Этот метод имеет маску чтения по умолчанию , которая не включает поле total_size .

Пример	Значение
*	Включает все поля, включая total_size
orders	Включает только поле orders и все его подполя.
orders.*	Включает только поле orders и все его подполя.

Неверные поля

Если маска поля ссылается на несуществующее значение, API ответит ошибкой INVALID_ARGUMENT .