Filtros

A API REST do Ad Manager é compatível com a filtragem nos métodos List. A sintaxe da string de filtro é definida formalmente na gramática EBNF (link em inglês).

Para começar, aqui estão alguns exemplos de casos de uso comuns.

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

Dica :o filtro precisa ser codificado em URL para solicitações GET. Por exemplo:
String do 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 é gerenciado automaticamente pelas bibliotecas de cliente.

Literais

Um valor literal básico (exemplos: 42, Hugo) é um valor a ser correspondido. Os literais que aparecem sozinhos são combinados em 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 é comparável à pesquisa universal na IU do Ad Manager, mas com escopo para um único tipo de recurso.

Os literais de string que contêm espaços precisam ser colocados entre aspas duplas (exemplo: "Foo bar"). Não é possível usar aspas simples para unir literais de string.

Operadores lógicos

A API REST do Ad Manager é compatível com os 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 a, b ou c for verdadeiro.

Observação: para corresponder a padrões de fala comuns, o operador OR tem precedência maior 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). Sempre que possível, use parênteses explícitos para evitar confusão.

Operadores de negação

A API REST do Ad Manager fornece os operadores unários NOT e -. Eles podem ser usados como sinônimos.

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 REST do Ad Manager é compatível com os operadores de comparação binários =, !=, <, >, <= 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 lexicamente após "foo".
<=	a <= "foo"	Verdadeiro se a for "foo" ou lexicamente antes dele.
>=	a >= 42	Verdadeiro se a for um valor numérico de 42 ou maior.

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

Como os filtros são aceitos como strings de consulta, a conversão de tipos ocorre para converter a string para o valor fortemente tipado adequado:

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

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

Caracteres curinga

Ao comparar strings para igualdade, a API REST do Ad Manager é compatível com caracteres curinga usando o caractere *.

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

Operador de travessia

A API REST do Ad Manager é compatível com o operador ., que indica a travessia por meio de mensagem, mapa ou struct.

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

A travessia é gravada usando os nomes de campo do recurso. Os serviços individuais podem especificar um subconjunto de campos compatíveis para travessia.

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

Tem operador

A API REST do 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.

Consulte campos de string para ver se a string contém uma substring correspondente:

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

Consulta de campos repetidos para conferir 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 forma que e.foo = 42.

Importante :os filtros não podem consultar um elemento específico em um campo repetido para encontrar 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 tiver a chave "foo".
m.foo:*	Verdadeiro se m tiver a chave "foo".
m.foo:42	Verdadeiro se m.foo for 42.

Ao percorrer mensagens, um campo só é 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 REST do Ad Manager é compatível com a ordenação em métodos List. A sintaxe dos campos orderBy é uma lista de nomes de campo separados por vírgulas. Por exemplo: "foo,bar".

A ordem de classificação padrão é crescente. Para especificar a ordem decrescente em 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.