Utilisation de JSON dans Power Fx

Power Fx permet aux créateurs de lire JSON dans un Objet sans type en utilisant la fonction ParseJSON.

Lecture et conversion de valeurs

ParseJSON convertit la chaîne d’enregistrement JSON suivant dans un Objet sans type avec des champs ItemName, Quantity, ReleaseDate et AvailableForPreOrder.

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

Chacun des champs est accessible à l’aide de la notation par points sur la valeur Objet sans type renvoyée par 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 ) );

Il est généralement recommandé de convertir explicitement la valeur d’un objet sans type en un type spécifique. Définir un objet sans type comme valeur de variable convertit également la variable en un objet sans type. Par conséquent, il est probablement nécessaire de convertir explicitement cette valeur lors de la définition d’une variable. Mais dans la plupart des cas, les valeurs d’objet sans type sont converties automatiquement en un type spécifique (« forcer ») lorsqu’elles sont utilisées comme paramètres de fonction où le type est un type simple comme un booléen, nombre ou texte, et le profil de paramètre de la fonction n’a pas de surcharges potentielles en conflit.

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

En plus de convertir automatiquement le type dans les appels de fonction, les objets sans type sont également convertis lorsqu’ils sont affectés à des propriétés de contrôle, dans la mesure du possible.

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

Et enfin, lorsque utilisez des opérateurs tels que & ou +, un L’objet non typé sera forcé s’il n’y a pas d’ambiguïté sur le type attendu.

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

Note

JSON n’a pas de type GUID, Couleur, Heure ou Date et heure. Ces valeurs sont représentées sous forme de chaîne. Si vous attribuez une valeur d’objet sans type JSON contenant une date à une propriété de texte directement, le texte d’origine du JSON est utilisé. Cela peut être important lorsqu’il s’agit de fuseaux horaires, de formats de date, etc. Dans ces cas, vous devez convertir explicitement les valeurs en utilisant GUID(), ColorValue(), DateValue(), DateTimeValue(), etc.

Au cas où un nom de champ se compose d’un nom d’identifiant invalide, par exemple lorsque les noms de champ commencent par un nombre ou contiennent des caractères invalides comme un trait d’union, vous pouvez mettre les noms de champ entre guillemets simples :

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

Power Fx n’évalue pas l’existence du champ tant que la formule n’a pas été exécutée. Cela permet une flexibilité dans le JSON entrant. Par exemple, le précédent JSON peut parfois contenir un champ supplémentaire appelé Discount. Mais dans notre exemple précédent, ce champ n’est pas présent. Écrire une formule qui utilise le champ Discount n’entraîne aucune erreur, pendant le processus de création de l’application ou lorsque les utilisateurs utilisent l’application. Si le champ est manquant lors de l’exécution de la formule, la valeur se traduit simplement par une valeur Blank().

Note

JSON prend en charge les valeurs null pour les champs. Celles-ci se traduisent également par des valeurs Blank(). Actuellement, il n’y a pas de distinction dans Power Fx entre un champ manquant ou un champ qui a la valeur null.

Puisque l’accès aux champs sur Objets sans type n’est pas évalué lors de l’écriture de la formule, Intellisense n’est pas disponible. JSON et Power Fx sont sensibles à la casse, faites donc très attention en écrivant les noms de champs.

Les valeurs JSON ne doivent pas nécessairement être dans une notation de type enregistrement. Un JSON valide peut être simplement une valeur, telle que "text value", true ou 123.456. Dans un tel cas, l’objet sans type que ParseJSON renvoie est la valeur elle-même et la notation par points n’est pas utilisée.

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

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

Enfin, JSON prend en charge les enregistrements imbriqués. La conversion d’un JSON en Objet sans type donne des objets imbriqués et la notation par points peut être utilisée pour parcourir la hiérarchie.

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

Lors de la conversion de cette chaîne JSON en une variable Objet sans type nommée jsonObject, les champs sont accessibles à l’aide de la notation par points.

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"

Si l’un des champs de l’expression en notation par points n’existe pas, Blank() sera retourné.

Tableaux et tables

JSON peut contenir des tableaux de valeurs ou d’enregistrements. Ces tableaux sont accessibles directement ou convertis en tables Power Fx.

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

Ce JSON contient un enregistrement avec un champ nommé OrderLines qui contient un tableau d’enregistrements. Chaque enregistrement comporte deux champs : Item et Quantity. Si le JSON est converti en un Objet sans type en utilisant la fonction ParseJSON et définie sur une variable nommée jsonOrder, nous pouvons accéder aux lignes de commande individuelles de plusieurs manières.

Set( jsonOrder, ParseJSON( jsonStringVariable ) );

Vous pouvez récupérer les enregistrements individuels et les valeurs à l’aide de la fonction Index(). Par exemple, pour obtenir le deuxième enregistrement dans le champ OrderLines, puis accédez au champ Quantity et convertissez-le en valeur.

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

Vous pouvez convertir le tableau de lignes de commande directement en table. Cela génère une table à colonne unique avec un Objet sans type représentant le dossier.

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

La table à colonne unique « orderLines » a maintenant une colonne « Value » qui représente l’objet sans type. Pour utiliser l’un des champs d’un enregistrement de cette table, utilisez la notation par points pour accéder au champ spécifique JSON sur l’objet sans type dans la valeur Value.

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

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

Pour rendre l’utilisation des enregistrements de ligne de commande plus facile et plus simple dans d’autres parties de votre application, vous pouvez convertir l’ensemble Objet sans type à un enregistrement entièrement dactylographié à l’aide de la fonction ForAll(). Fournir l’objet sans type directement à ForAll() signifie que vous pouvez accéder directement aux champs de l’objet au lieu d’utiliser le champ Value à colonne unique.

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

La nouvelle variable typedOrderLines est maintenant une table Power Fx entièrement typée avec les colonnes et les valeurs suivantes :

Item	Quantité
"Widget 1"	3
"Widget 2"	5

Les exemples précédents utilisent des tableaux d’enregistrements, mais JSON peut également contenir des tableaux de valeurs uniquement. Prenons l’exemple suivant qui représente une chaîne JSON valide contenant un tableau de trois chaînes.

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

Nous pouvons récupérer l’un des éléments du tableau en utilisant la fonction Index() et convertissez-le en texte.

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