Este guia descreve a sintaxe de filtro de lista e como filtrar vários de tipos de recursos.
Alguns métodos da API podem aceitar um filtro para limitar os recursos retornados na resposta.
Resumo
Esta seção fornece uma visão geral rápida da estrutura da sintaxe do filtro da lista.
Um filtro é uma string que contém um
expression
. Umexpression
é um booleano combinação de comparações:expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison } expression = ( expression )
Um
comparison
corresponde a um campo de recurso com um valor. Você pode usar todos operadores de comparação comuns.comparison = name OP value OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
O operador
has
, dois-pontos (:
), pode ser usado em strings e campos. Consulte a seção Tem operador para ver mais detalhes.É possível usar os seguintes tipos de valores em filtros:
- Numbers
- Strings
- Expressões entre parênteses
value = number| string | "*" | "(" expression ")"
As strings podem representar o seguinte:
- Texto arbitrário
- Booleanos
- Valores de tipo enumerado
- Carimbos de data/hora
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 seguintes expressões 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 seguintes
e os filtros são os mesmos:
c=d AND e=f
c=d e=f
É possível 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, o
filtros a seguir são iguais:
NOT e=f
-e=f
Comparações
Nesta seção, descrevemos comparações de "name OP value"
da seguinte maneira:
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. Para
exemplo, considere um recurso com um campo complexo item
que tem outro
um campo complexo tool
, que tem um campo chamado shape
. Em um filtro para este
você se referiria a uma forma com o nome item.tool.shape
.
O lado direito é normalmente um valor escalar que é convertido na e comparados com ele. Veja os tipos de valor literal para mais detalhes.
O lado direito de uma comparação também pode ser expresso como um booleano 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, o
filtros a seguir são iguais:
deal.name = ("test 1" OR "test 2")
deal.name = "test 1" OR deal.name = "test 2"
Aqui está outro exemplo mais complexo de duas funções filtros:
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 "Número" e Literais de string.
Número
Esta seção descreve a representação de literais numéricos.
Tipo | Definição | Exemplos |
---|---|---|
Duplo | Qualquer número que contenha um ponto decimal, com ou sem sinal ("-") é tratado como um Double. |
|
Número inteiro | Qualquer número sem ponto decimal, com ou sem sinal ("-") é tratado como um número inteiro. |
|
String
Esta seção descreve os tipos que você pode gravar como um literal de string na a sintaxe de filtro.
Tipo | Definição | Exemplos |
---|---|---|
Booleano | TRUE ou FALSE em letras minúsculas ou maiúsculas. |
|
Enumeração | O nome de um literal de tipo de enumeração. Os tipos enumerados diferenciam maiúsculas de minúsculas. |
FINALIZED não é o mesmo que 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ço em branco são tratadas como "E" implícito entre todas as palavras após dividir a string 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
Veja 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 valores Double, Integer, Boolean, Enum e Timestamp tipos
Tem operador
É possível usar o operador HAS
(:
) para operações especiais nos
:
- Substrings
- Quando o operador
HAS
é usado para comparar valores em uma coluna de strings com um string, o operador atuará como uma operação de substring. Por exemplo:name:"abcd"
retorna todas as instâncias em quename
é uma string contendo"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 não strings, ele se comporta da mesma forma que o operadorEQUALS
(=
). Por exemplo,isCompleted:true
se comporta na da mesma forma queisCompleted = true
. - Campos repetidos
É possível usar o operador
HAS
(:
) para filtrar um recurso de API repetido , desde que as seguintes condições sejam verdadeiras:- Há apenas um componente repetido no caminho do identificador de campo.
- O último identificador do caminho do campo é do tipo escalar.
Não é possível filtrar campos repetidos aninhados.
Veja 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"
nocolors
.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 escalar camposhape
, cujos valores podem ser"square"
ou"round"
.item.tools.shape:("square")
retorna todos os itens que têm formato de"square"
. ferramentas de visualização.item.tools.shape:("square" "round")
retorna todos os itens que têm um Ferramenta no formato"square"
e outra no formato"round"
.item.tools.shape:("square" OR "round")
retorna todos os itens que têm um Ferramenta de forma"square"
ou uma ferramenta de forma"round"
.
Campos aninhados não preenchidos
Campos aninhados são subcampos de campos de nível raiz, por exemplo, shape
em
item.tools.shape
é um campo aninhado de items.tools
.
O padrão dos campos no nível raiz é "false". Os campos aninhados não são preenchidos por padrão.
Objetos com campos aninhados não preenchidos não são retornados por valores
(!=
).
Veja 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 foi
retornar 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" AND pitchRevision for igual a 3. |
displayName = "proposal" OR proposalRevision = 3 |
displayName tem o valor de string "proposta". 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 igual a PROPOSED OU acusado de compras. |
proposalState = (PROPOSED AND BUYER_ACCEPTED) |
proposalState tem um valor de enumeração igual a PROPOSED e acusado de compras. |
dealName = Test Deal |
Expressão INVALID |
dealName = "Test Deal" |
dealName é igual a "Testar negócio". |
dealName = (Test Deal) |
dealName é igual a "Teste" e também igual a "Deal". |
dealName = ("Test1" OR "Test2") |
dealName é igual a "Test1" ou igual 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 contém a substring "C". |
dealName:("A B" OR C D) |
dealName contém a substring "A B" ou "C" e também contém a 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 nenhuma substring "A" ou contém a substring "B". |