Création d'une app personnalisée > Utilisation des formules et des fonctions > Utilisation des fonctions JSON
 

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.

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 :

Définir variable [ $url ; "https://boulangerie.exemple.com/rest/api/products" ]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 :

fonction HexDecode

fonction HexEncode

fonction TextDecode

fonction TextEncode

fonction Base64Decode

fonction Base64EncodeRFC

fonction CryptAuthCode

fonction CryptDigest

fonction CryptGenerateSignature

fonction CryptVerifySignature

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

La syntaxe suivante est prise en charge pour le paramètre cléOuIndexOuChemin.

 

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 [ $ProductCount ; Valeur:
   DecompteValeurs (
      JSONListKeys ( $$JSON ; "boulangerie.produit" )
   ) ]
Définir variable [ $i; Valeur: 0 ]
Si [ $ProductCount > 0 ]
   Boucle
      Nouvel enreg./requête
      Définir rubrique [ Produits::ID ;
         JSONGetElement ( $$JSON ; "boulangerie.produit[" & $i & "]id" ) ]
      Définir rubrique [ Produits::Prix ;
         JSONGetElement ( $$JSON ; "boulangerie.produit[" & $i & "]prix" ) ]
      Définir rubrique [ Produits::Stock ;
         JSONGetElement ( $$JSON ; "boulangerie.produit[" & $i & "]stock" ) ]
      Valider enreg./requêtes [ Avec fenêtre: 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).

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

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

Définir variable [ $ProductCount ; Valeur:
   DecompteValeurs (
      JSONListKeys ( $$JSON ; "boulangerie.produit" )
   ) ]
Définir variable [ $i; Valeur: 0 ]
Si [ $ProductCount > 0 ]
   Boucle
      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

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

renvoie ce message d'erreur :

? * 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: JSONFormatElements ( $$JSON ) ]
Si [ Début ( $Résultat ; 1 ) = "?" ]
   # $$JSON contient des données JSON non valides.
Fin de si

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.

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

Fonctions Texte

Fonctions Conteneur