Utilizzo di JSON in Power Fx
Power Fx permette ai creatori di leggere JSON in un Oggetto non tipizzato usando la funzione ParseJSON.
Lettura e conversione di valori
ParseJSON convertirà la seguente stringa di record JSON in un oggetto non tipizzato con campi ItemName, Quantity, ReleaseDate e AvailableForPreOrder.
{
"ItemName" : "Widget 1",
"Quantity" : 46,
"ReleaseDate" : "2022-09-01",
"AvailableForPreOrder" : true
}
È possibile accedere a ciascuno dei campi utilizzando la notazione punto sul valore Oggetto non tipizzato restituito da ParseJSON.
Set( untyped, ParseJSON( jsonStringVariable ) );
Set( item, Text ( untyped.ItemName ) );
Set( quantity, Value ( untyped.Quantity ) );
Set( release, DateValue ( untyped.ReleaseDate ) );
Set( preorder, Boolean ( untyped.AvailableForPreOrder ) );
In genere è una buona idea convertire in modo esplicito il valore di un oggetto non tipizzato in un tipo specifico. L'impostazione di un oggetto non tipizzato come valore di una variabile rende la variabile anche oggetto non tipizzato. Pertanto, è probabile che sia necessario convertire tale valore in modo esplicito quando si imposta su una variabile. Ma nella maggior parte dei casi i valori oggetto non tipizzati verranno convertiti automaticamente in un tipo specifico ("coercizione") se utilizzati come parametri di funzione in cui il tipo è un tipo semplice come booleano, numero o testo e il profilo del parametro della funzione non ha potenziali sovraccarichi in conflitto.
Left( untyped.ItemName, 1 ); // "W"
Radians( untyped.Quantity ); // 0.80285146
If (untyped.AvailableForPreOrder, "Available", "Not Available" ); // "Available"
Oltre a convertire automaticamente il tipo nelle chiamate di funzione, gli oggetti non tipizzati verranno convertiti anche quando assegnati alle proprietà del controllo, ove possibile.
Label1.Text: untyped.Quantity
InputText1.Default: untyped.ItemName
E infine, quando si utilizzano operatori come & o +, un oggetto non tipizzato verrà forzato se non c'è ambiguità sul tipo previsto.
untyped.Quantity + 1 // result is a number
untyped.ItemName & " (preorder)" // result is text
untyped.Quantity + untyped.Quantity // result is a number
untyped.Quantity & untyped.ItemName // result is text
Nota
JSON non ha un tipo GUID, Colore, Ora o DateTime . Questi valori sono rappresentati come una stringa. Se assegni un valore dell'oggetto non tipizzato a JSON contenente una data direttamente a una proprietà di testo, verrà usato il testo originale del JSON. Questo può essere importante quando si ha a che fare con fusi orari, formati di data, ecc. In questi casi è necessario convertire esplicitamente i valori utilizzando GUID(), ColorValue(), DateValue(), DateTimeValue() e così via.
Nel caso in cui il nome di un campo sia costituito da un nome identificativo non valido, ad esempio quando i nomi dei campi iniziano con un numero o contengono caratteri non validi come un trattino, puoi inserire i nomi dei campi tra virgolette singole:
untyped.'01'
untyped.'my-field'
Power Fx non valuterà l'esistenza del campo fino all'esecuzione della formula. Ciò consente flessibilità nel JSON in entrata. Ad esempio, il precedente JSON a volte può contenere un campo aggiuntivo chiamato Discount. Ma nel nostro esempio precedente, questo campo non è presente. Scrivere una formula che utilizza il campo Discount non comporterà alcun errore, durante il processo di creazione dell'app o quando gli utenti utilizzano l'app. Se il campo è mancante durante l'esecuzione della formula, il valore risulterà semplicemente in un valore Blank().
Nota
JSON supporta null valori per i campi. Anche questi risulteranno in valori Blank(). Attualmente non vi è alcuna distinzione in Power Fx tra un campo mancante o un campo che ha il valore null.
Poiché l'accesso ai campi in Oggetti non tipizzati non viene valutato quando si scrive la formula, non c'è Intellisense disponibile. Tutti e due JSON e Power Fx fanno distinzione tra maiuscole e minuscole, quindi presta particolare attenzione nello scrivere i nomi dei campi.
I valori JSON non devono essere in una notazione di tipo record. Un JSON valido può essere un valore, come "text value", true o 123.456. In tal caso, l'Oggetto non tipizzato restituito da ParseJSON è il valore stesso e la notazione punto non viene utilizzata.
Set( myText, Boolean( ParseJSON( "true" ) ) );
Set( myNumber, Value( ParseJSON( "123.456" ) ) );
Infine, JSON supporta i record nidificati. La conversione di JSON in Oggetto non tipizzato risulta in oggetti nidificati e la notazione punto può essere utilizzata per attraversare la gerarchia.
{
"Version" : 1,
"RootElement" : {
"Parent" : {
"Name" : "This is the parent",
"Child" : {
"Name" : "This is the child"
}
}
}
}
Quando si converte questa stringa JSON in una variabile di Oggetto non tipizzato denominata jsonObject, è possibile accedere ai campi utilizzando la notazione punto.
Set( jsonObject, ParseJSON( jsonStringVariable ) );
Set( parentName, Text( jsonObject.RootElement.Parent.Name ) ); // "This is the parent"
Set( childName, Text( jsonObject.RootElement.Parent.Child.Name ) ); // "This is the child"
Se uno qualsiasi dei campi nell'espressione della notazione punto non esiste, Blank() sarà restituito.
Matrici e tabelle
JSON può contenere array di valori o record. È possibile accedere direttamente a queste matrici o convertirle in tabelle Power Fx.
{
"OrderNumber" : "SO000010",
"CustomerID" : "CUST0126",
"OrderLines" : [
{
"Item" : "Widget 1",
"Quantity" : 3
},
{
"Item" : "Widget 2",
"Quantity" : 5
}
]
}
Questo JSON contiene un record con un campo denominato OrderLines che contiene una matrice di record. Ogni record ha due campi: Item e Quantity. Se il JSON viene convertito in un Oggetto non tipizzato usando la funzione ParseJSON e impostato su una variabile denominata jsonOrder, possiamo accedere alle singole righe ordine in diversi modi.
Set( jsonOrder, ParseJSON( jsonStringVariable ) );
È possibile recuperare singoli record e valori utilizzando la funzione Index(). Ad esempio, per ottenere il secondo record nel campo OrderLines, quindi accedere al campo Quantity e convertirlo in un valore.
Set( line2Quantity, Value( Index( jsonOrder.OrderLines, 2 ).Quantity ); // 5
È possibile convertire la matrice di righe ordine direttamente in una tabella. Questo creerà una tabella a colonna singola con un Oggetto non tipizzato che rappresenta il record.
Set( orderLines, Table( jsonOrder.OrderLines ) );
La tabella a colonna singola "orderLines" ora ha una colonna "Value" che rappresenta l'Oggetto non tipizzato. Per utilizzare uno qualsiasi dei campi di un record in questa tabella, utilizza la notazione punto per accedere al campo specifico JSON dell'Oggetto non tipizzato nella colonna Value.
Set( jsonRecord, Index( orderLines, 2 ) ); // Get the second record in the table
Set( line2Item, Text( jsonRecord.Value.Item ) ); // "Widget 2"
Per rendere l'uso dei record della riga ordine più semplice e diretto in altre parti dell'app, puoi convertire l'intero Oggetto non tipizzato in un record interamente tipizzato utilizzando la funzione ForAll(). Se fornisci l'oggetto non tipizzato direttamente a ForAll() significa che puoi accedere direttamente ai campi dell'oggetto invece di utilizzare il campo a colonna singola Value.
Set( typedOrderLines, ForAll( jsonOrder.OrderLines, { Item : Text( ThisRecord.Item ), Quantity : Value( ThisRecord.Quantity ) } ) );
La nuova variabile typedOrderLines è ora una tabella completamente tipizzata Power Fx con le seguenti colonne e valori:
| Item | Quantità |
|---|---|
| "Widget 1" | 3 |
| "Widget 2" | 5 |
Gli esempi precedenti utilizzano matrici di record, ma JSON può anche contenere matrici di soli valori. Considera il seguente esempio che è una stringa valida JSON contenente una matrice di tre stringhe.
[ "First Item", "Second Item", "Third Item"]
Possiamo recuperare uno degli elementi dalla matrice usando la funzione Index() e convertirlo in testo.
Text( Index( ParseJSON( jsonStringVariable ), 2 ) ) // "Second Item"