JSON データ バインディング ウィザード
［ファイル］メニュー への移動
ファイル > 新規作成 > その他... > Delphi > Web > JSON データ バインディング
JSON データ バインディング ウィザードを利用すると、JSON データ構造に基づいて Delphi データ型を簡単に作成し、Delphi JSON マーシャリングおよびシリアライゼーション ライブラリの 1 つを使用して、これらの型を JSON データにマップすることが容易になります。
このウィザードは、開発者がさまざまなオプションを設定できるようガイドし、既存の JSON データ構造をブループリントとして基盤とし、そのデータ マッピングを使用して、新しいユニットを作成するの支援します。
概要： 動作の仕組み
ウィザードは JSON テキストを受け取り、分析して、一連の Delphi タイプを生成します。
SON には公式または広く使用されているスキーマ定義がないため、分析の結果は指定された特定の JSON データに最適な型を表します。
生成されたコードは、指定された JSON ライブラリに合わせて最適化されており、そのライブラリはウィザードで選択できます。現時点でサポートされているライブラリは次のとおりです：
例
たとえば、次の JSON データがあるとします：
{"customer": {
"id": 1,
"name": "Mark",
"phone": "(831) 431-1000"
}}
ウィザードは、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;
次に、アプリケーションは、このライブラリまたは高次のシン クラス TJSONMapper<T> を使用して、JSON データをこれらの型のインスタンスに読み込んだり、型のインスタンスを JSON にシリアライズしたりすることができます。
たとえば、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);
または、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);
JSON データ バインディング ウィザードの利用
まず、JSON データ バインディング ウィザードを、［ファイル｜新規作成｜その他...｜Delphi｜Web｜JSON データ バインディング］から開く必要があります。
次に、次の手順を完了させます：
ステップ 1： JSON ソースを選択する
［JSON ソース］ページで、JSON ソースを、生成したい Delphi 型から選択します。
選択肢は次のとおりです：
- クリップボードから貼り付け： すでにクリップボードに保存されている JSON テキストを使用します。このオプションは、クリップボードにすでに有効な JSON テキストが格納されている場合に利用可能です。
- 編集ボックスに入力： ウィザードが提供するエディタに JSON テキストを入力することができます。
- ファイルから読み込み： ユーザーは、JSON テキストを含むファイルを提供する必要があります。
- REST サービスから取得： JSON テキストを HTTP GET リクエストを介して、URL からインポートします（以降で説明）
ステップ 2： JSON 入力、ファイルの提供、または REST サービスの設定
JSON がクリップボードからコピーされないのであれば、前のステップでされたオプションに従い、ユーザーは次のアクションのいずれかを行わなければなりません。
- JSON を編集ボックスに手動で貼り付け
- JSON テキストを含むファイルのパスを指定
- エンドポイント URL、ユーザー名、パスワードの入力
ステップ 3： バインディング オプションを指定する
［バインディング オプション］ページでは、JSON 要素をどのように Delphi 要素にマップ/バインドするかを指定します。ここでは、利用可能なマッピング ライブラリを選び、そのマッピング ロジックの詳細設定を選択することができます：
オプションは次のとおりです。
- JSON マッピング ライブラリ： Delphi 型を生成する必要がある JSON マーシャリング/シリアライゼーション ライブラリ。
選択肢は次のとおりです：
- System.JSON.Serializers
- REST.Json
- JSON 配列のマップ先： JSON 配列をマップする際に使用される Delphi データ型。使用可能なオプションは次のとおりです：
- TArray
- TList （REST.Json などの一部の JSON ライブラリは、JSON 配列への直接の “TList” マッピングをサポートしていない場合があります）。
- JSON オブジェクトのマップ先： JSON オブジェクトをマップする際に使用される Delphi データ型。 使用可能なオプションは次のとおりです：
- TObject
- record （REST.Json などの一部の JSON ライブラリは、“record” 型をサポートしていない場合があります）。
- JSON メンバーのマップ先： JSON オブジェクト メンバーをマップする際に使用される Delphi データ型。 使用可能なオプションは次のとおりです：
- プロパティ
- フィールド
- JSON 文字列のマップ先： JSON 文字列値をマップする際に使用される Delphi データ型。 使用可能なオプションは次のとおりです：
- Unicode
- Ansi
- プロパティ アクセサ： これらのオプションは、生成されるクラスのコードを決定します。使用可能なオプションは次のとおりです：
- フィールド
- 取得メソッド
- 設定メソッド
- 取得メソッドと設定メソッド
- メモ: JSON 情報はプロパティを介してフィールドにマップされますが、これらのプロパティをフィールドに直接マップするように要求したり、読み取り時にフィールドに、書き込み時に設定メソッドに、またはその逆（非常にまれだが）、または、読み書きのために 2 つのメソッドにマップするように要求したりすることもできます。
ステップ 4： コード オプションを選択する
［コード オプション］ページで、Delphi エンティティの命名方法を指定します。
オプションは次のとおりです。
- 基本クラス名： 前のページで、［JSON オブジェクトのマップ先］が TObject に設定されている場合に、すべての生成エンティティ型が継承するクラス名（レコードの場合には意味はありません）
- ルート オブジェクトの型名： もっとも外側の JSON オブジェクトがマップされる、最も外側の Delphi エンティティの名前
- ルート配列の型名：（省略可能）。「ルート」エンティティの配列を表す Delphi エンティティの名前。Root 配列の型名が指定されていない場合、該当する Delphi エンティティ型は生成されません。指定されている場合は、エンティティが次のように生成されます。ここでは、単一の Dataset プロパティです：
[JsonSerialize(jmFields)] TDataArray = class(TPersistent) private FDataset: TArray<TData>; public destructor Destroy; override; property Dataset: TArray<TData> read FDataset write FDataset; End;
最後に、［完了］ボタンを推して、ソース コードを生成します。
マッピング ルール
JSON データ バインディング ウィザードは、次のデータ マッピング ルールを使用します：
- JSON オブジェクトは Delphi TObject またはレコードにマップされる： 実際の型は、［JSON オブジェクトのマップ先］の設定と、Delphi レコードをサポートする JSON ライブラリの機能によって異なります（REST.Json ライブラリはレコードをサポートしていません）。
- JSON 配列は Delphi TList<T> または TArray<T> にマップされる： 実際の型は、［JSON 配列のマップ先］の設定と、JSON 配列から直接 Delphi TList<T> をデシリアライズ/シリアライズする JSON ライブラリの機能によって異なります。REST.Json ライブラリは TList<T> をサポートしていません。JSON 配列の代わりに、入れ子配列を持つ JSON オブジェクトにマップされます。
- JSON オブジェクト メンバーは Delphi フィールドまたはプロパティにマップされる： 実際のタイプは、［JSON メンバーのマップ先］および［JSON オブジェクトのマップ先］の設定によって異なります。プロパティのタイプは、レコードのタイプをサポートしていません。
- JSON オブジェクトが JSON 配列に収集されると、最大 1,000 個のオブジェクトの値を分析してフィールド/プロパティのタイプが推測されます。ウィザードは、日付と時刻の値、TGUID、ブール値などを具体的に処理できます。
- フィールド/プロパティの名前は、JSON メンバー名が有効な Delphi 識別子である場合、JSON メンバー名と同じになります。そうでなければ、名前は有効な識別子になるように「変更」されます。さらに、フィールドには「F」文字が接頭辞として付きます。
- ウィザードは、選択された JSON ライブラリの「バインディング」を行います。これには次の 3 つの要素が含まれます：
- 各 TObject またはレコード型に属性を 1 つ追加し、どのメンバーがシリアライゼーションに使用されるかを指定します。例：
[JsonSerialize(jmAllPubProps)] TCustomer = class(TPersistent)
- TObject またはレコードの型名が JSON メンバー名と異なる場合、属性を追加します：例：
[JsonName('label')] property label_: string read Flabel_ write Flabel_;
- 上記の属性が宣言されているライブラリ ユニットを、生成されたユニットの uses 句に追加します。例：
uses System.Classes, REST.Json.Types;
生成された型の使用方法
生成された Delphi 型は、ウィザードで選択された JSON ライブラリと使用できます。追加の変更は必要ありません。ライブラリ マッピングを変更する必要がある場合、ウィザードを再度実行し、必要なライブラリを選択することをお勧めします。
たとえば、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);
ここでの他の選択肢は、System.JSON.TJSONMapper ジェネリック クラスを使用することです。これは、既存の JSON ライブラリのシン ラッパーです。これは、最も一般的な JSON シリアライゼーション/デシリアライゼーション処理のための、簡略化された API を提供します。ただし、ライブラリによって提供される、オプションや補足的な特殊 API は隠ぺいします。
例：
// 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);
詳細については、System.JSON.TJSONMappers を参照してください。