Expert Liaison de données JSON

De RAD Studio
Aller à : navigation, rechercher

Remonter à Menu Fichier

Fichier > Nouveau > Autre... > Delphi > Web > Liaison de données JSON

L'expert Liaison de données JSON fournit un moyen facile de créer des types de données Delphi basés sur une structure de données JSON et de mapper ces types sur les données JSON en utilisant l'une des bibliothèques de marshaling et de sérialisation JSON Delphi.

Cet expert guide le développeur dans la définition de différentes options pour l'aider à créer une nouvelle unité avec le mappage des données basé sur une structure de données JSON existante utilisée comme plan.

Résumé : Comment cela fonctionne-t-il ?

L'expert prend un texte JSON, l'analyse et génère un ensemble de types Delphi.

Comme JSON ne dispose pas d'une définition de schéma officielle ou largement utilisée, le résultat de l'analyse représente les types les plus adaptés aux données JSON spécifiées.

Le code généré est optimisé pour une bibliothèque JSON spécifiée, que vous pouvez choisir dans l'expert. Voici les bibliothèques actuellement prises en charge :

Exemple

Par exemple, en fonction des données JSON : 

{"customer": {
 "id": 1,
 "name": "Mark",
 "phone": "(831) 431-1000"
}}

L'expert génère les types suivants pour la bibliothèque REST.Json : 

  [JsonSerialize(jmAllPubProps)]
  TCustomer = class(TPersistent)
  private
	Fid: Integer;
	Fname: string;
	Fphone: string;
  public
	property id: Integer read Fid write Fid;
	property name: string read Fname write Fname;
	property phone: string read Fphone write Fphone;
  end;

  [JsonSerialize(jmAllPubProps)]
  TData = class(TPersistent)
  private
	Fcustomer: TCustomer;
  public
	constructor Create;
	destructor Destroy; override;
	property customer: TCustomer read Fcustomer;
  end;

Ensuite, l'application peut utiliser cette bibliothèque ou la classe TJSONMapper<T> de haut niveau pour charger les données JSON dans ces instances de type ou pour sérialiser des instances de type dans JSON.

Par exemple, en utilisant REST.Json : 

  // Load JSON data from “s” string into new TData instance
  LData := TJson.JsonToObject<TData>(s);

  // Serialize TData instance referenced by LData into JSON string
  s := TJson.ObjectToJsonString(LData);

Ou en utilisant TJSONMapper<T> : 

  // Set JSON library to use
  TJSONMapper<TData>.SetDefaultLibrary('REST.Json');

  // Load JSON data from “s” string into new TData instance
  LData := TJSONMapper<TData>.Default.ObjFrom(s);

  // Serialize TData instance referenced by LData into JSON string
  s := TJSONMapper<TData>.Default.ToStr(LData);

Utilisation de l'expert Liaison de données JSON

Vous devez d'abord ouvrir l'expert Liaison de données JSON en sélectionnant Fichier > Nouveau > Autre... > Delphi > Web > Liaison de données JSON.

Effectuez ensuite les étapes suivantes :

Etape 1 : sélectionnez la source JSON

JSON Data Binding Wizard JSON Source.png

Sur la page Source JSON, spécifiez la source JSON à partir de laquelle vous voulez générer les types Delphi.

Les alternatives sont :

  • Coller depuis le presse-papiers : utilise le texte JSON déjà enregistré dans le presse-papiers. Cette option est uniquement disponible lorsque le presse-papiers contient déjà du texte JSON valide.
  • Saisir les données dans la zone d'édition : permet d'introduire le texte JSON dans un éditeur fourni par l'expert lui-même
  • Lire depuis le fichier : l'utilisateur doit fournir un fichier contenant le texte JSON.
  • Obtenir depuis le service REST : importe le texte JSON via une requête HTTP GET à partir d'une URL indiquée sur la page suivante.

Etape 2 : saisissez le texte JSON, fournissez un fichier ou définissez le service REST

