Praca z JSON w Power Fx

Power Fx umożliwia twórcom odczytywanie obiektu JSON do obiektu bez typu przy użyciu funkcji ParseJSON.

Odczyt i konwersja wartości

ParseJSON przekonwertuje następujący ciąg rekordu JSON na obiekt bez typuz polami ItemName, Quantity, ReleaseDate i AvailableForPreOrder.

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

Dostęp do każdego z pól można uzyskać za pomocą notacji kropkowej na wartości obiektu bez typu zwróconej 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 ) );

Generalnie warto jawnie przekonwertować wartość obiektu bez typu na konkretny typ. Ustawienie obiektu bez typu jako wartości zmiennej powoduje również, że zmienna staje się Obiektem bez typu. Tak więc konwersja takiej wartości jawnie podczas ustawiania na zmienną jest prawdopodobnie potrzebna. Jednak w większości przypadków wartości obiektów bez typu są automatycznie konwertowane na określony typ („wymuszane”) jako parametry funkcji, gdzie typ jest prostym typem, takim jak wartość logiczna, liczba lub tekst, a profil parametrów funkcji nie powoduje potencjalnych konfliktów.

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

Nie tylko typ jest automatycznie konwertowany w wywołaniach funkcji, ale również podczas przypisywania do właściwości kontrolki (gdy to możliwe) obiekty nie są konwertowane.

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

Na koniec w przypadku używania operatorów, takich jak& lub +, Nienapisany obiekt zostanie przekonywujący, jeśli nie będzie żadnych wątpliwości co do oczekiwanego 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

Uwaga

Kod JSON nie ma typu GUID, Color, Time ani DateTime . Te wartości są reprezentowane jako ciąg. Jeśli do właściwości tekstowej zostanie przypisana bezpośrednio wartość niedysportowana JSON zawierająca datę, zostanie użyty oryginalny tekst JSON. Może to być ważne podczas kontaktów ze strefami czasowymi, formatami dat itp. W takim przypadku należy jawnie przekonwertować wartości za pomocą identyfikatora GUID(), ColorValue(), DateValue(), DateTimeValue() itp.

Jeśli nazwa pola składa się z nieprawidłowej nazwy identyfikatora, na przykład kiedy nazwa pola rozpoczyna się od liczby lub zawiera nieprawidłowe znaki, na przykład łącznik, można umieścić nazwy pól w pojedynczym cudzysłowie:

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

Power Fx nie będzie oceniać iniekcjowania pola do momentu uruchomienia formuły. Umożliwia to elastyczność przychodzącego JSON. Na przykład poprzednia JSON może czasami zawierać pole dodatkowe o nazwie Discount. Jednak w poprzednim przykładzie to pole nie występuje. Napisanie formuły korzystającej z pola Discount nie spowoduje żadnych błędów podczas procesu tworzenia aplikacji ani podczas korzystania z aplikacji przez użytkowników. Jeśli podczas działania formuły nie ma pola, ta wartość spowoduje tylko wartość Blank().

Uwaga

Format JSON obsługuje null wartości pól. Będą również powodować wartości Blank(). Obecnie nie istnieje rozróżnienie w Power Fx między brakuje polem ani polem z wartością null.

Ponieważ dostęp do pól w Niewpisanych obiektach nie jest oceniany podczas pisania formuły, nie jest też dostępna funkcja Intellisense. Zarówno JSON, jak i Power Fx uwzględniają wielkość liter, więc zachowaj szczególną ostrożność podczas pisania nazw pól.

Wartości JSON nie muszą znajdować się w notacji w stylu rekordu. Prawidłowa wartość JSON może być tylko wartością, taką jak "text value", true lub 123.456. W takim przypadku obiekt bez typu, który zwraca ParseJSON jest samą wartością, a notacja z kropką nie jest używana.

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

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

Na koniec obiekt JSON obsługuje zagnieżdżone rekordy. Konwersja takiego obiektu JSON na obiekt bez typu powoduje zagnieżdżone obiekty, a do hierarchii można użyć notacji kropki.

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

Podczas konwertowania tego ciągu znaków JSON na zmienną objekt bez typu o nazwie jsonObject, dostęp do pól można uzyskać za pomocą notacji kropkowej.

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"

Jeśli któreś z pól w wyrażeniach notacji kropki nie istnieje, zostanie zwrócone pole Blank().

Tablice i tabele

JSON może zawierać tablice wartości lub rekordów. Można uzyskiwać dostęp bezpośrednio do tych tablic lub konwertować je na tabele Power Fx.

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

Ten kod JSON zawiera rekord o nazwie OrderLines pola zawierającego tablicę rekordów. Każdy rekord ma dwa pola: Item i Quantity. Jeśli JSON zostanie przekonwertowany na objekt bez typu przy użyciu funkcji ParseJSON i ustawiony na zmienną o nazwie jsonOrder, możemy uzyskać dostęp do poszczególnych wierszy zamówienia na kilka sposobów.

Set( jsonOrder, ParseJSON( jsonStringVariable ) );

Poszczególne rekordy i wartości można pobierać za pomocą funkcji Index(). Na przykład, aby uzyskać drugi rekord w polu OrderLines, przejdź do pola Quantity i przekonwertuj go na wartość.

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

Tablicę wierszy zamówienia można przekonwertować bezpośrednio na tabelę. Spowoduje to utworzenie tabeli jednokolumnowej z objektem bez typu reprezentującym rekord.

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

Tabela jedno kolumnowa "orderLines" zawiera teraz kolumnę "Wartość", która reprezentuje obiekt bez typu. Aby użyć dowolnego pola z rekordu w tej tabeli, użyj notacji z kropkami, aby uzyskać dostęp do konkretnego pola JSON w obiekcie bez typut w kolumnie Value.

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

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

Aby ułatwić i bardziej prosty sposób korzystania z rekordów wiersza zamówienia w innych częściach aplikacji, można przekonwertować cały nieopisany obiekt na rekord zupełnie wpisaną za pomocą funkcji ForAll(). Udostępnienie Obiekt bez typu bezpośrednio do ForAll() oznacza, że możesz uzyskać bezpośredni dostęp do pól obiektu zamiast używania jednokolumnowego pola Value.

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

Nowa zmienna typedOrderLines jest teraz w pełni typowaną tabelą Power Fx z następującymi kolumnami i wartościami:

Produkt	Ilość
"Widget 1"	3
"Widget 2"	5

W poprzednich przykładach użyto tablic rekordów, ale JSON może również zawierać tablice samych wartości. Rozważ następujący przykład zawierający prawidłowy ciąg JSON zawierający tablicę trzech ciągów.

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

Możemy pobrać jeden z elementów z tablicy za pomocą funkcji Index() i przekonwertować go na tekst.

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