Filtros

A API Ad Manager oferece suporte à filtragem em métodos List. A sintaxe da string de filtro é formalmente definida na gramática EBNF.

Para começar, confira alguns exemplos de casos de uso comuns.

Exemplo	Significado
orders.updateTime > "2024-01-01T00:00:00-5:00"	Lista pedidos com um updateTime após 1º de janeiro de 2024 no fuso horário padrão do leste
lineItems.targeting.geoTargeting.targetedGeoIds:2840	Lista itens de linha com uma segmentação geográfica que contém os Estados Unidos (ID de segmentação geográfica 2480)
lineItems.displayName = "*_interstitial"	Lista os itens de linha que têm um nome de exibição que termina com a string _interstitial
orders.displayName = "*video*"	Lista pedidos que têm um nome de exibição que contém a string video
displayName:"video"	Lista pedidos que têm um nome de exibição que contém a string video (sintaxe alternativa)

Dica: o filtro precisa ser codificado como URL para solicitações GET. Por exemplo: string de filtro: orders.updateTime > "2024-01-01T00:00:00-5:00" codificado em URL: orders.updateTime%20%3E%20%222024-01-01T00:00:00-5:00%22. Isso é processado automaticamente pelas bibliotecas de cliente.

Literais

Um valor literal simples (exemplos: 42, Hugo) é um valor a ser comparado. Os literais que aparecem sozinhos são correspondidos de forma aproximada a todos os campos compatíveis em um recurso. Os recursos documentam quais campos são considerados para correspondência no método list. Esse recurso é semelhante à pesquisa universal na interface do Ad Manager, mas limitado a um único tipo de recurso.

Os literais de string que contêm espaços precisam estar entre aspas duplas (por exemplo, "Foo bar"). Aspas simples não podem ser usadas para envolver literais de string.

Operadores lógicos

A API Ad Manager oferece suporte aos operadores binários AND e OR.

Atenção: esses operadores diferenciam maiúsculas e minúsculas. Os literais and e or são tratados como Literals.

Operador	Exemplo	Significado
AND	a AND b	Verdadeiro se a e b forem verdadeiros.
OR	a OR b OR c	Verdadeiro se qualquer um dos valores a, b ou c for verdadeiro.

Observação: para corresponder a padrões comuns de fala, o operador OR tem precedência mais alta que AND, ao contrário do que é encontrado na maioria das linguagens de programação. A expressão a AND b OR c é avaliada como a AND (b OR c). Quando possível, use parênteses explícitos para evitar confusões.

Operadores de negação

A API Ad Manager oferece os operadores unários NOT e -. Eles podem ser usados de forma intercambiável.

Operador	Exemplo	Significado
NOT	NOT a	Verdadeiro se a não for verdadeiro.
-	-a	Verdadeiro se a não for verdadeiro.

Operadores de comparação

A API Ad Manager oferece suporte aos operadores de comparação binária =, !=, <, >, <= e >= para campos de string, numérico, carimbo de data/hora e duração.

Operador	Exemplo	Significado
=	a = true	Verdadeiro se a for verdadeiro.
!=	a != 42	Verdadeiro, a menos que a seja igual a 42.
<	a < 42	Verdadeiro se a for um valor numérico menor que 42.
>	a > "foo"	Verdadeiro se a for ordenado lexicalmente após "foo".
<=	a <= "foo"	Verdadeiro se a for "foo" ou lexicalmente antes dele.
>=	a >= 42	Verdadeiro se a for um valor numérico de 42 ou mais.

Observação: ao contrário da maioria das linguagens de programação, os nomes de campo precisam aparecer no lado esquerdo de um operador de comparação. O lado direito aceita apenas operadores lógicos e literais.

Como os filtros são aceitos como strings de consulta, a conversão de tipo ocorre para traduzir a string para o valor fortemente tipado apropriado:

• As strings esperam aspas duplas. Exemplo: "Foo bar".
• Os tipos enumerados esperam a representação de string do tipo enumerado (diferenciação entre maiúsculas e minúsculas).
• Os booleanos esperam valores literais true e false.
• Os números esperam as representações padrão de números inteiros ou de ponto flutuante. Para números flutuantes, os expoentes são aceitos. Exemplo: 2.997e9.
• As durações esperam uma representação numérica seguida de um sufixo s (para segundos). Exemplos: "20s", "1.2s".
• Os carimbos de data/hora esperam uma string formatada RFC-3339. Exemplo: "2012-04-21T11:30:00-04:00". As compensações UTC são aceitas.

Cuidado: os identificadores true, false e null só têm significado intrínseco quando usados no contexto de uma referência de campo digitada.

Caracteres curinga

Ao comparar strings para igualdade, a API Ad Manager oferece suporte a caracteres curinga usando o caractere *.

Exemplo	Significado
a = "*.foo"	Verdadeiro se a terminar com ".foo".

Operador de traversal

A API Ad Manager é compatível com o operador ., que indica a travessia por uma mensagem, um mapa ou uma estrutura.

Exemplo	Significado
a.b = true	Verdadeiro se a tiver um campo b booleano verdadeiro.
a.b > 42	Verdadeiro se a tiver um campo b numérico maior que 42.
a.b.c = "foo"	Verdadeiro se a.b tiver um campo c de string "foo".

A travessia é gravada usando os nomes de campo do recurso. Serviços individuais podem especificar um subconjunto de campos com suporte para a travessia.

Importante: o operador . não pode ser usado para percorrer um campo ou uma lista repetida, exceto para uso específico com o operador :.

Tem operador

A API Ad Manager é compatível com o operador :, que significa "tem". Ele pode ser usado com coleções (campos ou mapas repetidos), mensagens e strings e se comporta de maneira um pouco diferente em cada caso.

Consulta de campos de string para saber se a string contém uma substring correspondente:

Exemplo	Significado
r.displayName:"_250x250"	Verdadeiro se o campo de string r.displayName contiver a substring _250x250.

Consulta de campos repetidos para saber se a estrutura repetida contém um elemento correspondente:

Exemplo	Significado
r:42	Verdadeiro se r contiver 42.
r.foo:42	Verdadeiro se r contiver um elemento e de modo que e.foo = 42.

Importante: os filtros não podem consultar um elemento específico em um campo repetido para um valor. Por exemplo, e.0.foo = 42 e e[0].foo = 42 não são filtros válidos.

Mapas, structs e mensagens podem consultar a presença de um campo no mapa ou um valor específico:

Exemplo	Significado
m:foo	Verdadeiro se m contiver a chave "foo".
m.foo:*	Verdadeiro se m contiver a chave "foo".
m.foo:42	Verdadeiro se m.foo for 42.

Ao percorrer mensagens, um campo só é considerado presente se tiver um valor diferente do padrão.

Limitações

Serviços individuais podem especificar mais estrutura ou limitações para consultas de filtro, além do que é definido aqui.

Pedido

A maioria dos recursos oferece suporte a ordenação em métodos List. Consulte a documentação do método List para saber o comportamento exato do recurso e quais campos são aceitos para ordenação.

A sintaxe dos campos orderBy é uma lista de nomes de campos separados por vírgulas. Por exemplo: "foo,bar".

A ordem de classificação padrão é ascendente. Para especificar a ordem decrescente de um campo, anexe um sufixo " desc". Por exemplo, "foo desc, bar".

Caracteres de espaço redundantes na sintaxe são ignorados. Os valores "foo, bar desc", " foo , bar desc " e "foo,bar desc" são equivalentes.

Os subcampos são especificados com o operador de travessia. Por exemplo: foo.bar ou address.street.