Filtri

L'API Ad Manager supporta i filtri in base ai metodi List. La sintassi della stringa di filtro è definita formalmente nella grammatica EBNF.

Per iniziare, ecco alcuni esempi di casi d'uso comuni.

Esempio Significato
orders.updateTime > "2024-01-01T00:00:00-5:00" Elenca gli ordini con updateTime dopo il 1° gennaio 2024 nel fuso orario standard orientale.
lineItems.targeting.geoTargeting.targetedGeoIds:2840 Elenca gli elementi pubblicitari con un targeting geografico che include gli Stati Uniti (ID target geografico 2480)
lineItems.displayName = "*_interstitial" Elenca gli elementi pubblicitari il cui nome visualizzato termina con la stringa _interstitial
orders.displayName = "*video*" Elenca gli ordini il cui nome visualizzato contiene la stringa video
displayName:"video" Elenca gli ordini il cui nome visualizzato contiene la stringa video (sintassi alternativa)

Valori letterali

Un valore letterale semplice (ad es. 42, Hugo) è un valore con cui eseguire la corrispondenza. I valori letterali visualizzati da soli vengono sottoposti a una ricerca approssimativa in tutti i campi supportati di una risorsa. Le risorse documentano quali campi sono considerati per la corrispondenza nel metodo list. Questa funzionalità è paragonabile alla ricerca universale nell'interfaccia utente di Ad Manager, ma limitata a un singolo tipo di risorsa.

I valori letterali stringa contenenti spazi devono essere racchiusi tra virgolette doppie (esempio: "Foo bar"). Non è possibile utilizzare virgolette singole per racchiudere i valori letterali stringa.

Operatori logici

L'API Ad Manager supporta gli operatori binari AND e OR.

Operatore Esempio Significato
AND a AND b True se a e b sono true.
OR a OR b OR c Vero se uno dei valori a, b, c è vero.

Operatori di negazione

L'API Ad Manager fornisce gli operatori unari NOT e -. Questi termini possono essere utilizzati in modo intercambiabile.

Operatore Esempio Significato
NOT NOT a Vero se a non è true.
- -a True se a non è vero.

Operatori di confronto

L'API Ad Manager supporta gli operatori di confronto binario =, !=, <, >, <= e >= per i campi di stringa, numerico, timestamp e durata.

Operatore Esempio Significato
= a = true True se a è vero.
!= a != 42 True, a meno che a non sia uguale a 42.
< a < 42 True se a è un valore numerico inferiore a 42.
> a > "foo" True se a è ordinato in modo lessicale dopo "foo".
<= a <= "foo" True se a è "foo" o precede questo termine dal punto di vista lessicale.
>= a >= 42 Vero se a è un valore numerico pari o superiore a 42.

Poiché i filtri sono accettati come stringhe di query, viene eseguita la conversione di tipo per tradurre la stringa nel valore fortemente tipizzato appropriato:

  • Per le stringhe sono previste virgolette doppie. Esempio: "Foo bar".
  • Gli enum richiedono la rappresentazione stringa dell'enum (sensibile alle maiuscole).
  • I valori booleani richiedono valori letterali true e false.
  • I numeri richiedono le rappresentazioni standard di numeri interi o in virgola mobile. Per i valori float, sono supportati gli esponenti. Esempio: 2.997e9.
  • Le durate richiedono una rappresentazione numerica seguita da un suffisso s (per secondi). Esempi: "20s", "1.2s".
  • I timestamp richiedono una stringa formattata in RFC-3339. Esempio: "2012-04-21T11:30:00-04:00". Gli offset UTC sono supportati.

Caratteri jolly

Quando confronti le stringhe per verificare se sono uguali, l'API Ad Manager supporta i caratteri jolly utilizzando il carattere *.

Esempio Significato
a = "*.foo" True se a termina con ".foo".

Operatore di attraversamento

L'API Ad Manager supporta l'operatore ., che indica il traversale di un messaggio, una mappa o una struttura.

Esempio Significato
a.b = true True se a ha un campo b booleano che è true.
a.b > 42 True se a ha un campo b numerico maggiore di 42.
a.b.c = "foo" True se a.b ha un campo stringa c che è "foo".

Il traversal viene scritto utilizzando i nomi dei campi della risorsa. I singoli servizi potrebbero specificare un sottoinsieme di campi supportati per la traversata.

Con operatore

L'API Ad Manager supporta l'operatore :, che significa "ha". È utilizzabile con raccolte (campi o mappe ripetuti), messaggi e stringhe e si comporta in modo leggermente diverso in ogni caso.

Query sui campi di stringa per verificare se la stringa contiene una sottostringa corrispondente:

Esempio Significato
r.displayName:"_250x250" True se il campo Stringa r.displayName contiene la sottostringa _250x250.

Esegui una query sui campi ripetuti per verificare se la struttura ripetuta contiene un elemento corrispondente:

Esempio Significato
r:42 True se r contiene 42.
r.foo:42 True se r contiene un elemento e tale che e.foo = 42.

Le mappe, le strutture e i messaggi possono eseguire query sulla presenza di un campo nella mappa o su un valore specifico:

Esempio Significato
m:foo True se m contiene la chiave "foo".
m.foo:* True se m contiene la chiave "foo".
m.foo:42 Vero se m.foo è 42.

Durante l'esplorazione dei messaggi, un campo è considerato presente solo se ha un valore diverso da quello predefinito.

Limitazioni

I singoli servizi possono specificare ulteriori strutture o limitazioni per le query di filtro oltre a quanto definito qui.

Ordine

L'API Ad Manager supporta l'ordinamento sui metodi List. La sintassi dei campi orderBy è costituita da un elenco di nomi di campi separati da virgole. Ad esempio: "foo,bar".

L'ordinamento predefinito è crescente. Per specificare l'ordinamento decrescente per un campo, aggiungere un suffisso " desc". Ad esempio: "foo desc, bar".

I caratteri degli spazi ridondanti nella sintassi vengono ignorati. I valori "foo, bar desc", " foo , bar desc " e "foo,bar desc" sono tutti equivalenti.

I campi secondari vengono specificati con l'operatore di attraversamento. Ad esempio: foo.bar o address.street.