Запросы списка фильтров

Методы list извлекают несколько ресурсов заданного типа. Параметр запроса filter позволяет задать критерии, которым должны соответствовать извлекаемые ресурсы.

Структура фильтра

Значения параметров filter представляют собой строки. Эти строки состоят из одного или нескольких критериев. Критерии объединяются с помощью операторов AND или OR .

Один критерий имеет вид {field} {operator} {value} . Вот пример:

  entityStatus="ENTITY_STATUS_ACTIVE"

Строки фильтров ограничены 500 символами. Если ваша строка слишком длинная:

  • Разбейте логику на отдельные строки. Выполните вызов list для каждой строки фильтра. Объедините результаты в один список.
  • Удалите критерии из строки фильтра. Используйте удаленные критерии для локальной фильтрации полученных ресурсов.

Заключите значения критерия в кавычки.

Убедитесь, что ваши фильтрующие строки закодированы для использования в URL-адресе при выполнении прямых вызовов API.

Дополнительную информацию о структуре строки фильтра см. в разделе « Критерии объединения» .

Критерии фильтрации

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

Каждый критерий поддерживает один или несколько операторов:

Аналогичные операторы
EQUALS (=)

Поле равно заданному значению.

Пример: entityStatus="ENTITY_STATUS_ACTIVE"

LESS THAN OR EQUAL TO (<=)

Значение поля меньше или равно заданному значению. Часто используется для фильтрации по дате или времени.

Пример: updateTime<="2023-04-01T12:00:00Z"

GREATER THAN OR EQUAL TO (>=)

Значение поля больше или равно заданному значению. Часто используется для фильтрации по дате или времени.

Пример: updateTime>="2023-03-01T12:00:00Z"

HAS (:)

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

Пример: lineItemIds:"1234"

Если в критерии не указан оператор, поддерживается только EQUALS (=) .

Критерий укажет, если требуется специальный формат.

Критерии присоединения

Объедините несколько критериев, чтобы дополнительно сузить list ответов.

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

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

Ограничения и примеры
AND должны объединять ограничения или группы ограничений, которые фильтруют разные поля или фильтруют одно и то же поле по-разному. updateTime>="2023-03-01T12:00:00Z" AND updateTime<="2023-04-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED")
OR необходимо объединить отдельные ограничения, фильтрующие по одному и тому же полю. (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")
OR нельзя объединять две группы ограничений. Вместо этого используйте несколько запросов list с разными значениями фильтра. Следующие две строки фильтра должны использоваться в отдельных запросах и не могут быть объединены с помощью оператора OR :
  • (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
  • (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")
Скобки могут подразумевать ограничения группы, даже если они не включены в текст. Строка фильтра updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT" интерпретируется как updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")