Práce s jazykem JSON v Power Fx

Power Fx umožňuje tvůrcům číst JSON do netypovaného objektu pomocí funkce ParseJSON.

Čtení a převod hodnot

ParseJSON převede následující řetězec záznamu JSON na netypovaný objekt s poli ItemName, Quantity, ReleaseDate a AvailableForPreOrder.

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

Ke každému z polí lze přistupovat pomocí tečkové notace na hodnotu netypovaného objektu vrácenou z 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 ) );

Obecně je dobré explicitně převést hodnotu netypovaného objektu na konkrétní typ. Nastavením netypovaného objektu jako hodnoty proměnné se proměnná stane rovněž netypovaný objekt. Je tedy pravděpodobné, že bude potřeba explicitně převést takovou hodnotu při nastavení na proměnnou. Ale ve většině případů se hodnoty netypovaných objektů automaticky převedou na konkrétní typ („donucení“), když se použijí jako parametry funkce, kde typ je jednoduchý typ, jako je logická hodnota, číslo nebo text, a profil parametrů funkce nemá potenciální konfliktní přetížení.

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

Kromě automatického převodu typu ve volání funkcí budou také netypované objekty převedeny při přiřazení k vlastnostem ovládacího prvku, pokud je to možné.

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

A nakonec, při použití operátorů jako & nebo +, netypový objekt bude převeden, pokud nebudou žádné nejasnosti ohledně očekávaného typu.

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

Poznámka:

JSON nemá typ GUID, Barva, Čas ani DateTime. Tyto hodnoty jsou reprezentovány jako řetězec. Pokud přiřadíte hodnotu netypovaného objektu JSON obsahujícího datum přímo do vlastnosti text, bude použit původní text JSON. To může být důležité při práci s časovými pásmy, formáty data atd. V takových případech byste měli explicitně převést hodnoty pomocí GUID(), ColorValue(), DateValue(), DateTimeValue() atd.

V případě, že název pole obsahuje neplatný název identifikátoru, například když názvy polí začínají číslem nebo obsahují neplatné znaky, jako je spojovník, můžete názvy polí uvést do jednoduchých uvozovek:

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

Power Fx nevyhodnotí existenci pole, dokud nebude vzorec spuštěn. To umožňuje flexibilitu v příchozích JSON. Například předchozí JSON může někdy obsahovat další pole s názvem Discount. Ale v našem předchozím příkladu toto pole není přítomno. Zápis vzorce, který používá pole Discount, nebude mít za následek žádné chyby během procesu vytváření aplikace ani při používání aplikace uživateli. Pokud pole při běhu vzorce chybí, výsledkem bude pouze hodnota Blank().

Poznámka:

JSON podporuje hodnoty null pro pole. Ty budou mít také za následek hodnoty Blank(). V současné době se v Power Fx nerozlišuje mezi chybějícím pole a polem, které má hodnotu null.

Protože se přístup k polím na netypovaných objektech při psaní vzorce nevyhodnocuje, není k dispozici ani Intellisense. JSON i Power Fx rozlišují velká a malá písmena, takže při psaní názvů polí dávejte pozor.

Hodnoty JSON nemusí být v zápisu ve stylu záznamu. Platný JSON může být jen hodnota, jako např. "text value", true nebo 123.456. V takovém případě je netypovaný objekt, který ParseJSON vrací, samotná hodnota a tečková notace se nepoužívá.

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

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

Konečně, JSON podporuje vnořené záznamy. Převádění takových JSON na netypovaný objekt má za výsledek vnořené objekty a tečkovou notaci lze použít k procházení hierarchie.

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

Při převodu tohoto řetězce JSON na proměnnou netypovaného objektu s názvem jsonObject lze k polím přistupovat pomocí tečkové notace.

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"

Pokud některé z polí ve výrazu tečkové notace neexistuje, je vráceno Blank().

Pole a tabulky

JSON může obsahovat pole hodnot nebo záznamů. K těmto polím lze přistupovat přímo nebo je lze převést na tabulky Power Fx.

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

Tento JSON obsahuje záznam s polem s názvem OrderLines, který obsahuje řadu záznamů. Každý záznam má dvě pole: Item a Quantity. Pokud se JSON převede na netypovaný objekt pomocí funkce ParseJSON a nastaví na proměnnou s názvem jsonOrder, můžeme k jednotlivým řádkům objednávky přistupovat několika způsoby.

Set( jsonOrder, ParseJSON( jsonStringVariable ) );

Jednotlivé záznamy a hodnoty můžete načíst pomocí funkce Index(). Chcete-li například získat druhý záznam v poli OrderLines a poté přistoupíte k poli Quantity a převedete ho na hodnotu.

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

Pole řádků objednávek můžete převést přímo na tabulku. Tím se vytvoří jednosloupcová tabulka s netypovaným objektem představujícím záznam.

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

Jednosloupcová tabulka „orderLines“ nyní obsahuje sloupec „Value“, který představuje netypovaný objekt. Chcete-li použít kterékoli z polí ze záznamu v této tabulce, použijte tečkovou notaci pro přístup ke konkrétnímu poli JSON na netypovaném objektu ve sloupci Value.

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

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

Aby bylo používání záznamů řádků objednávek snazší a přímočařejší v jiných částech vaší aplikace, můžete převést celý netypovaný objekt na zcela typovaný záznam pomocí funkce ForAll(). Poskytnutí netypovaného objektu přímo do ForAll() znamená, že můžete přistupovat přímo k polím objektů namísto použití jednosloupcového pole Value.

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

Nová proměnná typedOrderLines je nyní plně typovaná tabulka Power Fx s následujícími sloupci a hodnotami:

Item	Množství
„Widget 1“	3
„Widget 2“	5

Předchozí příklady používají pole záznamů, ale JSON může také obsahovat pole pouze hodnot. Zvažte následující příklad, který je platný řetězec JSON obsahující pole tří řetězců.

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

Můžeme načíst jednu z položek z pole pomocí funkce Index() a převést ji na text.

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