Arbeiten mit JSON in Power Fx

Power Fx ermöglicht Erstellern, JSON in ein nicht typisiertes Objekt mithilfe der ParseJSON-Funktion einzulesen.

Werte lesen und konvertieren

ParseJSON konvertiert die folgende JSON-Datensatzzeichenfolge in ein nicht typisiertes Objekt mit Feldern ItemName, Quantity, ReleaseDate und AvailableForPreOrder.

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

Auf jedes der Felder kann mit der Punktnotation im Untypisiertes Objekt-Wert zugegriffen werden, der von ParseJSON zurückgegeben wird.

Set( untyped, ParseJSON( jsonStringVariable ) );

Set( item, Text ( untyped.ItemName ) );
Set( quantity, Value ( untyped.Quantity ) );
Set( release, DateValue ( untyped.ReleaseDate ) );
Set( preorder, Boolean ( untyped.AvailableForPreOrder ) );

Es ist im Allgemeinen eine gute Idee, den Wert eines nicht typisierten Objekts explizit in einen bestimmten Typ zu konvertieren. Das Festlegen eines nicht typisierten Objekts als Variablenwert macht die Variable auch zu einem nicht typisierten Objekt. Daher ist es wahrscheinlich erforderlich, einen solchen Wert explizit zu konvertieren, wenn er auf eine Variable gesetzt wird. Aber in den meisten Fällen werden nicht typisierte Objektwerte automatisch in einen bestimmten Typ konvertiert („erzwingen“), wenn sie als Funktionsparameter verwendet werden, wenn der Typ ein einfacher Typ wie boolesch, Zahl oder Text ist und das Parameterprofil der Funktion keine potenziell widersprüchlichen Überladungen aufweist.

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

Neben der automatischen Konvertierung des Typs in Funktionsaufrufen werden auch nicht typisierte Objekte konvertiert, wenn sie Steuerelementeigenschaften zugewiesen werden, sofern dies möglich ist.

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

Und schließlich wird beim Verwenden von Operatoren wie zum Beispiel & oder + ein nicht typisiertes Objekt erzwungen, wenn bezüglich des erwarteten Typs keine Mehrdeutigkeit besteht.

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

Anmerkung

JSON hat keinen Typ GUID, Farbe, Zeit oder Terminzeit. Diese Werte werden als Zeichenfolge dargestellt. Wenn Sie einen nicht typisierten Objektwert für JSON, der ein Datum enthält, einer Texteigenschaft direkt zuweisen, wird der ursprüngliche Text von JSON verwendet. Dies kann wichtig sein, wenn es um Zeitzonen, Datumsformate usw. geht. In solchen Fällen sollten Sie die Werte mit GUID(), ColorValue(), DateValue(), DateTimeValue() usw. explizit konvertieren.

Falls ein Feldname aus einem ungültigen Bezeichnernamen besteht, beispielsweise wenn der Feldname mit einer Zahl beginnt oder ungültige Zeichen wie einen Bindestrich enthält, können Sie die Feldnamen in einfache Anführungszeichen setzen:

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

Power Fx wertet das Vorhandensein des Felds erst aus, wenn die Formel ausgeführt wird. Dies ermöglicht Flexibilität beim eingehenden JSON. Zum Beispiel kann das vorherige JSON manchmal ein zusätzliches Feld namens Discount enthalten. Aber in unserem vorherigen Beispiel ist dieses Feld nicht vorhanden. Das Schreiben einer Formel, die das Discount-Feld verwendet, führt zu keinen Fehlern, weder während der App-Erstellung noch wenn Benutzer die App verwenden. Wenn das Feld fehlt, wenn die Formel ausgeführt wird, ergibt der Wert nur einen Blank()-Wert.

Notiz

JSON unterstützt null-Werte für Felder. Diese ergeben ebenfalls Blank()-Werte. Derzeit gibt es keine Unterscheidung in Power Fx zwischen einem fehlenden Feld oder einem Feld mit dem Wert null.

