Фильтры

API Менеджера рекламы поддерживает фильтрацию по методам List . Синтаксис строки фильтра формально определен в грамматике EBNF .

Для начала приведем несколько примеров распространенных случаев использования.

Пример Значение
orders.updateTime > "2024-01-01T00:00:00-5:00" Перечисляет заказы с updateTime после 1 января 2024 г. в восточном стандартном часовом поясе.
lineItems.targeting.geoTargeting.targetedGeoIds:2840 Перечисляет позиции с географическим таргетингом, включающим США (идентификатор географической цели 2480 ).
lineItems.displayName = "*_interstitial" Перечисляет позиции, отображаемое название которых заканчивается строкой _interstitial
orders.displayName = "*video*" Перечисляет заказы, отображаемое имя которых содержит строку video
displayName:"video" Перечисляет заказы, отображаемое имя которых содержит строку video (альтернативный синтаксис).

Литералы

Простое буквальное значение (примеры: 42 , Hugo ) — это значение, с которым необходимо сопоставить. Литералы, появляющиеся отдельно, нечетко сопоставляются со всеми поддерживаемыми полями ресурса. Ресурсы документируют, какие поля рассматриваются для сопоставления в методе list . Эта функция аналогична универсальному поиску в интерфейсе Менеджера рекламы, но ограничена одним типом ресурса.

Строковые литералы, содержащие пробелы, следует заключать в двойные кавычки (пример: "Foo bar" ). Одинарные кавычки нельзя использовать для переноса строковых литералов.

Логические операторы

API Менеджера рекламы поддерживает бинарные операторы AND и OR .

Оператор Пример Значение
AND a AND b Верно, если a и b верны.
OR a OR b OR c Истинно, если какое-либо из a , b , c истинно.

Операторы отрицания

API Менеджера рекламы предоставляет унарные операторы NOT и - . Их можно использовать взаимозаменяемо.

Оператор Пример Значение
NOT NOT a Верно, если a не верно.
- -a Верно, если a не верно.

Операторы сравнения

API Менеджера рекламы поддерживает операторы двоичного сравнения = , != , < , > , <= и >= для строковых, числовых полей, полей метки времени и продолжительности.

Оператор Пример Значение
= a = true Верно, если a истинно.
!= a != 42 Истинно, если a не равно 42.
< a < 42 Истинно, если a — числовое значение меньше 42.
> a > "foo" Истинно, если a лексически упорядочен после «foo».
<= a <= "foo" Истинно, если a равно «foo» или лексически перед ним.
>= a >= 42 Истинно, если a — числовое значение 42 или выше.

Поскольку фильтры принимаются как строки запроса, происходит преобразование типов для перевода строки в соответствующее строго типизированное значение:

  • Строки ожидают двойных кавычек. Пример: "Foo bar" .
  • Перечисления ожидают строкового представления перечисления (с учетом регистра).
  • Булевы значения ожидают true и false литеральные значения.
  • Числа ожидают стандартные представления целых чисел или чисел с плавающей запятой. Для чисел с плавающей запятой поддерживаются показатели степени. Пример: 2.997e9 .
  • Длительность предполагает числовое представление, за которым следует суффикс s (для секунд). Примеры: "20s" , "1.2s" .
  • Метки времени ожидают строку в формате RFC-3339 . Пример: "2012-04-21T11:30:00-04:00" . Поддерживаются смещения UTC.

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

При сравнении строк на предмет равенства API Менеджера рекламы поддерживает подстановочные знаки с использованием символа * .

Пример Значение
a = "*.foo" Истинно, если a заканчивается на ".foo".

Оператор обхода

API Менеджера рекламы поддерживает формат . оператор, который указывает обход сообщения, карты или структуры.

Пример Значение
ab = true Истинно, если a имеет логическое поле b , которое истинно.
ab > 42 Истинно, если a имеет числовое поле b , превышающее 42.
abc = "foo" Истинно, если ab имеет поле строки c , имеющее значение «foo».

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

Имеет оператор

API Менеджера рекламы поддерживает оператор : , что означает «имеет». Его можно использовать с коллекциями (повторяющимися полями или картами), сообщениями и строками, и в каждом случае он ведет себя немного по-разному.

Строковые поля запрашивают, содержит ли строка соответствующую подстроку:

Пример Значение
r.displayName:"_250x250" Значение true, если строковое поле r.displayName содержит подстроку _250x250 .

Повторяющиеся поля запрашивают, содержит ли повторяющаяся структура соответствующий элемент:

Пример Значение
r:42 Истинно, если r содержит 42.
r.foo:42 Истинно, если r содержит элемент e такой, что e.foo = 42 .

Карты, структуры и сообщения могут запрашивать либо наличие поля на карте, либо конкретное значение:

Пример Значение
m:foo Истинно, если m содержит ключ «foo».
m.foo:* Истинно, если m содержит ключ «foo».
m.foo:42 Истинно, если m.foo равно 42.

При прохождении сообщений поле считается присутствующим только в том случае, если оно имеет значение, отличное от значения по умолчанию.

Ограничения

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

Заказ

Большинство ресурсов поддерживают упорядочивание методов List . Подробную информацию о поведении ресурса и о том, какие поля поддерживаются для упорядочивания, см. в документации по методу List

Синтаксис полей orderBy представляет собой список имен полей, разделенных запятыми. Например: "foo,bar" .

По умолчанию порядок сортировки — по возрастанию. Чтобы указать порядок убывания поля, добавьте суффикс " desc" . Например: "foo desc, bar" .

Избыточные пробелы в синтаксисе игнорируются. Значения "foo, bar desc" , " foo , bar desc " и "foo,bar desc" эквивалентны.

Подполя указываются с помощью оператора обхода . Например: foo.bar или address.street .