Lorsque le texte JSON n'est pas copié depuis le presse-papiers, selon l'option sélectionnée à l'étape précédente, l'utilisateur doit effectuer l'une des actions suivantes :

  • Coller le texte JSON manuellement dans la zone d'édition.
  • Fournir le chemin du fichier contenant le texte JSON.
  • Saisir une URL de point de terminaison, un nom d'utilisateur et un mot de passe.
Remarque: Après avoir appuyé sur le bouton Suivant, l'expert tentera d'obtenir et d'analyser le texte JSON et affichera une boîte de message si des erreurs sont découvertes.

Etape 3 : spécifiez les options de liaison

JSON Data Binding Wizard Binding Options.png

Sur la page Options de liaison, spécifiez comment mapper/lier les éléments JSON aux éléments Delphi. Ici, vous pouvez choisir l'une des bibliothèques de mappage disponibles et sélectionner d'autres paramètres de la logique de mappage.

Les options sont les suivantes :

  • Bibliothèque de mappage JSON : bibliothèque de marshaling/sérialisation JSON, pour laquelle les types Delphi doivent être générés. Les options sont :
    • System.JSON.Serializers
    • REST.Json
  • Mapper le tableau JSON sur : le type de données Delphi qui sera utilisé pour mapper le tableau JSON. Les options possibles sont les suivantes :
    • TArray
    • TList (certaines bibliothèques JSON, comme REST.Json, peuvent ne pas prendre en charge le mappage “TList” sur les tableaux JSON directement).
  • Mapper l'objet JSON sur : le type de données Delphi qui sera utilisé pour mapper les objets JSON. Les options possibles sont les suivantes :
    • TObject
    • enregistrement (certaines bibliothèques JSON, comme REST.Json, peuvent ne pas prendre en charge le type “enregistrement”).
  • Mapper le membre JSON sur : le type de données Delphi qui sera utilisé pour mapper les membres d'objet JSON. Les options possibles sont les suivantes :
    • propriété
    • champ
  • Mapper la chaîne JSON sur : le type de données Delphi qui sera utilisé pour mapper les valeurs de chaînes JSON. Les options possibles sont les suivantes :
    • Unicode
    • Ansi
  • Accesseurs de propriétés : ces options déterminent le code de la classe en cours de génération. Les options possibles sont les suivantes:
    • champs
    • Getters
    • Setters
    • Getters et Setters
    Remarque: Les informations JSON sont mappées sur des champs via des propriétés, mais vous pouvez demander que ces propriétés soient mappées sur des champs directement, sur un champ lors de la lecture ou une méthode setter en écriture, le contraire (très rare) ou les deux méthodes pour la lecture et l'écriture.

Etape 4 : sélectionnez les options de code

JSON Data Binding Wizard Code Options.png

Sur la page Options de code, spécifiez comment nommer les entités Delphi.