Da der Zugriff auf Felder für Untypisierte Objekte beim Schreiben der Formel nicht ausgewertet wird, ist auch Intellisense nicht verfügbar. Sowohl JSON als auch Power Fx beachten die Groß- und Kleinschreibung, seien Sie also besonders vorsichtig beim Schreiben von Feldnamen.

JSON-Werte müssen nicht im Stil eines Datensatzes geschrieben werden. Gültiges JSON kann nur ein Wert sein, wie z. B. "text value", true oder 123.456. In einem solchen Fall ist das nicht typisierte Objekt, das ParseJSON zurückgibt, der Wert selbst, und die Punktnotation wird nicht verwendet.

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

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

Schließlich unterstützt JSON verschachtelte Datensätze. Solches JSON in Untypisiertes Objekt zu konvertieren, führt zu verschachtelten Objekten, und die Punktnotation kann verwendet werden, um die Hierarchie zu durchlaufen.

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

Bei der Konvertierung dieser JSON-Zeichenfolge in eine Untypisiertes Objekt-Variable namens jsonObject kann auf die Felder mit der Punktnotation zugegriffen werden.

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"

Wenn eines der Felder im Punktnotationsausdruck nicht vorhanden ist, wird Blank() zurückgegeben.

Arrays und Tabellen

JSON kann Arrays von Werten oder Datensätzen enthalten. Auf diese Arrays kann direkt zugegriffen werden, oder sie können in Power Fx-Tabellen konvertiert werden.

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

Dieses JSON enthält einen Datensatz mit einem Feld namens OrderLines, das ein Array von Datensätzen enthält. Jeder Datensatz hat zwei Felder: Item und Quantity. Wenn das JSON in ein Untypisiertes Objekt mithilfe der ParseJSON-Funktion konvertiert und auf eine Variable namens jsonOrder festgelegt wird, können wir auf verschiedene Arten auf die einzelnen Auftragszeilen zugreifen.

Set( jsonOrder, ParseJSON( jsonStringVariable ) );

Sie können einzelne Datensätze und Werte mithilfe der Index()-Funktion abrufen. Um beispielsweise den zweiten Datensatz im OrderLines-Feld abzurufen, greifen Sie dann auf das Quantity-Feld zu und konvertieren es in einen Wert.

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

Sie können das Array von Auftragszeilen direkt in eine Tabelle umwandeln. Dadurch wird eine einspaltige Tabelle mit einem nicht typisierten Objekt erstellt, das den Datensatz darstellt.

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

Die einspaltige Tabelle „orderLines“ hat jetzt eine „Value“-Spalte, die das nicht typisierte Objekt darstellt. Um eines der Felder aus einem Datensatz in dieser Tabelle zu verwenden, verwenden Sie die Punktnotation, um auf das spezifische JSON-Feld für das nicht typisierte Objekt in der Value-Spalte zuzugreifen.

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

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

Um die Verwendung der Auftragszeilendatensätze in anderen Teilen Ihrer App einfacher und unkomplizierter zu gestalten, können Sie das Ganze nicht typisierte Objekt in einen vollständig typisierten Datensatz mit der ForAll()-Funktion konvertieren. Bereitstellung von Untypisiertes Objekt direkt zu Für alle() bedeutet, dass Sie direkt auf die Objektfelder zugreifen können, anstatt das einspaltige Feld Value zu verwenden.

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

Die neue typedOrderLines-Variable ist jetzt eine vollständig typisierte Power Fx-Tabelle mit folgenden Spalten und Werten:

Artikel	Menge
„Widget 1“	3
„Widget 2“	5

Die vorherigen Beispiele verwenden Arrays von Datensätzen, aber JSON kann auch Arrays nur aus Werten enthalten. Betrachten Sie das folgende Beispiel, das eine gültige JSON-Zeichenfolge ist, die ein Array aus drei Zeichenfolgen enthält.

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

Wir können eines der Elemente aus dem Array abrufen, indem wir die Index()-Funktion verwenden, und es in Text konvertieren.

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