Filtri

L'API REST di Ad Manager supporta l'applicazione di filtri sui metodi List. La sintassi della stringa di filtro è formalmente definita nella grammatica dell'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
lineItems.targeting.geoTargeting.targetedGeoIds:2840	Elenca gli elementi pubblicitari con un targeting geografico che contiene gli Stati Uniti (ID targeting 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 che hanno un nome visualizzato contenente la stringa video (sintassi alternativa)

Suggerimento: il filtro deve avere codifica URL per le richieste GET. Ad esempio:
Stringa filtro: orders.updateTime > "2024-01-01T00:00:00-5:00"
Codifica URL: orders.updateTime%20%3E%20%222024-01-01T00:00:00-5:00%22.
Questo viene gestito automaticamente dalle librerie client.

Valori letterali

Un valore letterale essenziale (esempi: 42, Hugo) è un valore di cui trovare una corrispondenza. I valori letterali che appaiono da soli vengono confrontati con tutti i campi supportati su una risorsa. Le risorse documentano i campi considerati per la corrispondenza nel metodo list. Questa funzionalità è paragonabile alla ricerca universale nell'interfaccia utente di Ad Manager, ma ha come ambito un singolo tipo di risorsa.

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

Operatori logici

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

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

Operatore	Esempio	Significato
AND	a AND b	True se a e b sono veri.
OR	a OR b OR c	True se uno qualsiasi tra a, b e c è vero.

Nota: per trovare corrispondenze con pattern di parlato comuni, l'operatore OR ha una precedenza maggiore rispetto a AND, a differenza di quanto si trova nella maggior parte dei linguaggi di programmazione. L'espressione a AND b OR c restituisce a AND (b OR c). Se possibile, utilizza le parentesi esplicite per evitare confusione.

Operatori di negazione

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

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

Operatori di confronto

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

Operatore	Esempio	Significato
=	a = true	True se a è vero.
!=	a != 42	Vero 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 è in ordine lessico dopo "foo".
<=	a <= "foo"	True se a è "foo" o lessicalmente prima di questo.
>=	a >= 42	True 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; sul lato destro accetta solo operatori letterali e logici.

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

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

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

Caratteri jolly

Quando confronti le stringhe per determinare l'uguaglianza, l'API REST di Ad Manager supporta i caratteri jolly che usano il carattere *.

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

Operatore di trasferimento

L'API REST di Ad Manager supporta l'operatore ., che indica il attraversamento attraverso un messaggio, una mappa o uno struct.

Esempio	Significato
a.b = true	True se a ha un campo booleano b vero.
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 contenente "foo".

Il trasferimento viene scritto utilizzando i nomi dei campi della risorsa. I singoli servizi possono specificare un sottoinsieme di campi supportati per l'attraversamento.

Importante: l'operatore . non può essere utilizzato per attraversare un campo o un elenco ripetuto, tranne in caso di utilizzo specifico con l'operatore :.

Con operatore

L'API REST di 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 ciascun caso.

Query sui campi 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.

Mappe, struct e messaggi possono eseguire query per verificare la presenza di un campo nella mappa o di 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	True se m.foo è 42.

Quando si attraversano messaggi, un campo viene considerato presente solo se ha un valore non predefinito.

Limitazioni

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

Ordine

L'API REST di Ad Manager supporta l'ordinamento in base ai metodi List. 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'ordine decrescente di un campo, aggiungi un suffisso " desc". Ad esempio: "foo desc, bar".

Gli 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.