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 un updateTime dopo il 1° gennaio 2024 nel fuso orario orientale standard degli Stati Uniti
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)

Suggerimento: il filtro deve essere codificato come URL per le richieste GET. Ad esempio: stringa filtro: orders.updateTime > "2024-01-01T00:00:00-5:00" URL codificato: orders.updateTime%20%3E%20%222024-01-01T00:00:00-5:00%22. Questa operazione viene gestita automaticamente dalle librerie client.

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 i campi considerati per la corrispondenza sul 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 inserire spazi tra i valori letterali stringa.

Operatori logici

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

Attenzione: questi operatori sono sensibili alle maiuscole. I valori letterali and e or vengono considerati come valori letterali.

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

Nota: per corrispondere a schemi di discorso comuni, l'operatore OR ha una precedenza superiore a AND, diversamente da quanto avviene nella maggior parte dei linguaggi di programmazione. L'espressione a AND b OR c viene valutata come a AND (b OR c). Se possibile, utilizza parentesi esplicite per evitare confusione.

Operatori di negazione

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

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

Operatori di confronto

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

Operatore	Esempio	Significato
=	a = true	Vero se a è true.
!=	a != 42	True, a meno che a non sia uguale a 42.
<	a < 42	Vero se a è un valore numerico inferiore a 42.
>	a > "foo"	Vero se a è ordinato in modo lessicale dopo "foo".
<=	a <= "foo"	Vero 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.

Nota: a differenza della maggior parte dei linguaggi di programmazione, i nomi dei campi devono apparire sul lato sinistro di un operatore di confronto; il lato destro accetta solo letterali e operatori logici.

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

• Le stringhe richiedono 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 in virgola mobile, 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.

Attenzione: gli identificatori true, false e null hanno un significato intrinseco solo se utilizzati nel contesto di un riferimento a un campo di tipo.

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 l'esplorazione 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	Vero se a ha un campo numerico b 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.

Importante: l'operatore . non può essere utilizzato per esaminare un campo o un elenco ripetuto, tranne per un uso specifico con l'operatore :.

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.

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.

Importante: i filtri non possono eseguire query su un elemento specifico in un campo ripetuto per un valore. Ad esempio, e.0.foo = 42 e e[0].foo = 42 non sono filtri validi.

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

La maggior parte delle risorse supporta l'ordinamento in base ai metodi List. Consulta la documentazione del metodo List per il comportamento preciso della risorsa e i campi supportati per l'ordinamento.

La sintassi per i campi orderBy è 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 di spaziatura ridondanti nella sintassi vengono ignorati. I valori "foo, bar desc", " foo , bar desc " e "foo,bar desc" sono tutti equivalenti.

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