Utilisation des fonctions JSON

FileMaker Pro fournit plusieurs fonctions texte permettant à votre app personnalisée d'analyser et de modifier les données JSON à partir d'autres sources, tels que les services Web qui transfèrent les données au format JSON via une API REST.

Pour plus d'informations sur le format de données JSON, consultez le site Web json.org.

Mise en forme de données JSON

Les données JSON ne nécessitent pas d'espace ou de fin de ligne entre les éléments. Cependant, pour faciliter la lecture des données lors de la résolution de problèmes, utilisez la fonction JSONFormatElements, qui ajoute des tabulations et des caractères de fin de ligne, tel qu'indiqué dans la section Exemple de données JSON.

Analyse de données JSON

Les fonctions JSON suivantes vous permettent d'analyser des données JSON, notamment d'obtenir des clés, des valeurs, des tableaux ou des objets JSON entiers pour un traitement supplémentaire :

  • JSONGetElement : interroge les données JSON à propos d'un élément (objet, tableau ou valeur).

  • JSONListKeys : répertorie les noms d'objet (clés) ou index de tableau dans les données JSON.

  • JSONListValues : répertorie les valeurs dans les données JSON.

Le premier paramètre de ces fonctions, json, spécifie la rubrique Texte, la variable ou l'expression de type texte contenant les données JSON valides sur lesquelles agir.

Le second paramètre, cléOuIndexOuChemin, spécifie la partie des données JSON sur lesquelles agir.

  • clé : nom d'une clé dans un objet JSON.

  • index : index d'un élément dans un tableau JSON (le premier élément a un index de 0).

  • chemin d'accès : chaîne hiérarchique de noms de clé et/ou d'index de tableau

Les deux types de syntaxe suivants sont pris en charge pour le paramètre cléOuIndexOuChemin : notation par points et notation par crochets.

Syntaxe du paramètre cléOuIndexOuChemin

Désigne
Notation par points Notation par crochets

"."

""

Le niveau racine, s'il s'agit du premier caractère (facultatif dans la notation par points)

".[n]"

"[n]"

Les éléments à l'index n d'un tableau au niveau racine

".nom"

"['nom']"

La clé d'un objet nommé nom au niveau racine

".nomA.nomB.nomC"

"['nomA']['nomB']['nomC']"

Un objet nommé nomC, qui est un descendant de nomB et nomA

".[3][2][1]nomA[0]"

"[3][2][1]['nomA'][0]"

Le premier élément du tableau dans l'objet nomA, qui est au troisième niveau dans un ensemble de tableaux imbriqués.

"[:]"

"[:]"

Le dernier élément d'un tableau

"[+]"

"[+]"

La position après le dernier élément d'un tableau. Utilisé dans la fonction JSONSetElement pour ajouter un élément à la fin d'un tableau.

