Uso e sintaxe do filtro de lista

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. Um expression é 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:

1. NOT
2. OR
3. 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.	1234.567 -789.0123
Número inteiro	Qualquer número sem um ponto decimal, com ou sem um sinal ("-") é tratado como um número inteiro.	1234 -789

String

Nesta seção, descrevemos os tipos que podem ser escritos como um literal de string na sintaxe de filtro.

Observação :um literal de string pode estar entre aspas duplas (" ") ou sem aspas. Não é possível usar aspas simples para representar um literal de string. Por exemplo, "ABC DEF" e ABC DEF são literais de string, mas "ABC DEF" não é.

Tipo	Definição	Exemplos
Booleano	TRUE ou FALSE em qualquer letra maiúscula.	TRUE True "true"
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.	name = "test \"double quotes\"" name=(ABC DEF) é equivalente a name=ABC AND name=DEF
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.

Observação: para valores armazenados como strings, só é possível usar os operadores "!=", "=" e ":". A comparação de strings não diferencia maiúsculas de minúsculas.

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 que name é uma string que contém "abcd".

Verificação da existência

Quando você usa o operador HAS com o caractere especial *, o operador HAS verifica se há valores não nulos. Por exemplo, name:* retorna todas as instâncias em que name 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 operador EQUALS (=). Por exemplo, isCompleted:true se comporta da mesma maneira que isCompleted = 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:

1. Há apenas um componente repetido ao longo do caminho do identificador de campo.
2. 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 campo colors, 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 campo colors.
• item.colors:("red" "yellow") retorna todos os itens que têm "red" e "yellow" no campo colors.
• item.colors:("red" OR "yellow") retorna todos os itens que têm "red" ou "yellow" no campo colors.

item também tem um campo tools repetido que é um objeto complexo com um campo escalar shape, 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".

Observação :nem todos os campos repetidos podem ser filtrados. Para mais detalhes sobre um recurso específico, consulte a documentação de referência.

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 = 93641	advertiserId que tem um valor inteiro 93641.
isSetupComplete = true isSetupComplete:TRUE 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 displayName = "proposal" 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 != "proposal"	displayName não é igual a "proposta".
proposalState = (PROPOSED OR BUYER_ACCEPTED) proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED	proposalState tem um valor de enumeração que é igual a PROPOSED OU BUYER_AcceptED.
proposalState = (PROPOSED AND BUYER_ACCEPTED) proposalState = (PROPOSED BUYER_ACCEPTED) proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED proposalState = PROPOSED proposalState = 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 = "Test1" OR dealName = "Test2"	dealName é igual a "Test1" ou a "Test2".
dealName:*	dealName is not null.
dealName:"test" dealName:test	dealName contém a substring "test".
dealName:("A B") dealName:"A B"	dealName contém a substring "A B".
dealName:(A B) dealName:"A" AND dealName:"B"	dealName contém a substring "A" e a substring "B".
dealName:("A" OR "B" AND "C") dealName:("A" OR "B" "C") dealName:"A" OR dealName:"B" AND dealName:"C" dealName:"A" OR dealName:"B" dealName:"C" (dealName:"A" OR dealName:"B") AND dealName:"C" (dealName:"A" OR dealName:"B") dealName:"C"	dealName contém a substring "A" OU "B" E também contém a substring "C"
dealName:("A B" C) dealName:"A B" AND dealName:"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) NOT dealName:"A" AND dealName:"B" (NOT dealName:"A") AND dealName:"B" (NOT dealName:"A") dealName:"B"	dealName não contém nenhuma substring "A" e também contém a substring "B".
dealName:(NOT "A" OR "B") NOT dealName:"A" OR dealName:"B" (NOT dealName:"A") OR dealName:"B"	dealName não contém a substring "A" nem a substring "B".