DataSet Serializeのクィックスタート

提供: Support
移動先: 案内、 検索

対象となるIDEのバージョン

  • Delphi XE3 〜 10.3 Rio

サポートプラットホーム

  • Win32, Win64


このドキュメントは、DataSet SerializeのReadmeの抄訳です。

DataSet Serializeとは

「DataSet Serialize」は、Delphi向けのJSONとDataSetを簡単に扱うための機能セットです。

  • レコードをDataSetへインポート/エクスポート
  • JSONデータ(必要な属性を含む)の検証
  • DataSetをJSON形式にエクスポート/インポート
  • マスター/詳細またはTDataSetFieldを使用してネストされたJSONを管理

などの機能があります。

これらはすべてクラスヘルパーを使用しているため、さらにシンプルで使いやすくなっています。

DataSet Serializeのインストール

  1. GitHubにホストされてるhttps://github.com/viniciussanchez/dataset-serializeのサイトからダウンロード
  2. ダウンロードしたdataset-serialize-master.zipファイルを任意のパスへ展開
  3. IDEメニューの[プロジェクト] > [オプション] > [ビルド] > [Delphiコンパイラ] の”検索パス”にdataset-serialize-masterを展開したsrc(ソースコード)フォルダのパスを追加する
    Thumb03000273ujpn.png


別のプロジェクトでDataSet Serializeのライブラリを有効にしたい場合は、IDEメニューの[ツール] > [オプション] > [言語] > [Delphi] > [ライブラリ]の"ライブラリパス"に手順3と同様にsrcフォルダを追加してください。


DataSet Serializeを利用するには

DataSet Serializeが提供するすべての機能は、DataSet.Serializeユニットのクラスヘルパにあります。プロジェクトで利用するためには、以下の例のようにuses句にユニットを追加してください。 

uses DataSet.Serialize;

自身のプロジェクトコードにDataSet.Serializeユニットを定義することで、以下のようなヘルパーメソッドが利用できます。

  • ToJSONObject
  • ToJSONArray
  • LoadStructure
  • SaveStructure
  • ValidateJSON
  • LoadFromJSON
  • MergeFromJSONObject

など


それでは、DataSet.Serializeの各機能のルールや特徴について詳しく見ていきましょう。


DataSetからJSONへの変換

Delphiで標準提供しているJSONに関連したクラスライブラリは、バージョンアップを重ねるごとにヘルパーやユーティリティクラスが追加され、より使いやすくなっているため自前でDataSetをJSON形式に変換する方法もありますが、DataSet Serializeを利用すると、DataSetレコード情報からJSONオブジェクトを作成する作業がもっと簡単に行えます。 また変換できるデータセットの種類には、もともとJSON変換をサポートしているFireDAC以外にも、dbExpress、IBExpressなどのデータベースフレームワークや、TClientDataSetのような従来のデータセットにも対応しています。

DataSet Serializeには、このためにToJSONObjectとToJSONArrayという2つの関数が用意されています。この関数の使い方を見てみましょう。 

var
  LJSONArray: TJSONArray;
  LJSONObject: TJSONObject;  
begin
  LJSONObject := qrySamples.ToJSONObject(); // export a single record
  LJSONArray := qrySamples.ToJSONArray(); // export all records 
end;

この2つの関数の違いは何ですか？


ToJSONObjectは、DataSetの現在のレコードのみをTJSONObjectに変換し、ToJSONArrayは、選択されたレコードだけでなく、DataSetのすべてのレコードをTJSONArrayに変換します。


ToJSONObject関数

function ToJSONObject(const AOnlyUpdatedRecords: Boolean = False; const AChildRecords: Boolean = True): TJSONObject;
パラメータ名 説明
AChildRecords （Master DetailまたはTDataSetField経由で）子レコードをエクスポートするかどうかを示します。
AOnlyUpdatedRecords 変更されたレコード（追加、変更、または削除されたレコード）のみをエクスポートするかどうかを示します。 この機能は、FireDACを使用している場合にのみ使用可能で、CachedUpdatesプロパティはTrueである必要があります。

す。


ToJSONObjectの仕様は、以下の通りです。


  • データセットが空、あるいは未割り当ての場合は、空のJSON Object（{}）を返します。
  • VisibleプロパティがTrue以外のフィールドは無視されます。
  • JSONの属性名は、フィールド名が大文字であっても、常に小文字のフィールド名になります。
  • フィールドのタイプがTDataSetFieldの場合、ネストされたJSONが生成されます（子レコードの場合はJSONObject、複数の場合はJSONArray）。 このタイプの状況に最も適した方法は、マスター/詳細を作成することです。
  • すべての子レコードはJSONArrayとしてエクスポートされます。
  • ToJSONObjectまたはToJSONArrayメソッドのAOnlyUpdatedRecordsパラメータを使用すると、JSON項目が「object_state」プロパティに追加され、レコードに何が起こったか（削除、包含、または変更）を定義します。
  • マスター/詳細を使用してネストされたJSONを表現するためにJSON配列を作成すると、DataSet名が生成されたJSONの属性名になります。 例えば、DataSet名がqry（クエリ）またはmt（memtable）で始まる場合、これらのイニシャルは無視され、残りの部分だけがJSONの属性名になるというルールがあります。


