JSONata è un linguaggio di trasformazione e query open source progettato per i dati JSON che useremo per accedere e analizzare i dati da un corpo di risposta JSON restituito dall’API.
Puoi facilmente testare le query usando https://try.jsonata.org/ o, se preferisci un formato Javascript più elaborato, https://www.stedi.com/jsonata/playground . Per questa introduzione, atteniamoci al metodo di allenamento di JSONata.
L’utente lancerà il suo oggetto fittizio Invoice che useremo come punto di riferimento. I dati di input non elaborati si trovano a sinistra, la query dell’espressione JSONata si trova in alto a destra e il risultato trovato da tale espressione verrà visualizzato in basso a destra.
Per riallineare l’oggetto JSON, usa il piccolo strumento di rientro all’estrema destra dell’oggetto fittizio e salva qualsiasi espressione corrente usando la funzionalità di condivisione in alto a destra.
Per ora, questo è tutto ciò che devi sapere sull’attrezzo ginnico. Successivamente, usa una query all’interno del modello di fattura predefinito.
Se stai solo cercando informazioni chiave o un punto di riferimento dopo l’abilitazione, dai un’occhiata al nostro cheatsheet.
Mappatura dei dati
Campo a livello di radice: Account
Campo nidificato nell’oggetto radice: Account . "Nome account"
Se trova un'altra struttura JSON, puoi usare la notazione con punti per inserire i campi seguenti.
Campo nidificato in un array a livello radice:
Primo ordine in questo account:
Account.Order[0]Promemoria: L’indicizzazione dell’array inizia da [0] per il primo elemento. Il collegamento all’ultimo elemento in un array è [-1].
Il primo colore del prodotto in questo stesso oggetto:
Account.Order[0].Product[0].Description.ColourRecupera un array di elementi da un array di livello radice:
Se più valori corrispondono a una query, JSONata li aggregherà automaticamente.
Controlla l’intero oggetto Account.Order e recupera tutti gli OrderID in esso contenuti:
Account.Order.OrderIDFiltraggio dei dati
Definisci la destinazione a cui si accede, ad es
Account.Order.OrderIDOra aggiungi la condizione nel punto corrispondente: per ogni esecuzione di un array, aggiungi una coppia di [] parentesi:
ad esempio, includi solo gli ordini con prodotti con un prezzo superiore a 30 che sono stati ordinati una sola volta e mostrano il rispettivo nome del prodotto:
Account.Order.Product[Price > 30 and Quantity = 1].'Product Name'ad es., includi solo gli ordini con prodotti con una descrizione.Peso superiore a 1 e mostra il rispettivo OrderID:
Account.Order[Product[Description.Weight > 1]].OrderIDIn alternativa, puoi anche verificare la presenza di un’affermazione veritiera, ad es
Account.Order[Product["Purple" in Description.Colour]].OrderIDInoltre, può essere combinato con le ricerche con caratteri jolly se vuoi controllare più chiavi, ad es
Account.Order[Product["Purple" in Description.*]].OrderIDAltri operatori di percorso
( https://docs.jsonata.org/path-operators )
^( ... ) (Ordine per)
Ordina per ordine decrescente:
Account.Order^(>OrderID)Ordina per prodotto dal più economico al più costoso:
Account.Order.Product^(Price)* (carattere jolly)
Accedi a qualsiasi SKU indipendentemente dalla denominazione principale diretta:
Account.Order.*.SKUAccedi a qualsiasi nome prodotto , indipendentemente dalla denominazione principale:
**.'Product Name'% (principale)
Cerca a ritroso nella struttura dati corrente:
Account.Order.Product.{
'Account': %.%.`Account Name`,
'Order': %.OrderID,
'Product': `Product Name`
}# (Associazione di variabili di posizione)
Crea un indice, a partire da 0:
Account.Order#$i[Product.[Quantity > 0]].{
'Order ID': OrderID,
'Order Number': $i + 1
}@ (Associazione di variabili di contesto)
Assegna temporaneamente una nuova struttura dati, consentendo la mappatura tra oggetti:
Account@$A.Account.Order@$O.{
"Account Name": $A.'Account Name',
"OrderID": $O.OrderID
}Condizionali
Simile all’operatore ternario in JS, puoi usare ? istruzioni for if e : for else. Gli operatori booleani e/o possono essere usati per creare condizioni di catena.
SE LA CONDIZIONE È VERA? FARE QUESTO (ALTRO FARE NIENTE)
SE LA CONDIZIONE È VERA? FARE QUESTO: ALTRIMENTI FARE QUESTO
$count(Account.Order) > 1 ? "REPEAT CUSTOMER"Account.Order[0].Product[0].Price <= 100 or Account.Order[0].Product[1].Price <= 100 ? "Bargain" : "VIP" = "Bargain"Manipolazione dei dati
Operatori supportati
| Operatore | Priorità | Descrizione |
| Moltiplica (*) | 5 | Moltiplica due numeri |
| Dividi (/) | 5 | Divide due numeri |
| Modulo (%) | 5 | Restituisce il resto quando si dividono due numeri |
| Concatena (&) | 4 | Concatena due stringhe |
| Aggiungi (+) | 4 | Aggiunge due numeri |
| Sottrai (-) | 4 | Sottrae due numeri |
| Uguale (=) | 3 | Verifica se due valori sono uguali |
| Diverso (!=) | 3 | Verifica se due valori non sono uguali |
| Maggiore di (> ) | 3 | Restituisce true se il valore di sinistra è maggiore del valore di destra |
| Maggiore o uguale a (> =) | 3 | Restituisce true se il valore a sinistra è maggiore o uguale al valore a destra |
| Meno di (< ) | 3 | Restituisce true se il valore di sinistra è inferiore al valore di destra |
| Minore o uguale a (< =) | 3 | Restituisce true se il valore a sinistra è minore o uguale al valore a destra |
| AND logico (e) | 2 | Restituisce true se entrambi i valori sinistro e destro sono veri |
| OR logico (o) | 1 | Restituisce true se il valore a sinistra è vero o il valore a destra è vero |
es. stringhe concatenate:
Account.Order[0].Product[0].Description.Colour & " " & Account.Order[0].Product[0].'Product Name'Funzioni integrate
Tieni presente che questi sono stati notevolmente ridotti per motivi di leggibilità. La documentazione completa è disponibile qui: https://docs.jsonata.org/overview.html
Nota: un’espressione multilinea deve essere racchiusa tra ()
Forza tipo stringa: $string ( Account.Order[0].Product[0].ProductID ): "858383"
Tipo di numero forzato: $number ( Account.Order[0].Product[0].SKU ): 406654608
Stringa maiuscola: $maiuscolo ( Account . Order [ 0 ]. OrderID ): "ORDINE103"
Stringa minuscola: $minuscolo ( Account . Ordine [ 0 ]. Prodotto [ 0 ]. Descrizione . Colore ): "viola"
Genera un numero casuale compreso tra 0 e 1: $random ()
Conteggio oggetti in un array: $count ( Account . Order )
Conta gli oggetti in un array che soddisfano una condizione: $count ( Account . Order . Product [ Price> 30 ])
Numero di caratteri in una stringa: $length ( Account . 'Account Name' )
Sostituisci/rimuovi determinati caratteri in una stringa: $replace ( Account . Order [ 0 ]. Product [ 0 ]. 'Product Name' , "Bowler ", "" ): "Cappello"
Taglio di una stringa su un numero di caratteri specifico: $substring ( $string ( Account . Order [ 0 ]. Product [ 0 ]. ProductID ), 1 , 2 )
Taglia una stringa in base a uno schema specifico: $substringAfter ( Account . Order [ 0 ]. OrderID , "order" )
Risultato simile usando split + join:
$join ( $split ( Account . Order [ 0 ]. Product [ 0 ]. 'Product Name', " "), '_' )
Può anche essere scritto come ~> funzione:
$split ( Account . Ordine [ 0 ]. Prodotto [ 0 ]. 'Nome prodotto', " ") ~> $join('_' )
Controlla se una stringa contiene un modello specifico: il modello può essere una stringa esatta o un’espressione regolare:
$contains ( Account . Order [ 0 ]. Product [ 0 ]. 'Product Name' , "Hat" )
Date e orari
La maggior parte delle date verrà superata secondo lo standard internazionale ISO 8601 e avrà il seguente aspetto 2023-04-20T13:09:39+00:00 (informazioni sul fuso orario di trasporto) o 2023-04-20T13:09:39Z (con chiave in millisecondi offset da UTC). Sono ben leggibili, ma non possono essere manipolati in modo nativo da JSONata.
Spesso, dovrai quindi trasformarli in tempo UNIX, che è il numero letterale di secondi trascorsi dalle 00:00:00 UTC del 1 gennaio 1970 (Epoca Unix), che non è più leggibile dal punto di vista umano, ma come numero intero può essere aggiunto/sottratto/confrontato con altre date UNIX. JSONata funziona in modo nativo con Millis, che sono i MILLISECONDS dall’epoca Unix (quindi UNIX * 1000).
$ora (): "2023-04-20T13:39:58.216Z"
$milli (): 1681998518175
Ora questi millis possono essere ritrasformati in un formato data a tua scelta definendo un’immagine (il tuo modello di destinazione) in una stringa: https://www.w3.org/TR/xpath-functions-31/#date-picture -string
Esempi di pattern: https://www.w3.org/TR/xpath-functions-31/#date-time-examples
| Identificatore | Significato |
| Y | Anno (valore assoluto) |
| M | Mese nell’anno |
| D | Giorno nel mese |
| F | Giorno in settimana |
| H | Ora nel giorno (24 ore) |
| h | Ora in mezza giornata (12 ore) |
| P | Indicatore AM/PM |
| m | Minuto in ora |
| s | Secondo in minuto |
| Z | Fuso orario |
ad es. $fromMillis ( $millis (), '[M]/[G]/[Y01]' ) restituisce "4/20/23" ,
$fromMillis ( $millis (), '[D01].[M01].[Y0001] [H#1]:[m01]' ) restituisce "20.04.2023 13:51" .
Mettiamolo in pratica: supponiamo che tu abbia due date nei dati delle risposte e che tu voglia controllare quanti giorni sono trascorsi da OGGI.
"2023-04-20T00:00:00.000Z"
"20.04.2023"
Trasformali entrambi in Milis: la seconda data non è nel modello ISO 8601 standard, quindi dovrai fornire l’immagine affinché JSONata possa sapere quale valore è il tuo giorno, mese, anno e qualsiasi informazione temporale potresti avere a disposizione.
$toMillis ( '2023-04-20T00:00:00.000Z' ) : 1681948800000
$toMillis ( '20.04.2023' , '[D01].[M01].[Y0001]' ): 1681948800000
Puoi anche visualizzare l’ora corrente in Milis tramite la funzione standard $millis(): 1681999968402
Ora puoi semplicemente sottrarre l’una dall’altra e ricevere la differenza tra le due date in millisecondi: 1681999968402 - 1681948800000 = 51296367
Usando la conversione temporale comune:
1000 millisecondi = 1 secondo
60 sec = 1 minuto
60 min = 1 ora
E arrotondando per difetto il risultato, ricevi un totale di 14 ore trascorse da adesso al timestamp fornito:
$round (51296367 / 1000 / 60 / 60 ) = 14
Combinata in una riga, stai esaminando un’operazione di:
$round(($millis() - $toMillis('20.04.2023', '[D01].[M01].[Y0001]')) / 1000 / 60 / 60)Output speciali
Ticket “Oneliner”
Poiché potresti avere una sola possibilità di risposta, ti consigliamo di trasmettere quante più informazioni possibili in un singolo parametro. JSONata gestisce l’aggregazione per te in modo che tu possa giocare liberamente con la copia di testo.
Supponiamo che tu voglia visualizzare gli SKU e i prezzi di tutti i prodotti nel tuo ordine:
Account.Order.ProductPoiché alla fine vuoi solo avere una grande riga di testo con tutti i prodotti considerati, puoi semplicemente creare un array condiviso con tutte le informazioni richieste:
Account.Order.Product.(SKU & Price)Ora devi solo combinarli in un’unica grande stringa con un carattere di interruzione di riga come separatore:
$join(Account.Order.Product.("SKUs: " & SKU & ", " & "Price: " & Price), "\n")Nota: Considera i limiti del CRM: Zendesk Support offre una formattazione di base, quindi a \n si tradurrà correttamente in un’interruzione di riga durante il rendering di un’email di risposta, ma ciò potrebbe non essere il caso per tutti i sistemi.
Schede e sequenze
Le schede e le sequenze sono il vero punto di forza di JSONata poiché gestisce la query e l'aggregazione dei dati in modo nativo, a condizione che la risposta segua lo stesso schema. Un C&C è costituito da una serie di oggetti in cui ogni oggetto rappresenta una delle tue schede. Un esempio molto semplice di struttura C&C con 2 schede potrebbe essere simile al seguente:
[
{
"imageURL": data.url1,
"title": data.title1,
"description": data.description1
},
{
"imageURL": data.url2,
"title": data.title2,
"description": data.description2
}
]È importante che tutti gli oggetti nell’array seguano la stessa struttura in modo che sia possibile accedervi tramite la stessa chiave condivisa. Assicurati anche di tenere a mente i limiti del tuo CRM .
Per un esempio semplice, costruiamo di nuovo un C&C sui dati di esempio della fattura. Iniziamo con un array sin dall’inizio: qualsiasi risultato di query con più di un oggetto risposta verrà convertito automaticamente in un array, ma è consigliabile disporre di questa opzione di sicurezza nel caso in cui il risultato contenga un solo oggetto.
[Account.Order.Product.'Product Name'][Account.Order.Product.SKU][Account.Order.Product.Description.Colour]Questi sono alcuni dei campi che ci interessano. Uniamoli in un unico oggetto: assicurati di assegnare un nome a ciascuna chiave nell’oggetto di destinazione:
[
Account.Order.Product.
{
"name": 'Product Name',
"sku": SKU,
"colour": Description.Colour
}
]Se hai bisogno di un valore di un livello superiore, puoi semplicemente iniziare la query a un livello superiore. Se vuoi includere anche [ Account . Ordina . OrderID ] nell’array:
[
Account.Order.
{
"orderId": OrderID,
"name": Product.'Product Name',
"sku": Product.SKU,
"Colour": Product.Description.Colour
}
]Noterai che non esiste più una corrispondenza diretta 1:1 poiché ogni ordine può contenere più elementi, motivo per cui questa risposta crea array di stringhe apparentemente casuali. Puoi risolvere il problema accedendo indirettamente all’oggetto principale (consulta Associazione principale), assegnando temporaneamente una struttura di oggetti diversa in JSONata (consulta Associazione di variabili di contesto), aggiungendo un C&C secondario che scorre gli elementi nell’ordine scelto o trasformando ulteriormente i dati. a seconda della tua UX ideale. Ecco un esempio trasformato:
[
Account.Order.
{
"orderId": OrderID,
"name": $join(Product.'Product Name', ", "),
"totalPrice": $sum(Product.Price)
}
]Se vuoi rendere più sicura la query, aggiungiamo alcuni fail safe nel caso in cui non disponi dei dati di risposta previsti (per coprire, ad esempio, un 404) e un limite nel caso in cui la risposta restituisca più risultati di quelli che il tuo CRM può assistenza (ad esempio 10 per i widget SunCo):
Account.Order ?
[Account.Order[[0..9]].
{
"orderId": OrderID,
"name": $join(Product.'Product Name', ", "),
"totalPrice": $sum(Product.Price)}]
: [{"orderId": "???", "name": "Cannot find your item?"}]IMPORTANTE: Assicurati che tutte le chiavi C&C seguano la convenzione camelCase , _ i nomi dei parametri non sono supportati.
Ora tutte queste chiavi, ad esempio orderId, name, totalPrice, saranno disponibili per il tuo Carousel. Imposta il tipo di sequenza su dinamico nell’interfaccia utente e aggiungi il nome del parametro che ospita la query qui sopra, ad esempio orderList .
Ora puoi accedere a qualsiasi chiave negli oggetti dell’array aggiungendo una scorciatoia %, o generandole direttamente nella chat sulle schede:
Oppure memorizzandoli nella sessione inserendo nella scheda scelta un’azione che fa riferimento alla chiave dell’oggetto scelto in un nome di parametro a tua scelta, ad esempio:
Avvertenza sulla traduzione: questo articolo è stato tradotto usando un software di traduzione automatizzata per fornire una comprensione di base del contenuto. È stato fatto tutto il possibile per fornire una traduzione accurata, tuttavia Zendesk non garantisce l'accuratezza della traduzione.
Per qualsiasi dubbio sull'accuratezza delle informazioni contenute nell'articolo tradotto, fai riferimento alla versione inglese dell'articolo come versione ufficiale.