Filtrar respostas da lista

A maioria dos serviços na API Display & Video 360 oferece um método LIST para recuperação em massa de recursos. Esses métodos LIST geralmente oferecem suporte à filtragem de resultados usando um parâmetro de consulta filter. Use esse parâmetro para otimizar o uso da API, recuperando apenas o que você precisa.

Este guia mostra como usar o parâmetro filter de maneira eficaz.

Estrutura do filtro

Um valor de parâmetro filter é uma string que consiste em uma ou mais restrições que podem ser combinadas com os operadores AND ou OR e agrupadas usando parênteses.

As restrições têm o formato {field} {operator} {value}. Veja um exemplo:

entityStatus="ENTITY_STATUS_ACTIVE"

O comprimento da string de filtro não pode exceder 500 caracteres. Se a string de filtro tiver mais de 500 caracteres, faça o seguinte:

  • Divida a lógica em várias strings de filtro e extraia os recursos usando solicitações LIST separadas.
  • Remova parte da lógica da string de filtro e use-a para filtrar os recursos recuperados localmente.

Encapsule os valores de restrição entre aspas para garantir que a lógica seja aplicada corretamente.

Use a codificação de URL nas strings de filtro se você estiver fazendo chamadas LIST diretamente sem usar uma biblioteca de cliente.

Consulte Lógica entre restrições para mais detalhes sobre a formatação das consultas.

Campos que aceitam filtros

Os campos filtráveis de cada método LIST são listados na descrição do parâmetro filter do método. Na maioria dos casos, é possível filtrar um subconjunto dos campos padrão de um recurso. Em alguns casos raros, há outros campos que podem ser usados apenas para filtrar.

Cada campo na descrição do parâmetro aceita pelo menos um dos operadores comparáveis a seguir:

Operadores semelhantes
EQUALS (=) O valor do campo de recurso é igual ao valor fornecido.

Exemplo: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=) O valor do campo de recurso é menor ou igual ao valor fornecido. Usado com frequência ao comparar uma data ou data/hora.

Exemplo: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=) O valor do campo de recurso é maior ou igual ao valor especificado. Usado com frequência ao comparar uma data ou data/hora.

Exemplo: updateTime>="2023-03-01T12:00:00Z"
HAS (:) O valor do campo de recurso contém o valor fornecido. Se o campo de recurso for uma string, ele vai verificar se o valor fornecido é uma substring existente. Se o campo de recurso for uma matriz, ele vai verificar se a matriz contém o valor fornecido.

Exemplo: lineItemIds:"1234"

Se nenhum operador for especificado para o campo na descrição do parâmetro, só será possível usar o operador EQUALS (=). Alguns campos aceitam vários operadores.

Alguns campos filtráveis, como os de datas e horários, exigem que o valor comparável siga um formato específico. O formato é especificado ao lado do campo na descrição do parâmetro filter.

Lógica entre restrições

É possível combinar várias restrições para restringir ou ampliar a resposta da sua solicitação LIST.

Geralmente, é possível combinar várias restrições com operadores lógicos AND e OR. Cada método LIST especifica quais operadores são compatíveis. Alguns métodos só aceitam uma restrição no parâmetro filter.

Considere as seguintes restrições ao criar strings de filtro com operadores lógicos AND ou OR:

  • AND precisa ser usado entre restrições ou grupos de restrições que filtram campos diferentes ou filtram o mesmo campo de maneira diferente. Confira alguns exemplos:
    • 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 precisa ser usado entre restrições individuais que filtram pelo mesmo campo. Confira um exemplo:
    • (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")

  • Não é possível usar OR para combinar dois grupos de restrições. Use várias solicitações LIST com valores de filtro diferentes. Por exemplo, use as seguintes solicitações LIST separadas:

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

    Não use o operador OR para combiná-los:

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

  • Os parênteses podem ser implícitos se você não os usar para agrupar restrições em uma string de filtro. Por exemplo, a seguinte string de filtro:

    updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT"

    é interpretada como:

    updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")