Os métodos list recuperam vários recursos de um tipo definido. O parâmetro de consulta filter permite especificar critérios que os recursos recuperados precisam atender.
Estrutura do filtro
Os valores do parâmetro filter são strings. Essas strings são compostas por um ou mais
critérios. Os critérios são unidos pelos operadores AND ou OR.
Um único critério tem a forma {field} {operator} {value}. Veja um exemplo:
entityStatus="ENTITY_STATUS_ACTIVE"
As strings de filtro são limitadas a 500 caracteres. Se a string for muito longa:
- Divida a lógica em strings separadas. Faça uma chamada
listcom cada string de filtro. Combine os resultados para criar uma única lista. - Remove critérios da string de filtro. Use os critérios removidos para filtrar os recursos recuperados localmente.
Coloque os valores de um critério entre aspas.
Verifique se as strings de filtro estão codificadas para uso em um URL ao fazer chamadas de API diretamente.
Consulte a seção Critérios de junção para saber mais sobre a estrutura da string de filtro.
Critérios de filtro
Cada método de lista aceita determinados critérios de filtro. A descrição do parâmetro filter do método lista esses critérios. Os critérios de filtro geralmente são um subconjunto dos campos do recurso recuperado.
Cada critério é compatível com um ou mais operadores:
| Operadores comparáveis | |
|---|---|
EQUALS (=)
|
O campo é igual ao valor especificado. Exemplo: |
LESS THAN OR EQUAL TO (<=)
|
O campo é menor ou igual ao valor especificado. Geralmente usado para filtrar por uma data ou data e hora. Exemplo: |
GREATER THAN OR EQUAL TO (>=)
|
O campo é maior ou igual ao valor especificado. Geralmente usado para filtrar por uma data ou data e hora. Exemplo: |
HAS (:)
|
O campo contém o valor especificado. Se o campo for uma string, ele vai verificar se o valor informado é uma substring. Se o campo for uma matriz, ele vai verificar se o valor especificado está presente. Exemplo: |
Se um critério não especificar um operador, ele só vai aceitar EQUALS (=).
Um critério vai indicar se ele precisa de um formato especial.
Critérios de junção
Combine vários critérios para restringir ainda mais a resposta do list.
Combine critérios com os operadores lógicos AND e OR. Cada método list especifica quais são compatíveis. Alguns métodos só aceitam filtros com um critério.
Considere estes limites ao usar vários critérios:
| Limitações e exemplos | |
|---|---|
AND precisa combinar restrições ou grupos de restrições que filtram campos diferentes ou o mesmo campo de maneiras diferentes.
|
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 combinar restrições individuais que filtram pelo mesmo campo.
|
(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 combinar dois grupos de restrições.OR Em vez disso, use várias solicitações list com valores de filtro diferentes.
|
As duas strings de filtro a seguir precisam ser usadas em solicitações separadas e não podem ser combinadas usando o operador OR:
|
| Os parênteses podem ser implícitos para agrupar restrições, mesmo que não estejam incluídos. |
A 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")
|