Фильтрация ответов по списку

Большинство сервисов Display & Video 360 API предоставляют метод LIST для массового получения ресурсов. Эти методы LIST обычно поддерживают фильтрацию результатов с помощью параметра запроса filter . Используйте этот параметр, чтобы оптимизировать использование API, получая только то, что вам нужно.

В этом руководстве показано, как эффективно использовать параметр filter .

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

Значение параметра filter — это строка, состоящая из одного или нескольких ограничений, которые можно комбинировать с помощью операторов AND или OR и группировать с помощью круглых скобок.

Ограничения имеют вид {field} {operator} {value} . Вот пример:

entityStatus="ENTITY_STATUS_ACTIVE"

Длина строки фильтра не может превышать 500 символов. Если строка фильтра превышает 500 символов, выполните одно из следующих действий:

  • Разделите логику на несколько строк фильтра и извлеките ресурсы, используя отдельные запросы LIST .
  • Удалите часть логики из строки фильтра и используйте ее для локальной фильтрации полученных ресурсов.

Заключите значения ограничений в кавычки, чтобы обеспечить правильное применение логики.

URL-кодируйте строки фильтра, если вы выполняете вызовы LIST напрямую, без использования клиентской библиотеки.

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

Фильтруемые поля

Фильтруемые поля каждого метода LIST перечислены в описании параметра 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 (=) . Некоторые поля поддерживают несколько операторов.

Некоторые фильтруемые поля, например поля для дат и времени, требуют, чтобы сопоставимое значение соответствовало определенному формату. Формат указывается рядом с полем в описании параметра filter .

Логика между ограничениями

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

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

Учитывайте следующие ограничения при построении строк фильтра с логическими операторами AND или OR :

  • AND необходимо использовать между ограничениями или группами ограничений, которые фильтруют разные поля или по-разному фильтруют одно и то же поле. Вот несколько примеров:
    • updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE"
    • 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 с разными значениями фильтра. Например, используйте следующие отдельные запросы LIST :

    • (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
    • (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")

    Не используйте оператор OR для их объединения:

    (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123") OR (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")