Neste guia, descrevemos a sintaxe do filtro de lista e como filtrar vários tipos de recursos.
Alguns métodos da API podem aceitar um filtro para limitar os recursos retornados na resposta.
Resumo
Nesta seção, você encontra uma visão geral da estrutura da sintaxe de filtro da lista.
Um filtro é uma string que contém uma
expression
. Umexpression
é uma combinação booleana de comparações:expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison } expression = ( expression )
Um
comparison
corresponde a um campo de recurso a um valor. É possível usar todos os operadores de comparação comuns.comparison = name OP value OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
O operador
has
, dois pontos (:
), pode ser usado em strings e campos repetidos. Consulte a seção Com operador para mais detalhes.Você pode usar os seguintes tipos de valores em filtros:
- Números
- Strings
- Expressões entre parênteses
value = number| string | "*" | "(" expression ")"
As strings podem representar o seguinte:
- Texto arbitrário
- booleanos
- Valores de enumeração
- Marcações de tempo
Expressões booleanas
expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}
As operações são feitas na seguinte ordem:
NOT
OR
AND
Por exemplo, as expressões a seguir são equivalentes:
a OR NOT b AND NOT c OR d
(a OR (NOT b)) AND ((NOT c) OR d)
É possível omitir o operador AND
entre comparações. Por exemplo, os filtros a seguir são os mesmos:
c=d AND e=f
c=d e=f
Você pode usar o hífen (-
) como alternativa para NOT
. Não pode haver um espaço entre o hífen (-
) e a comparação a seguir. Por exemplo, os
filtros a seguir são iguais:
NOT e=f
-e=f
Comparações
Esta seção descreve comparações de "name OP value"
como estas:
comparison = name OP value
onde
OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"
O lado esquerdo de uma comparação é o nome do caminho de um campo de recurso da API.
O nome consiste em uma série de identificadores de recursos conectados por ponto (.
).
Cada identificador de campo é seguido pelo próximo nível de nomes desse campo. Por exemplo, considere um recurso com um campo complexo item
que tenha outro campo complexo tool
, que tenha um campo chamado shape
. Em um filtro para esse
recurso, você se referiria a uma forma com o nome item.tool.shape
.
O lado direito é normalmente um valor escalar que é convertido no tipo do campo e comparado com ele. Consulte a seção de tipos de literal de valor para saber mais.
O lado direito de uma comparação também pode ser expresso como uma combinação booleana
entre parênteses de valores literais e/ou expressões booleanas que contêm apenas
valores literais (precedidos com ou sem NOT
). O nome do lado esquerdo e o
operador de comparação são aplicados a cada um dos valores. Por exemplo, os
filtros a seguir são iguais:
deal.name = ("test 1" OR "test 2")
deal.name = "test 1" OR deal.name = "test 2"
Veja outro exemplo mais complexo de dois filtros equivalentes:
deal.name = ("test 1" OR "test 2" AND (NOT "test3" OR "test4"))
(deal.name = "test 1" OR deal.name = "test 2") AND ( (NOT deal.name = "test3") OR deal.name = "test4")
Tipos de literal de valor
O valor do lado direito de um operador de comparação pode ser categorizado em literais de número e de string.
Número
Nesta seção, descrevemos a representação de literais numéricos.
Tipo | Definição | Exemplos |
---|---|---|
Rebatida dupla | Qualquer número que contenha um ponto decimal, com ou sem um sinal ("-") é tratado como um duplo. |
|
Número inteiro | Qualquer número sem um ponto decimal, com ou sem um sinal ("-") é tratado como um número inteiro. |
|
String
Nesta seção, descrevemos os tipos que podem ser escritos como um literal de string na sintaxe de filtro.
Tipo | Definição | Exemplos |
---|---|---|
Booleano | TRUE ou FALSE em qualquer letra maiúscula. |
|
Enumeração | O nome de um literal de tipo de enumeração. Os tipos enumerados diferenciam maiúsculas de minúsculas. |
FINALIZED é diferente de Finalized
|
String | Qualquer string que contenha texto codificado em UTF-8 ou ASCII de 7 bits. Aspas incorporadas precisam ser precedidas de uma barra invertida. Strings sem aspas com espaços em branco são tratadas como "AND" implícito entre todas as palavras depois de serem divididas por espaços em branco. |
|
Carimbo de data/hora | Uma string no formato padrão ISO8601. |
"2014-10-02T15:01:23.045Z"
|
Operadores de comparação
Estes são os operadores de comparação:
- Menor ou igual a:
"<="
- Menor que:
"<"
- Maior ou igual a:
">="
- Maior que:
">"
- Diferente de:
"!="
- Igual a:
"="
- Tem:
":"
Esses operadores se aplicam aos tipos de valor Double, Integer, Boolean, Enum e Timestamp.
Tem operador
É possível usar o operador HAS
(:
) para operações especiais nos seguintes campos:
- Substrings
- Quando o operador
HAS
é usado para comparar valores em uma coluna de string com uma string, ele atua como uma operação de substring. Por exemplo,name:"abcd"
retorna todas as instâncias em quename
é uma string que contém"abcd"
. - Verificação da existência
- Quando você usa o operador
HAS
com o caractere especial*
, o operadorHAS
verifica se há valores não nulos. Por exemplo,name:*
retorna todas as instâncias em quename
não é nulo, ausente ou indefinido. - Quando você usa o operador
HAS
com valores que não são de string, ele se comporta da mesma forma que o operadorEQUALS
(=
). Por exemplo,isCompleted:true
se comporta da mesma maneira queisCompleted = true
. - Campos repetidos
Você pode usar o operador
HAS
(:
) para filtrar um campo repetido de recurso de API, desde que as seguintes condições sejam verdadeiras:- Há apenas um componente repetido ao longo do caminho do identificador de campo.
- O último identificador do caminho do campo é de tipo escalar
A filtragem em campos repetidos aninhados não é compatível.
Confira um exemplo:
item
tem um campocolors
, que contém valores de string como"red"
,"blue"
e"yellow"
.item.colors:("red")
retorna todos os itens que têm o valor"red"
no campocolors
.item.colors:("red" "yellow")
retorna todos os itens que têm"red"
e"yellow"
no campocolors
.item.colors:("red" OR "yellow")
retorna todos os itens que têm"red"
ou"yellow"
no campocolors
.
item
também tem um campotools
repetido que é um objeto complexo com um campo escalarshape
, com valores que podem ser"square"
ou"round"
.item.tools.shape:("square")
retorna todos os itens que têm ferramentas em forma de"square"
.item.tools.shape:("square" "round")
retorna todos os itens que têm uma ferramenta em forma de"square"
e uma ferramenta em forma de"round"
.item.tools.shape:("square" OR "round")
retorna todos os itens que têm uma ferramenta de forma"square"
ou"round"
.
Campos aninhados não preenchidos
Os campos aninhados são subcampos de campos no nível raiz. Por exemplo, shape
em item.tools.shape
é um campo aninhado de items.tools
.
Os campos no nível raiz são definidos como falsos por padrão. Por padrão, os campos aninhados não são preenchidos.
Objetos com campos aninhados não preenchidos não são retornados por filtros
negativos (!=
).
Confira um exemplo:
item.tools
tem um tipo enumerado size
, cujo valor pode ser definido como "SMALL"
, "MEDIUM"
ou "LARGE"
.
Se você tiver os seguintes itens:
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
},
{
"name": "item3"
}
Uma chamada para items.list
com o filtro negativo "tools.size != SMALL"
retorna o seguinte:
{
"items": [
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
}
]
}
Como item.tools.size
não foi definido para item3
, o filtro negativo não
retorna o objeto item3
.
Exemplos
Exemplo | Descrição |
---|---|
externalDealId = "123456789" |
externalDealId que tem um valor de string "123456789". |
advertiserId:93641 |
advertiserId que tem um valor inteiro 93641. |
isSetupComplete = true |
isSetupComplete é igual a TRUE. |
updateTime > "2018-02-14T11:09:19.378Z" |
updateTime é posterior a 14/02/2018 11:09:19.378 UTC |
displayName = "proposal" AND proposalRevision = 3 |
A string displayName tem um valor idêntico de "proposta" E a propostaRevision é igual a 3. |
displayName = "proposal" OR proposalRevision = 3 |
displayName tem um valor de string "Proposal" OU a propostaRevision é igual a 3. |
NOT displayName = "proposal" |
displayName não é igual a "proposta". |
proposalState = (PROPOSED OR BUYER_ACCEPTED) |
proposalState tem um valor de enumeração que é igual a PROPOSED OU BUYER_AcceptED. |
proposalState = (PROPOSED AND BUYER_ACCEPTED) |
proposalState tem um valor de enumeração que é igual a PROPOSED E BUYER_AcceptED |
dealName = Test Deal |
Expressão INVALID |
dealName = "Test Deal" |
dealName é igual a "Testar transação". |
dealName = (Test Deal) |
dealName é igual a "Teste" e também a "Transação". |
dealName = ("Test1" OR "Test2") |
dealName é igual a "Test1" ou a "Test2". |
dealName:* |
dealName is not null. |
dealName:"test" |
dealName contém a substring "test". |
dealName:("A B") |
dealName contém a substring "A B". |
dealName:(A B) |
dealName contém a substring "A" e a substring "B". |
dealName:("A" OR "B" AND "C") |
dealName contém a substring "A" OU "B" E também contém a substring "C" |
dealName:("A B" C) |
dealName contém a substring "A B" e também a substring "C". |
dealName:("A B" OR C D) |
dealName contém a substring "A B" ou "C", além da substring "D". |
dealName:(NOT "A" B) |
dealName não contém nenhuma substring "A" e também contém a substring "B". |
dealName:(NOT "A" OR "B") |
dealName não contém a substring "A" nem a substring "B". |