La différence entre la notation par points et par crochets est qu'au lieu d'utiliser des points (.) pour séparer les noms des clés, la notation par crochets entoure les noms de clés avec des guillemets simples (') et des crochets ([]). Vous pouvez utiliser l'une ou l'autre dans le paramètre cléOuIndexOuChemin. Toutefois, vous devez utiliser la notation par crochets si les noms de clé incluent des points, afin que l'analyseur JSON puisse correctement identifier le nom de la clé. Par exemple, si une clé à la racine d'un objet JSON est « modèle.réponse », alors le paramètre cléOuIndexOuChemin est « ['modèle.réponse'] ».

L'exemple de script suivant crée un enregistrement pour chaque produit dans un tableau JSON. En supposant que l'Exemple de données JSON soit stocké dans la variable $$JSON, le script utilise JSONListValues pour obtenir le contenu du tableau de produits sous la forme d'une liste de valeurs et utilise DecompteValeurs pour déterminer le nombre de produits figurant dans la liste. En enregistrant systématiquement un produit dans la boucle, le script utilise ObtenirValeur pour obtenir l'objet JSON d'un produit dans la liste et configure les rubriques en utilisant les valeurs obtenues à l'aide de JSONGetElement. Étant donné que les fonctions JSON analysent intégralement l'objet JSON qui leur a été transmis, il est recommandé d'utiliser les fonctions JSON sur des objets JSON plus petits figurant dans une boucle répétée plusieurs fois.

Copier 
Définir variable [ $ProductList ; Valeur: JSONListValues ( $$JSON ; "boulangerie.produit" ) ]
Définir variable [ $ProductCount ; Valeur: DecompteValeurs ( $ProductList ) ]
Définir variable [ $i ; Valeur: 1 ]
Si [ $ProductCount > 0 ]
   Boucle [ Purge: Systématique ]
      Nouvel enreg./requête
      Définir variable [ $Product ; Valeur: ObtenirValeur ( $ProductList ; $i ) ]
      Définir rubrique [ Produits::Identifiant ; JSONGetElement ( $Product ; "id" ) ]
      Définir rubrique [ Produits::Prix ; JSONGetElement ( $Product ; "prix" ) ]
      Définir rubrique [ Produits::Stock ; JSONGetElement ( $Product ; "stock" ) ]
      Valider enreg./requêtes [ Avec boîte de dialogue: Non ]
      Définir variable [ $i ; Valeur: $i + 1 ] 
      Fin de boucle si [ $i > $ProductCount ]
   Fin de boucle
Fin de si

Modification et ajout d'éléments de données JSON

La fonction JSONSetElement vous permet de modifier des valeurs et d'ajouter des éléments dans les données JSON. Les paramètres json et cléOuIndexOuChemin fonctionnent au sein de cette fonction, tel que décrit dans la section Analyse de données JSON. Si le paramètre cléOuIndexOuChemin spécifie un élément existant, la valeur de cet élément est modifiée ; si l'élément n'existe pas, un nouvel élément est ajouté.

La fonction JSONSetElement définit l'élément spécifié sur le paramètre valeur. Vous pouvez spécifier n'importe quelle valeur JSON valide, allant d'un simple nombre ou chaîne à un objet ou un tableau complexe.

Le paramètre type spécifie le type de données du paramètre valeur de façon à ce que l'analyseur JSON suive des règles strictes lors de la gestion de chaque type de données. Pour connaître les types de données pris en charge, consultez la section fonction JSONSetElement. Pour insérer des données dans le paramètre json déjà mis en forme comme élément JSON valide, définissez le paramètre type sur JSONRaw.

L'exemple suivant ajoute des paires clé-valeur pour un nouveau produit à un objet JSON vide. Ensuite, le nouvel objet est ajouté à la fin du tableau de produits dans la variable $$JSON (consultez la section Exemple de données JSON).

Copier 
Définir variable [ $NewProduct ; Valeur: 
   JSONSetElement ( "{}" ;
      [ "id" ; "FB4" ; JSONString ] ; 
      [ "nom" ; "Gâteau à la vanille" ; JSONString ] ; 
      [ "prix" ; 17.5 ; JSONNumber ] ; 
      [ "stock" ; 12 ; JSONNumber ] ; 
      [ "catégorie" ; "Gâteaux" ; JSONString ] ; 
      [ "offre spéciale" ; true ; JSONBoolean ] 
   ) ]
Définir variable [ $NextIndex ; Valeur: 
   DecompteValeurs ( 
      JSONListKeys ( $$JSON ; "boulangerie.produit" ) 
   ) ] 
Définir variable [ $$JSON ; Valeur: 
   JSONSetElement ( 
      $$JSON ; "boulangerie.produit[" & $NextIndex & "]" ; $NewProduct ; 
      JSONObject 
   ) ]

Une autre fonction JSON qui crée un élément JSON est la fonction JSONMakeArray. Elle convertit une liste de valeurs en un tableau JSON. Pour accepter les données formatées de différentes manières, cette fonction vous permet de spécifier le caractère qui sépare chaque valeur et le type de données JSON à utiliser.

Suppression d'éléments de données JSON

La fonction JSONDeleteElement vous permet de supprimer un élément. Les paramètres json et cléOuIndexOuChemin fonctionnent au sein de cette fonction, tel que décrit dans la section Analyse de données JSON. Le paramètre cléOuIndexOuChemin doit spécifier un élément existant dans le paramètre json.

L'exemple suivant supprime l'élément dans le tableau de produits dont la clé « ID » a la valeur « FB3 » dans la variable $$JSON (consultez la section Exemple de données JSON).

Copier 
Définir variable [ $ProductCount ; Valeur: 
   DecompteValeurs ( 
      JSONListKeys ( $$JSON ; "boulangerie.produit" ) 
   ) ] 
Définir variable [ $i ; Valeur: 0 ]
Si [ $ProductCount > 0 ]
   Boucle [ Purge: Systématique ]
      Définir variable [ $ID ; Valeur: 
         JSONGetElement ( $$JSON ; "boulangerie.produit[" & $i & "]id" ) ]
      Si [ $ID = "FB3" ]
         Définir variable [ $$JSON ; Valeur: 
            JSONDeleteElement ( $$JSON ; "boulangerie.produit[" & $i & "]" ) ]
         Fin de script [ Résultat de texte: 0 ]
      Fin de si
      Définir variable [ $i ; Valeur: $i + 1 ]
      Fin de boucle si [ $i ≥ $ProductCount ]
   Fin de boucle
Fin de si

Gestion des erreurs dans les données JSON

Si une erreur se produit lors de l'analyse du paramètre json, les fonctions JSON renvoient le caractère « ? » suivi d'un message d'erreur de l'analyseur JSON.

Par exemple, lorsque le caractère « : » après la clé « boulangerie » manque dans l'Exemple de données JSON), ce calcul

Copier 
JSONGetElement ( $$JSON ; "boulangerie.produit[0]id" )

renvoie ce message d'erreur :

Copier 
? * Line 3, Column 2
  Missing ':' after object member name
* Line 13, Column 5
  Extra non-whitespace after JSON value.

Pour déterminer si les données JSON sont valides avant de les utiliser, utilisez la fonction JSONFormatElements et vérifiez si le premier caractère est « ? ». Par exemple :

Copier 
Définir variable [ $Résultat ; Valeur: JSONFormatElements ( $$JSON ) ]
Si [ Début ( $Résultat ; 1 ) = "?" ]
   # $$JSON contient des données JSON non valides.
Fin de si

De même, pour déterminer si les données JSON sont valides avant de les utiliser, utilisez la fonction JSONGetElementType et testez si l'objet dans son ensemble est un objet JSON. Par exemple :

Copier 
Définir variable [ $Résultat ; Valeur: JSONGetElementType ( $$JSON, "" ) ]
Si [ $result ≠ JSONObject ]
    # $$JSON contient des données JSON non valides.
Fin de si

Extraction de données JSON à partir d'un service Web

L'action de script Insérer depuis URL vous permet d'accéder à un service Web, de spécifier des paramètres pour les informations à extraire, d'envoyer et de recevoir des en-têtes HTTP, et de stocker les résultats dans une variable ou une rubrique.

Par exemple, une boulangerie rend sa liste de produits au format JSON accessible aux clients via une API REST. L'exemple suivant renvoie la liste des offres spéciales du jour sous forme de données JSON dans la variable $$JSON :

Copier 
Définir variable [ $url ; "https://boulangerie.exemple.com/rest/api/products" ]
Copier 
Insérer depuis URL [ Avec boîte de dialogue: Non ; Cible: $$JSON ; $url ; Vérifier les certificats SSL ; options cURL: "--data liste=offres spéciales" ]

Pour les données renvoyées au format $$JSON, consultez la section Exemple de données JSON.

FileMaker Pro fournit également plusieurs fonctions utilitaires qui gèrent le codage de caractères et la signature cryptographique requis par certaines API REST :

Exemple de données JSON

L'exemple de données JSON suivant contient un objet « boulangerie » qui a un tableau de trois objets « produits », chacun avec plusieurs paires clé-valeur.

Copier 
{
    "boulangerie" : 
    {
        "produit" : 
        [
            {
                "id" : "FB1",
                "nom" : "Donuts",
                "prix": 1.99,
                "stock" : 43,
                "catégorie" : "Pains",
                "offre spéciale" : true
            },
            {
                "id" : "FB2",
                "prix": 22.5,
                "nom" : "Gâteau au chocolat",
                "stock" : 23,
                "catégorie" : "Gâteaux", 
                "offre spéciale" : true
            },
            {
                "id" : "FB3",
                "prix": 3.95,
                "nom" : "Baguette",
                "stock" : 34,
                "catégorie" : "Pains", 
                "offre spéciale" : true
            }
        ]
    }
}

Remarques 

  • L'analyseur JSON conserve l'ordre des éléments dans un tableau, mais pas dans un objet. Par conséquent, il se peut que les fonctions JSON renvoient des éléments dans un objet dans un ordre différent de celui spécifié.

  • Dans les données JSON, les valeurs numériques fractionnelles doivent utiliser un point « . » comme séparateur décimal, quel que soit le séparateur spécifié par les formats système de votre ordinateur ou les formats utilisés lors de la création du fichier FileMaker Pro.

Rubriques connexes