ToJSONArray関数

function ToJSONArray(const AOnlyUpdatedRecords: Boolean = False; const AChildRecords: Boolean = True): TJSONArray;
パラメータ名 説明
AChildRecords （マスター/詳細またはTDataSetField経由で）子レコードをエクスポートするかどうかを示します。
AOnlyUpdatedRecords 　変更されたレコード（追加、変更、または削除されたレコード）のみをエクスポートするかどうかを示します。 この機能は、FireDACを使用している場合にのみ使用可能で、CachedUpdatesプロパティはTrueである必要があります。

す。


ToJSONArrayの仕様は、以下の通りです。


  • データセットが空、あるいは未割り当ての場合は、空のJSON Array（{}）を返します。
  • 基本的にToJSONArrayもToJSONObjectと同じルールに従います。


データ構造の読み込みと保存

あまり便利ではありませんが、重要な機能としてSaveStructureとLoadStructureがあります。名前からもわかるように、DataSetに設定されたフィールドの構造全体を保存したり、JSON形式の構造をロードすることができます。ここでは、DataSetフィールドのロードとエクスポートの例を紹介します。 

var
  LJSONArray: TJSONArray;
begin
  LJSONArray := qrySamples.SaveStructure;
  qrySamples.LoadStructure(LJSONArray, True);
end;

SaveStructureとLoadStructure関数を実行すると、以下のようなDataSetのTFieldプロパティが制御されます。 

Alignment, FieldName, DisplayLabel, DataType, Size, Key, Origin, Required, Visible, ReadOnly, AutoGenerateValue

LoadStructure関数

procedure LoadStructure(const AJSONArray: TJSONArray; const AOwns: Boolean = True);
パラメータ名 説明
AOwns パラメータとして渡されたJSONを破棄する責任者(オーナー)を指定


この関数を呼び出す前にはDataSetをアクティブ化せず、フィールドを定義しないでください。

SaveStructure関数

function SaveStructure: TJSONArray;

DataSetのフィールド数がゼロの場合、空白のJSON Array（[]）を返します。


JSONの検証

ValidateJSON関数は、リクエストで受け取ったJSONに必要な情報がすべて含まれているかどうかをサーバー上で検証したい場合などに非常に便利です。実際には、データセットのすべてのフィールドが走査され、必要なフィールドがJSONで入力されているかどうかがチェックされます。フィールドが必須で、JSONに入力されていない場合、関数によって返されるJSON Arrayに追加されます。以下の例をご覧ください。 

begin
  LJSONArray := qrySamples.ValidateJSON('{"country":"Brazil"}');
end;


{"country": "Brazil"}を受信した場合、DataSetに3つのフィールド（ID, FIRST_NAME, COUNTRY）があり、IDとFIRST_NAMEフィールドが必須であると仮定すると、以下のように返されます。 

[{"field":"id","error":"Id not informed"},{"field":"firstName","error":"Name not informed"}]


ValidateJSON関数

function ValidateJSON(const AJSONObject: TJSONObject; const ALang: TLanguageType = enUS; const AOwns: Boolean = True): TJSONArray;
パラメータ名 説明
ALang メッセージの組み立てに使用する言語の変更(デフォルトは英語)
AOwns パラメータとして渡されたJSONを破棄する責任者(オーナー)を指定


ValidateJSONの仕様は、以下の通りです。


  • JSONが割り当てられていない場合や、フィールド数が0の場合は、例外が発生します。
  • メッセージのデフォルト言語は英語
  • すべての必須フィールドが入力された場合でも、空のJSON Array（[]）が返されます。
  • 必須フィールドは、Required プロパティが True である必要があります。
  • DisplayLabelプロパティを使用して、メッセージのカスタマイズが可能。


JSONからの読み込み

DataSet Serializeでは、LoadFromJSON関数を使用してJSONObject、JSONArray、さらにはネストしたJSONを持つDataSetを1つのメソッドにまとめてロードすることができます。使用方法の例は、以下の通りです。 

begin
  qrySamples.LoadFromJSON('{"firstName":"Vinicius Sanchez","country":"Brazil"}');
end;

LoadFromJSON関数

procedure LoadFromJSON(const AJSONObject: TJSONObject; const AOwns: Boolean = True); overload;
procedure LoadFromJSON(const AJSONArray: TJSONArray; const AOwns: Boolean = True); overload;
パラメータ名 説明
AOwns パラメータとして渡されたJSONを破棄する責任者(オーナー)を指定


