Utilisation des fonctions JSON

FileMaker Pro fournit plusieurs fonctions texte permettant à votre solution 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.

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 :

Définir variable [ $url ; "https://<nom_domaine_boulangerie>/rest/api/products" ]

Insérer depuis URL [ Vérifier les certificats SSL ; Avec fenêtre: Non; $$JSON ;
$url ; "--data liste=offres spéciales" ]

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

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 onglets et des caractères de fin de ligne, tel qu'indiqué dans la section Exemple 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 :

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.

Paramètre cléOuIndexOuChemin	Désigne
« . »	(Facultatif) Le niveau racine, s'il s'agit du premier caractère.
« .[n] »	Les éléments à l'index n d'un tableau au niveau racine
« .nom »	La clé d'un objet nommé nom au niveau racine
« .nomA.nomB.nomC »	Un objet nommé nomC, qui est un descendant de nomB et nomA
« .[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.

L'exemple de script suivant détermine le nombre de produits dans l'Exemple de données JSON (données stockées dans la variable $$JSON) à l'aide de la fonction JSONListKeys, crée un enregistrement pour chaque produit, puis définit les rubriques dans chaque enregistrement sur les valeurs obtenues à l'aide de la fonction JSONGetElement pour chaque produit.

Définir variable [ $NombreProduits ; Valeur:
   DecompteValeurs (
      JSONListKeys ( $$JSON ; "produit.boulangerie" )
   ) ]
Définir variable [ $i; Valeur: 0 ]
Si [ $NombreProduits > 0 ]
   Boucle
      Nouvel enreg./requête
      Définir rubrique [ Produits::ID ;
         JSONGetElement ( $$JSON ; "produit.boulangerie[" & $i & "]id" ) ]
      Définir rubrique [ Produits::Prix ;
         JSONGetElement ( $$JSON ; "produit.boulangerie[" & $i & "]prix" ) ]
      Définir rubrique [ Produits::Stock ;
         JSONGetElement ( $$JSON ; "produit.boulangerie[" & $i & "]stock" ) ]
      Valider enreg./requêtes [ Avec fenêtre: Non ]
      Définir variable [ $i; Valeur: $i + 1 ]
      Fin de boucle si[ $i ≥ $NombreProduits ]
   Fin de boucle
Fin de si

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 JSON dans le paramètre json, vous pouvez définir le paramètre type sur JSONRaw de sorte que l'analyseur JSON détermine le type de données du paramètre valeur.

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).

Définir variable [ $NouveauProduit ; 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" ; vrai ; JSONBoolean ]
   ) ]
Définir variable [ $IndexSuivant ; Valeur:
   DecompteValeurs (
      JSONListKeys ( $$JSON ; "produit.boulangerie" )
   ) ]
Définir variable [ $$JSON ; Valeur:
   JSONSetElement (
      $$JSON ; "produit.boulangerie[" & $IndexSuivant & "]" ; $NouveauProduit ;
      JSONObject
   ) ]

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).

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

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

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

? * 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 :

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

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.

{
"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
}
]
}
}

•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é.