Arbeta med JSON i Power Fx

Power Fx gör det möjligt för tillverkare att läsa JSON i Objekt utan typ med funktionen ParseJSON.

Läsa och konvertera värden

ParseJSON konverterar följande JSON-poststräng till ett typlöst objekt med fields ItemName, Quantity, ReleaseDate and AvailableForPreOrder.

{
  "ItemName" : "Widget 1",
  "Quantity" : 46,
  "ReleaseDate" : "2022-09-01",
  "AvailableForPreOrder" : true
}

Var och en av fälten kan nås med hjälp av punktmarkering för det Objekt utan typ som returneras från 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 ) );

Det är vanligtvis en bra idé att uttryckligen konvertera ett typlöst objekts värde till en viss typ. Om du anger ett typlöst objekt som ett variabelvärde blir variabeln även ett typlöst objekt. Därför är det troligen nödvändigt att konvertera ett sådant värde explicit när du ställer in till en variabel. Men i de flesta fall konverteras typlösa objektvärden till en viss typ automatiskt ("tvingas") när de används som funktionsparametrar där typen är en enkel typ som boolesk, siffra eller text och funktionens parameterprofil inte har några potentiella överlagringar i konflikt.

Left( untyped.ItemName, 1 ); // "W"
Radians( untyped.Quantity ); // 0.80285146
If (untyped.AvailableForPreOrder, "Available", "Not Available" ); // "Available"

Förutom att automatiskt konvertera typen i funktionsanrop, konverteras även typlösa objekt när de tilldelas för att kontrollera egenskaper när det är möjligt.

Label1.Text: untyped.Quantity
InputText1.Default: untyped.ItemName

Och slutligen när använder operatorer, t.ex. & eller +, kommer en Typlösa objekt kommer att tvingas om det inte finns någon oklarhet om den förväntade typen.

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

Kommentar

JSON har ingen GUID, Color, Time eller DateTime typ. Dessa värden representeras som en sträng. Om du tilldelar ett typlöst objektvärde för JSON som innehåller ett datum till en textegenskap direkt används kommer den ursprungliga texten för JSON att användas. Detta kan vara viktigt när det gäller tidszoner, datumformat osv. I sådana fall bör du uttryckligen konvertera värden med GUID(), ColorValue(), DateValue(), DateTimeValue(), etc.

Om ett fältnamn består av ett ogiltigt ID-namn, till exempel när fältnamnen börjar med ett tal eller innehåller ogiltiga tecken, t.ex. ett bindestreck, kan du placera fältnamnen i enskilda citattecken:

untyped.'01'
untyped.'my-field'

Power Fx kommer inte att utvärdera förekomsten av fältet förrän formeln körs. Detta ger flexibilitet för inkommande JSON. Det kan till exempel hända att det föregående JSON-fältet ibland innehåller ett extra fält som kallas för Discount. Men i vårt tidigare exempel är det här fältet inte med. Om du skriver en formel som fältet Discount kommer inte att resultera i några fel under programtillverkningsprocessen eller när användare använder programmet. Om fältet saknas när formeln körs resulterar värdet bara i ett Blank() värde.

Kommentar

JSON stöder null värden för fält. Dessa resulterar också i Blank() värden. För närvarande finns det ingen skillnad i Power Fx mellan ett saknat fält eller ett fält som har värdet null.

När du öppnar fält för objekt utan typ utvärderas inte när formeln skrivs, finns det inte heller några Intellisense tillgängliga. Både JSON och Power Fx är skiftlägeskänsliga. Var därför extra försiktig när du skriver ut fältnamn.

JSON-värden behöver inte vara i en notation i postformat. Ett giltigt JSON-värde kan endast vara ett värde, till exempel "text value", true eller 123.456. I ett sådant fall är Objekt utan typ som ParseJSON returnerar själva värdet och punktmarkering används inte.

Set( myText, Boolean( ParseJSON( "true" ) ) );

Set( myNumber, Value( ParseJSON( "123.456" ) ) );

Slutligen stöder JSON kapslade poster. Om du konverterar en sådan JSON till Objekt utan typ resulterar detta i inkapslade objekt och punktmarkeringen kan användas för att skapa hierarkin.

{
  "Version" : 1,
  "RootElement" : {
    "Parent" : {
      "Name" : "This is the parent",
      "Child" : {
        "Name" : "This is the child"
      }
    }
  }
}

När du konverterar den här JSON-strängen till en Objekt utan typ variabel med namnet jsonObject, går det att komma åt fälten med hjälp av punktmarkering.

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"

Om något av fälten i punktmarkering uttrycket inte finns returneras Blank().

Matriser och tabeller

JSON kan innehålla matriser med värden eller poster. Matriserna kan nås direkt eller göras om till Power Fx tabeller.

{
  "OrderNumber" : "SO000010",
  "CustomerID" : "CUST0126",
  "OrderLines" : [
    {
      "Item" : "Widget 1",
      "Quantity" : 3
    },
    {
      "Item" : "Widget 2",
      "Quantity" : 5
    }
  ]
}

Denna JSON innehåller en post med ett fält med namnet OrderLines som innehåller en matris med poster. Varje post har två fält: Item och Quantity. Om JSON konverteras till en Objekt utan typ med funktionen ParseJSON och anges till en variabel med namnet jsonOrder kan vi komma åt de enskilda orderraderna på flera sätt.

Set( jsonOrder, ParseJSON( jsonStringVariable ) );

Du kan hämta enskilda poster och värden med hjälp av funktionen Index(). Om du till exempel vill hämta den andra posten i fältet OrderLines öppnar du fältet Quantity och konverterar det till ett värde.

Set( line2Quantity, Value( Index( jsonOrder.OrderLines, 2 ).Quantity ); // 5

Du kan konvertera matrisen med orderrader direkt till en tabell. Detta kommer att skapa en tabell med en kolumn med en Objekt utan typ som representerar posten.

Set( orderLines, Table( jsonOrder.OrderLines ) );

En kolumntabell "orderLines" har nu en Värde-kolumn som representerar det Objekt utan typ. Om du vill använda något av fälten från en post i den här tabellen använder du punktmarkering för att komma åt det specifika JSON-fältet i Objekt utan typ i kolumnen Value.

Set( jsonRecord, Index( orderLines, 2 ) ); // Get the second record in the table

Set( line2Item, Text( jsonRecord.Value.Item ) ); // "Widget 2"

För att göra användningen av orderradsposterna enklare i andra delar av ditt program, kan du konvertera hela Objekt utan typ till en helt typangiven post med funktionen ForAll(). Om du tillhandahåller Objekt utan angiven typ direkt till ForAll() innebär att du kan komma åt objektfälten direkt istället för att använda den arkiverade en kolumnen i fältet Value.

Set( typedOrderLines, ForAll( jsonOrder.OrderLines, { Item : Text( ThisRecord.Item ), Quantity : Value( ThisRecord.Quantity ) } ) );

Den nya typedOrderLines variabeln är nu en helt typangiven Power Fx-tabell med följande kolumner och värden:

Artikel	Kvantitet
"Widget 1"	3
"Widget 2"	5

I de tidigare exemplen används matriser med poster, men JSON kan också innehålla matriser med endast värden. Följande exempel är en giltig JSON-sträng som innehåller en matris med tre strängar.

[ "First Item", "Second Item", "Third Item"]

Vi kan hämta ett av objekten från matrisen med hjälp av funktionen Index() och konvertera det till text.

Text( Index( ParseJSON( jsonStringVariable ), 2 ) ) // "Second Item"