LoadFromJSONの仕様は、以下の通りです。


  • JSONまたはDataSetが未割り当ての場合は、何も実行されません。
  • DataSetがアクティブ化されておらず、TFDMemTableクラスでない場合、何も実行されません。
  • DataSetのタイプがTFDMemTableで、アクティブではなく、フィールド数が0の場合、JSONの必要性に応じてフィールドが作成されます。DataTypeはftStringで、Sizeは4096になります。
  • object_state "プロパティがJSONの場合、以下のような検証が行われます。
    INSERTEDと等しい場合、DataSetにAppendが実行されます。
    MODIFIEDまたはDELETEDの場合は、操作対象のレコードを探すためにDataSet内でLocateが行われます。レジストリが見つからない場合は、何も行われません。Locateを実行するために、JSON内でKey Fieldsの検索が行われます。
    MODIFIEDがDataSetのEditメソッドに等しい場合。
    DELETEDがDataSetのDeleteメソッドに等しい場合。
  • JSONに "object_state "プロパティが見つからない場合は、Appendメソッドが呼び出されます。
  • JSONでDataSetを読み込むときに、ReadOnlyまたはVisible(False)のフィールドは無視されます。
  • フィールド名を持つ属性がJSONに見つからない場合（大文字/小文字の区別は無し）、またはnullである場合、そのフィールドは無視されます（null / empty)
  • マスター/詳細を使用してネストされたJSONを含むDataSetをロードする場合、慣例により、子DataSetの名前は、子DataSetの名前は、ロードされる子のリストを表すJSON属性名と同じであると想定されます。子DataSetの名前にqry(query)やmt(memtable)のイニシャルが付いていても、それらは無視されます。


JSONからの結合

DataSet Serializeでは、MergeFromJSONObject関数を使用するだけで、DataSetの登録を変更することができます。この機能はLoadFromJSON関数と似ています。使用例としては、リクエストで使用される動詞がPUT（必ずしもそうではない）の場合のRESTサーバーで、この場合、新しいレコードを含めるのではなく、現在のレコードを変更します。 

begin
  qrySamples.MergeFromJSONObject('{"firstName":"Vinicius","country":"United States"}');
end;


MergeFromJSONObject関数

procedure MergeFromJSONObject(const AJSONObject: TJSONObject; const AOwns: Boolean = True); overload;
パラメータ名 説明
AOwns パラメータとして渡されたJSONを破棄する責任者(オーナー)を指定

MergeFromJSONObject関数は、LoadFromJSON関数の検証と同じ仕様です。


コンフィグレーション

DataSet Serializeの一部の機能についてはカスタマイズ可能です。

  • Date input is UTC (タイムゾーン) 
    TDataSetSerializeConfig.GetInstance.DateInputIsUTC := True;
  • null値のエクスポート 
    TDataSetSerializeConfig.GetInstance.Export.ExportNullValues := True;
  • エクスポートしたフィールドのみを表示 
     
TDataSetSerializeConfig.GetInstance.Export.ExportOnlyFieldsVisible := True;
  • 子データセットをJSONオブジェクトとしてエクスポートする（1レコードのみの場合 
    TDataSetSerializeConfig.GetInstance.Export.ExportChildDataSetAsJsonObject := False;
  • インポートのみのフィールドを表示 
    TDataSetSerializeConfig.GetInstance.Import.ImportOnlyFieldsVisible := True;
  • キャメルケースの定義 
    // cndNone, cndLower, cndUpper, cndLowerCamelCase
TDataSetSerializeConfig.GetInstance.CaseNameDefinition := cndLowerCamelCase;
  • 日付フォーマット（エクスポート時のフィールドタイプはftDateに相当) 
    TDataSetSerializeConfig.GetInstance.Export.FormatDate := 'YYYY-MM-DD';
  • 通貨型フォーマット (エクスポート時のフィールドタイプはftCurrencyに相当) 
    TDataSetSerializeConfig.GetInstance.Export.FormatCurrency := '0.00##';
  • データセットの接頭辞の定義 
    TDataSetSerializeConfig.GetInstance.DataSetPrefix := ['mt', 'qry'];

サンプルプログラム

DataSet Serializeでは、サンプルプログラムが提供れています。上記で紹介した各機能については、サンプルプログラムを実際に実行し、確認してみてください。

Thumb03000274ujpn.png

DataSet Serializeについて

DataSet Serializeは、オープンソースプロジェクトで、ライセンス規約はこちらを参照ください。このプロジェクトは、多くの素晴らしいcontributorsによって維持されています。なお、エンバカデロではこの製品に関するテクニカルサポートサービスは提供しておりません。

「https://docwiki.embarcadero.com/Support/j/index.php?title=DataSet_Serializeのクィックスタート&oldid=2368」から取得