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"
URL codificado: 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 associados 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 ser colocados entre aspas duplas (exemplo: "Foo bar"). As aspas simples não podem ser usadas para unir literais de string.

Operadores lógicos

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

Cuidado: esses operadores diferenciam maiúsculas de minúsculas. Os literais and e or são tratados como literais.

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ão.

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 estiver 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 só aceita 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 o número inteiro padrão ou representações flutuantes. Para flutuações, 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 de 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 termina com ".foo".

Operador de traversal

A API Ad Manager oferece suporte ao operador ., que indica a transposição 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 é escrita usando os nomes de campos 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 tiver a chave "foo".
m.foo:42	Verdadeiro se m.foo for 42.

Ao transferir mensagens, um campo só será considerado presente se tiver um valor não padrão.

Limitações

Os serviços individuais podem especificar outras estruturas ou limitações para consultas de filtro além do que está definido aqui.

Pedido

A API Ad Manager oferece suporte ao pedido em métodos List. A sintaxe dos campos orderBy é uma lista separada por vírgulas de nomes de campo. Por exemplo, "foo,bar".

A ordem de classificação padrão é crescente. 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.