Funzioni di gestione delle raccolte collection-management-functions
Informazioni sulle funzioni di raccolta query
Il linguaggio delle espressioni introduce anche un set di funzioni per le raccolte di query. Queste funzioni sono descritte di seguito.
Negli esempi seguenti, utilizziamo un evento denominato “LobbyBeacon” contenente una raccolta di token di notifica push. Gli esempi in questa pagina utilizzano la struttura del payload dell’evento mostrata di seguito:
{
"_experience":{
"campaign":{
"message":{
"profile":{
"pushNotificationTokens":[
{
"token":"token_1",
"application":{
"_id":"APP1",
"name":"MarltonMobileApp",
"version":"1.0"
}
},
{
"token":"token_2",
"application":{
"_id":"APP2",
"name":"MarketplaceApp",
"version":"1.0"
}
},
{
"token":"token_3",
"application":{
"_id":"APP3",
"name":"VendorApp",
"version":"2.0"
}
}
]
}
}
}
},
"timestamp":"1536160728"
}
@event{LobbyBeacon._experience.campaign.message.profile.pushNotificationTokens}, dove "LobbyBeacon" è il nome dell'evento e il resto del percorso corrisponde alla struttura mostrata sopra.La funzione all(<condition>)
La funzione all abilita la definizione di un filtro per una determinata raccolta utilizzando un’espressione booleana.
<listExpression>.all(<condition>)
Esempio concettuale: tra tutti gli utenti dell’app, puoi ottenere quelli che usano IOS 13 (espressione booleana “app used == IOS 13”). Il risultato di questa funzione è l’elenco filtrato contenente gli elementi che corrispondono all’espressione booleana (ad esempio: utente app 1, utente app 34, utente app 432).
In un’attività Condizione Data Source è possibile verificare se il risultato della funzione all è nullo o meno. È inoltre possibile combinare questa funzione all con altre funzioni quali count. Per ulteriori informazioni, vedere Attività condizione Data Source.
Esempi di codice con il payload LobbyBeacon:
Gli esempi seguenti utilizzano il payload dell’evento mostrato nella parte superiore di questa pagina.
Esempio 1
Vogliamo verificare se un utente ha installato una versione specifica di un’applicazione. Per questo otteniamo tutti i token di notifica push associati alle applicazioni mobili per le quali la versione è 1.0. Quindi eseguiamo una condizione con la funzione count per verificare che l’elenco di token restituito contenga almeno un elemento.
count(@event{LobbyBeacon._experience.campaign.message.profile.pushNotificationTokens.all(currentEventField.application.version == "1.0").token}) > 0
Il risultato è vero.
Esempio 2
In questo caso, usiamo la funzione count per verificare se la raccolta contiene token di notifica push.
count(@event{LobbyBeacon._experience.campaign.message.profile.pushNotificationTokens.all().token}) > 0
Il risultato è vero.
count(@event{LobbyBeacon._experience.campaign.message.profile.pushNotificationTokens.token})
Il risultato dell’espressione è 3.
-
Quando la condizione di filtro nella funzione all() è vuota, il filtro restituirà tutti gli elementi dell'elenco. Tuttavia, per contare il numero di elementi di una raccolta, la funzione all non è obbligatoria.
-
currentEventFieldè disponibile solo quando si manipolano le raccolte eventi,currentDataPackFieldquando si manipolano le raccolte origini dati ecurrentActionFieldquando si manipolano le raccolte di risposte di azioni personalizzate.
all, first e last, viene eseguito un ciclo su ogni elemento della raccolta uno alla volta. currentEventField, currentDataPackField e currentActionField corrispondono all'elemento di cui viene eseguito il ciclo.La prima(<condition>) e l’ultima(<condition>) funzioni
Le funzioni first e last abilitano inoltre la definizione di un filtro nella raccolta restituendo il primo/ultimo elemento dell’elenco che soddisfa il filtro.
<listExpression>.first(<condition>)
<listExpression>.last(<condition>)
Esempio 1
Questa espressione restituisce il primo token di notifica push associato alle applicazioni mobili la cui versione è 1.0.
@event{LobbyBeacon._experience.campaign.message.profile.pushNotificationTokens.first(currentEventField.application.version == "1.0").token}
Risultato: token_1.
Esempio 2
Questa espressione restituisce l’ultimo token di notifica push associato alle applicazioni mobili la cui versione è 1.0.
@event{LobbyBeacon._experience.campaign.message.profile.pushNotificationTokens.last(currentEventField.application.version == "1.0").token}
Risultato: token_2.
Funzione at(<index>)
La funzione at consente di fare riferimento a un elemento specifico di una raccolta in base a un indice.
L’indice 0 è il primo indice della raccolta.
<listExpression>.at(<index>)
Esempio
Questa espressione restituisce il secondo token di notifica push dell’elenco.
@event{LobbyBeacon._experience.campaign.message.profile.pushNotificationTokens.at(1).token}
Risultato: token_2.
Questa sezione contiene informazioni strutturate che supportano l’interpretazione, il recupero e la risposta alle domande relative a questo argomento.
Per una comprensione completa, queste informazioni devono essere unite alla documentazione su questa pagina. Nessuna delle due origini è progettata per essere indipendente; la pagina descrive la funzione, mentre questa sezione fornisce un contesto aggiuntivo che aiuta a non ambiguare la terminologia, le finalità, l’applicabilità e i vincoli.
- TL;DR: In questa pagina sono documentate le funzioni di gestione della raccolta
all(),first(),last()eat()utilizzate nell’editor di espressioni avanzate di Percorso, illustrate con esempi di payload del token di notifica push.
Intenti:
- Filtrare una raccolta di campi evento o origine dati utilizzando una condizione booleana con
all(<condition>) - Conteggio degli elementi di raccolta filtrati o non filtrati utilizzando
count()in combinazione con le funzioni di raccolta - Recuperare il primo o l’ultimo elemento corrispondente di una raccolta utilizzando
first()olast() - Accedere a un elemento della raccolta in un indice specifico basato su zero utilizzando
at(<index>) - Comprendere quale variabile di loop (
currentEventField,currentDataPackField,currentActionField) si applica a ciascun contesto di raccolta
Glossario:
- all(condition): filtra una raccolta e restituisce tutti gli elementi che corrispondono all’espressione booleana specificata (specifica per prodotto)
- first(condition): restituisce il primo elemento (più recente per eventi esperienza) di una raccolta corrispondente alla condizione (product-specific)
- last(condition): restituisce l’ultimo elemento (meno recente per gli eventi di esperienza) di una raccolta corrispondente alla condizione (specifico per prodotto)
- at(index): Restituisce l’elemento all’indice a base zero specificato di una raccolta (specifico per prodotto)
- currentEventField: variabile di loop disponibile solo quando si esegue l’iterazione sulle raccolte eventi (specifiche del prodotto)
- currentDataPackField: variabile di loop disponibile solo quando si esegue l’iterazione sulle raccolte di origini dati (specifico per prodotto)
- currentActionField: variabile di loop disponibile solo quando si esegue l’iterazione sulle raccolte di risposte di azioni personalizzate (specifico per prodotto)
Guardrail:
- L’utilizzo di eventi di esperienza nelle espressioni/condizioni di percorso non è supportato; considera metodi alternativi, come gli attributi calcolati
currentEventField,currentDataPackFieldecurrentActionFieldsono disponibili solo nei rispettivi contesti di raccolta- La funzione
allnon è necessaria per contare gli elementi della raccolta.count()può essere applicata direttamente al percorso del campo - Quando
all()viene chiamato con una condizione vuota, vengono restituiti tutti gli elementi della raccolta
Terminologia:
- Nome canonico: Funzioni di gestione delle raccolte — Acronimo: none — varianti: funzioni di raccolta, funzioni di raccolta query
- Sinonimi: “all()” = “funzione filtro raccolta”; “at()” = “funzione di accesso indice”
- Non confondere:
first()(evento esperienza più recente) ≠ primo elemento inserito negli elenchi generali
Domande frequenti:
- D: Qual è la differenza tra
all()con una condizione vuota eall()con una condizione? — Un elementoall()vuoto restituisce ogni elemento; un elementoall()basato su condizioni restituisce solo gli elementi che corrispondono all’espressione booleana. - D: come si contano i token di notifica push senza utilizzare
all()? — Chiamarecount()direttamente nel percorso del campo token, ad esempiocount(@event{LobbyBeacon...pushNotificationTokens.token}). - D: quale variabile si utilizza per fare riferimento all’elemento corrente quando si esegue il ciclo su una raccolta di origini dati? — Utilizzare
currentDataPackFieldall’interno diall(),first()olast()nelle raccolte di origini dati. - D: come è possibile ottenere il secondo elemento in una raccolta? — Utilizzare
at(1)perché l’indice 0 è il primo elemento. - Q: perché
last()restituisce l’evento esperienza meno recente? — Gli eventi di esperienza vengono archiviati in ordine cronologico inverso, pertanto l’ultima posizione nell’insieme corrisponde all’evento meno recente.