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: |
|
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: |
|
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: |
|
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: |
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
:
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çõesLIST
com valores de filtro diferentes. Por exemplo, use as seguintes solicitaçõesLIST
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")