Les options sont les suivantes :

  • Nom de classe de base : nom de classe à partir duquel tous les types d'entités générés seront hérités lorsque, sur la page précédente, l'option "Mapper l'objet JSON sur" est définie sur TObject (n'a pas de sens pour le type enregistrement).
  • Nom du type d'objet racine : le nom de l'entité Delphi la plus externe à laquelle l'objet JSON le plus externe sera mappé.
  • Nom du type de tableau racine : facultatif. Le nom de l'entité Delphi qui représentera le tableau des entités “racine”. Si le nom du type de tableau racine n'est pas spécifié, le type d'entité Delphi correspondant n'est pas généré. S'il est spécifié, une entité sera générée comme ceci et comportera une propriété Dataset unique :
[JsonSerialize(jmFields)]
TDataArray = class(TPersistent)
private
FDataset: TArray<TData>;
  public
	destructor Destroy; override;
	property Dataset: TArray<TData> read FDataset write FDataset;
  End;

Pour finir, cliquez sur le bouton Terminer pour générer le code source.

Règles de mappage

L'expert Liaison de données JSON utilise les règles de mappage des données suivantes :

  • L'objet JSON est mappé sur un TObject ou un enregistrement Delphi : le type exact dépend du paramètre Mapper l'objet JSON sur et de la capacité de la bibliothèque JSON à prendre en charge les enregistrements Delphi (la bibliothèque REST.Json ne prend pas en charge les enregistrements).
  • Le tableau JSON est mappé sur un TList<T> ou un TArray<T> Delphi : le type exact dépend du paramètre Mapper le tableau JSON sur et de la capacité de la bibliothèque JSON à désérialiser/sérialiser directement le TList<T> Delphi à partir du tableau JSON. La bibliothèque REST.Json ne prend pas en charge TList<T>;. Au lieu d'effectuer un mappage direct, le mappage est effectué sur un objet JSON contenant un tableau imbriqué.
  • Le membre d'objet JSON est mappé sur un champ ou une propriété Delphi : le type exact dépend des paramètres Mapper le membre JSON sur et Mapper l'objet JSON sur. Le type propriété n'est pas pris en charge pour le type enregistrement.
    • Le type du champ ou de la propriété est deviné après analyse des valeurs dans jusqu'à 1 000 objets lorsque les objets JSON sont collectés dans un tableau JSON. L'expert peut spécifiquement gérer les valeurs date et heure, les TGUID, les booléens, etc.
    • Le nom du champ ou de la propriété est identique au nom du membre JSON, lorsque ce dernier est un identificateur Delphi valide. Sinon, le nom est “modifié” pour être un identificateur valide. De plus, les champs sont préfixés par le caractère “F”.
  • L'expert effectue la “liaison” de la bibliothèque JSON sélectionnée, en incluant trois éléments :
    • Ajoute un attribut à chaque TObject ou type enregistrement, en spécifiant quels membres utiliser dans la sérialisation. Par exemple :
      [JsonSerialize(jmAllPubProps)]
  TCustomer = class(TPersistent)
    • Ajoute un attribut à TObject ou aux membres du type enregistrement lorsque son nom est différent du nom du membre JSON. Par exemple :
      [JsonName('label')]
    property label_: string read Flabel_ write Flabel_;
    • Ajoute une unité bibliothèque là où les attributs ci-dessus sont déclarés pour la clause uses de l'unité générée. Par exemple :
      uses
    System.Classes, REST.Json.Types;
Remarque: L'expert Liaison de données JSON utilise la classe Data.DBJson.TJSONToDataSetBridge pour analyser la structure JSON et remplir la collection Data.DB.TFieldDefs. Ensuite, l'expert utilise cette collection pour générer les types Delphi.

Comment utiliser les types générés

Les types Delphi générés peuvent être utilisés avec la bibliothèque JSON qui a été choisie dans l'expert. Aucune modification supplémentaire n'est requise. Si le mappage de bibliothèque doit être changé, nous recommandons d'utiliser à nouveau l'expert et de choisir la bibliothèque requise.

Par exemple, lorsque vous utilisez REST.Json, vous obtenez ce code : 

  // Load JSON data from “s” string into new TData instance
  LData := TJson.JsonToObject<TData>(s);

  // Serialize TData instance referenced by LData into JSON string
  s := TJson.ObjectToJsonString(LData);

Ici, l'option alternative consiste à utiliser la classe générique System.JSON.TJSONMapper, qui est un wrapper fin des bibliothèques JSON existantes. Elle fournit une API simplifiée pour les opérations de sérialisation/désérialisation JSON les plus courantes, même si elle masque les options et les API spécifiques supplémentaires fournies par les bibliothèques. Par exemple : 

  // Set JSON library to use
  TJSONMapper<TData>.SetDefaultLibrary('REST.Json');

  // Load JSON data from “s” string into new TData instance
  LData := TJSONMapper<TData>.Default.ObjFrom(s);

  // Serialize TData instance referenced by LData into JSON string
  s := TJSONMapper<TData>.Default.ToString(LData);

Pour de plus amples informations, veuillez consulter System.JSON.TJSONMappers.

Voir aussi

Récupérée de « https://docwiki.embarcadero.com/RADStudio/Athens/f/index.php?title=Expert_Liaison_de_données_JSON&oldid=218674 »