Filtrar respostas da lista

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

Neste guia, mostramos 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 são no 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 exceder 500 caracteres, siga um destes procedimentos:

• Divida a lógica em várias strings de filtro e recupere 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.

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

Codifique as strings de filtro em URL se 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á campos adicionais que podem ser usados apenas para filtragem.

Cada campo na descrição do parâmetro é compatível com pelo menos um dos seguintes operadores comparáveis:

Operadores comparáveis
EQUALS (=)	O valor do campo do recurso é igual ao valor fornecido. Exemplo: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=)	O valor do campo do recurso é menor ou igual ao valor informado. Geralmente usado ao comparar uma data ou data e hora. Exemplo: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=)	O valor do campo de recurso é maior ou igual ao valor informado. Geralmente usado ao comparar uma data ou data e hora. Exemplo: updateTime>="2023-03-01T12:00:00Z"
HAS (:)	O valor do campo de recurso contém o valor fornecido. Se o campo "resource" for uma string, ele vai verificar se o valor fornecido é uma substring existente. Se o campo de recurso for uma matriz, ela vai verificar se ela contém o valor informado. Exemplo: lineItemIds:"1234"

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

Alguns campos filtráveis, como os de datas e horas, 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 expandir a resposta da sua solicitação LIST.

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

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

Observação :os exemplos a seguir foram escritos usando as restrições de parâmetro do método advertisers.lineItems.list filter.

• AND precisa ser usado entre restrições ou grupos de restrições que filtrem campos diferentes ou que filtrem o mesmo campo de maneira diferente. Veja 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á-las:

  (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 usa 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")