RAD サーバーリソースの概要

EMS リソースは、EMS サーバー API を拡張するものです。

EMS リソースを EMS サーバーに読み込むと、EMS サーバーはそれを登録し、そのすべてのエンドポイントを公開します。EMS クライアントアプリケーションは、TBackendEndpoint コンポーネントを使って、EMS リソースのエンドポイントにアクセスすることができます。

メモ： EMS リソースを定義する前に、その定義を含める EMS パッケージを作成してください。

1 リソースクラスの定義
- 1.1 リソースクラスの宣言
- 1.2 リソース名
2 エンドポイントメソッドの定義
3 リソースのマッピングのカスタマイズ
- 3.1 リソース属性オブジェクトの定義
- 3.2 属性を使用したリソースのマッピングのカスタマイズ（Delphi）
4 リソースの登録
- 4.1 リソース属性オブジェクトを使ったリソースの登録
5 関連項目

リソースクラスの定義

リソースクラスとは、EMS リソースを表すクラスです。

リソースクラスの宣言

リソースクラスは通常のクラスとして宣言することができます。以下に例を示します。

Delphi の場合：

TMyResource = class;

C++ の場合：

// .h
class TMyResource {};

リソースクラスには、以下のいずれかに該当する少なくとも 1 つのコンストラクタが必要です。

パラメータのないコンストラクタ
TComponent 型の 1 つのパラメータを受け取るコンストラクタ

リソース名

EMS リソースごとに、そのリソースを一意に識別するリソース名があります。EMS クライアントアプリケーションからリソースにアクセスするには、TBackendEndpoint コンポーネントの Resource プロパティに対象リソースの名前を設定する必要があります。

デフォルトでは、クラスが表す EMS リソースの名前は、クラス名からプレフィックスの "T" を取り除いたもの（付いていれば）です。たとえば、上記クラスのリソース名は "MyResource" になります。EMS リソースに異なる名前を付けたい場合は、後でカスタマイズすることができます。

エンドポイントメソッドの定義

リソースクラスを定義したら、次に、そのクラスにエンドポイントメソッドを追加します。

エンドポイントメソッドとは、そのメソッドが定義されたリソースに対する API 要求を処理するメソッドです。

API 要求では、"GET" などの要求メソッド（必須）と、リソースサフィックス（任意）を指定します。リソースクラスの各エンドポイントメソッドは、要求メソッドとリソースサフィックスの 1 つの組み合わせを処理するものでなければなりません。

エンドポイントメソッドで処理可能な要求を EMS サーバーが受け取ると、以下の処理が行われます。

EMS サーバーがエンドポイントメソッドを実行します。
エンドポイントメソッドが応答を生成します。
生成された応答を、EMS サーバーが、元の要求を送信したクライアントアプリケーションに送り返します。

エンドポイントメソッドの宣言

エンドポイントメソッドを宣言するには、以下の要件を満たすメソッドをリソースクラス内に宣言しなければなりません。

public または published の可視性で宣言されている
要求メソッドの名前（Get、Put、Post、Delete、Patch）と一致する文字列で名前が始まっている
Get、PutItem、PostWhateverYouWant は、いずれもエンドポイントメソッド名として有効です。プレフィックスの大文字/小文字はどちらでもかまいません。たとえば Get、get、GET はどれも、エンドポイントメソッド名の有効なプレフィックスです。
シグネチャは、戻り値を持たず、TEndpointContext、TEndpointRequest、TEndpointResponse の 3 つのパラメータだけをこの順で受け取る

Delphi の場合：

procedure MethodName(const AContext: TEndpointContext; const ARequest: TEndpointRequest; const AResponse: TEndpointResponse);

C++ の場合：

void MethodName(TEndpointContext* AContext, TEndpointRequest* ARequest, TEndpointResponse* AResponse);

リソースクラスのメソッドが上記の要件をすべて満たさない場合、EMS サーバーはそのメソッドには API エンドポイントをマッピングしません。

エンドポイントメソッドの実装

エンドポイントメソッドの実装では、受け取った TEndpointResponse のインスタンスにデータを設定しなければなりません。これは通常、JSON データです。TEndpointResponse の Body プロパティの SetValue メソッドを使って応答に JSON データを設定するか、SetBytes または SetStream を使ってデータをそのまま応答本体に書き込むことができます。

「チュートリアル：初めての EMS リソースを実装する」に簡単な例がありますので参照してください。

要求メソッド

エンドポイントメソッドの名前は、そのエンドポイントメソッドが処理する要求メソッドの名前で始まります。つまり、1 つのエンドポイントメソッドで複数の異なる要求メソッドを処理することはできません。

EMS サーバー API では以下の種類の要求メソッドをサポートしています。

名前	説明
GET	データを取得します。
PUT	新しい項目を作成してその ID を取得します。
POST	既存の項目を新しいデータで置き換えます。
PATCH	既存の項目のデータの一部を更新します。
DELETE	項目を削除します。

リソースサフィックス

リソースサフィックスとは、エンドポイント URL の末尾、リソース名の直後にくる文字列で、小文字で記述します。たとえば、エンドポイントにアクセスする URL が http://example.com/ems/myresource/item/count で、リソース名が "MyResource" であれば、そのエンドポイントのリソースサフィックスは "item/count"（または "/item/count"）です。

各エンドポイントメソッドは、特定のリソースサフィックスにマッピングされます。EMS クライアントアプリケーションからリソースにアクセスするには、TBackendEndpoint コンポーネントの ResourceSuffix プロパティにリソースサフィックス文字列を設定する必要があります。

デフォルトでは、エンドポイントメソッドのリソースサフィックスは空文字列です。異なるリソースサフィックスをエンドポイントメソッドに割り当てるには、後でエンドポイントメソッドのマッピングをカスタマイズする必要があります。

リソースサフィックスは、必ず、リソース自体の URL からの相対パスで指定します。スラッシュ（/）で始まるリソースサフィックスをエンドポイントメソッドに割り当てると、最初のスラッシュは EMS サーバーによって無視されます。たとえば、"/item/count" と "item/count" はどちらも、http://example.com/ems/myresource/item/count などの同じエンドポイント URL を指す有効なリソースサフィックスです。

リソースサフィックスに使用できる特別なセグメント

セグメントとは、スラッシュ以外の文字を含む文字列です。リソースサフィックスは、スラッシュで区切られた複数のセグメントで構成することができます。たとえば、"item/count" には、"item" および "count" という 2 つのセグメントが含まれています。

リソースサフィックスでは、以下の特別なセグメントをサポートしています。

セグメント	説明
`*`	任意のセグメントと一致します。たとえば、"*/count" というリソースサフィックスは、"foo/count" や "bar/count" と一致します。
`{<識別子>}`	この <識別子> は、"item" や "key" など任意の識別子でかまいません。任意のセグメントに一致します。一致したセグメントは、識別子をキー、要求 URL 内の実際の文字列を値として TEndpointRequest.Params プロパティに格納されます。たとえば、"{item}/bar" というリソースサフィックスは "foo/bar" と一致し、TEndpointRequest.Params プロパティに `item=foo` というペアが格納されます。

メモ： これらの特別なセグメントは、それ自体が 1 つのセグメントとして完結した形でしか使用できません。"foo*/bar" や "{foo}bar/count" などのリソースサフィックスは、EMS サーバーによって、特別なセグメントではなく、"foo*" や "{foo}bar" のような通常の文字列として解釈されます。

エンドポイント名

エンドポイントの名前は、EMS コンソール UI 上でそのエンドポイントを表す表示用の文字列です。

デフォルトでは、エンドポイントメソッドが表すエンドポイントの名前は、そのメソッドの名前になります。エンドポイントに異なる名前を付けたい場合は、後でカスタマイズすることができます。

エンドポイント名はリソース内で一意でなければなりません。2 つの異なるエンドポイントメソッドに同じエンドポイント名を付けると、EMS サーバーは後で見つかったエンドポイント名の末尾に数値を追加して一意の名前にします。たとえば、エンドポイントメソッドが 2 つあるときに、マッピングを変更した結果、両方のエンドポイント名が "MyEndpoint" になると、最初のエンドポイントメソッドは元のエンドポイント名のままですが、2 番目のエンドポイントメソッドの名前は "MyEndpoint2" になります。

リソースのマッピングのカスタマイズ

リソースクラスを EMS サーバーに登録する前に、リソースクラスおよびエンドポイントメソッドを EMS サーバー API にどうマッピングするかを変更することができます。

リソース名、リソースサフィックス、エンドポイント名を変更できます。ただし、要求メソッドは変更できません。これは常に、エンドポイントメソッド名のプレフィックスで定義されます。

リソースのマッピングをカスタマイズするには、そのリソースのリソース属性オブジェクトを定義し、リソースの登録時にそのオブジェクトを使用します。Delphi の場合は、属性を使ってリソースのマッピングをカスタマイズすることもできます。

リソース属性オブジェクトの定義

リソース属性オブジェクトは TEMSResourceAttributes のインスタンスです。

リソース属性オブジェクトを使ってリソースのマッピングをカスタマイズする手順は以下のとおりです。

TEMSResourceAttributes のインスタンスを作成します。
リソース属性オブジェクトのプロパティに、リソースで使用したいマッピングを設定します。
そのオブジェクトを、リソースの登録時に RegisterResource の第 2 パラメータに指定します。

リソースのマッピングをカスタマイズするには、TEMSResourceAttributes の以下のプロパティを使用できます。

プロパティ	説明
ResourceName	リソースの名前を指定します。
ResourceSuffix	特定のエンドポイントメソッド名に対して、そのエンドポイントメソッドのリソースサフィックスを指定します。
EndPointName	特定のエンドポイントメソッド名に対して、そのエンドポイントメソッドが表すエンドポイントの名前を指定します。

メモ： 定義するのは、変更したいマッピングデータだけでかまいません。たとえば、ResourceName の値を変更しなければ、EMS サーバーはリソースのデフォルト名（リソースクラスの名前を基に作成されたもの）を使用します。

以下に例を示します。

Delphi の場合：

// var MyResourceAttributes: TEMSResourceAttributes;
MyResourceAttributes.Create();
MyResourceAttributes.ResourceName := 'Resource';
MyResourceAttributes.ResourceSuffix['Get'] := '{item}';
MyResourceAttributes.EndPointName['Get'] := 'GetItem';

C++ の場合：

std::auto_ptr<TEMSResourceAttributes> MyResourceAttributes(new TEMSResourceAttributes());
MyResourceAttributes->ResourceName = "Resource";
MyResourceAttributes->ResourceSuffix["Get"] = "{item}";
MyResourceAttributes->EndPointName["Get"] = "GetItem";

属性を使用したリソースのマッピングのカスタマイズ（Delphi）

Delphi で、リソースクラスとエンドポイントメソッドのマッピングデータをカスタマイズするには、以下の属性を使って注釈を付けます。

メンバの種類	属性	説明
リソースクラス	ResourceName	リソースの名前を指定します。
エンドポイントメソッド	ResourceSuffix	エンドポイントメソッドのリソースサフィックスを指定します。
エンドポイントメソッド	EndpointName	エンドポイントメソッドが表しているエンドポイントの名前を指定します。

以下に例を示します。

[ResourceName('Resource')]
TMyResource = class
published
    [ResourceSuffix('{item}')]
    [EndpointName('GetItem')]
    procedure Get(const AContext: TEndpointContext; const ARequest: TEndpointRequest; const AResponse: TEndpointResponse);
end;

リソースの登録

リソースクラスとエンドポイントメソッドを定義したら、次に以下を行う必要があります。

リソースクラスを TypeInfo に渡して、リソースクラスの RTTI 情報を取得します。
リソースクラスの RTTI 情報を渡して RegisterResource を実行します。

RegisterResource はパッケージの Register メソッドで呼び出します。

以下に例を示します。

Delphi の場合：

RegisterResource(TypeInfo(TMyResource));

C++ の場合：

RegisterResource(__typeinfo(TMyResource));

リソース属性オブジェクトを使ったリソースの登録

リソースクラスおよびエンドポイントメソッドのマッピングデータをカスタマイズするためにリソース属性オブジェクトを作成した場合は、そのリソース属性オブジェクトを RegisterResource の第 2 パラメータに渡します。

以下に例を示します。

Delphi の場合：

RegisterResource(TypeInfo(TMyResource), MyResourceAttributes);

C++ の場合：

RegisterResource(__typeinfo(TMyResource), MyResourceAttributes.release());

RAD サーバーリソースの概要

目次

リソースクラスの定義

リソースクラスの宣言

リソース名

エンドポイントメソッドの定義

エンドポイントメソッドの宣言

エンドポイントメソッドの実装

要求メソッド

リソースサフィックス

リソースサフィックスに使用できる特別なセグメント

エンドポイント名

リソースのマッピングのカスタマイズ

リソース属性オブジェクトの定義

属性を使用したリソースのマッピングのカスタマイズ（Delphi）

リソースの登録

リソース属性オブジェクトを使ったリソースの登録

関連項目

案内メニュー

個人用ツール

名前空間

変種

表示

その他

検索

RAD Studio 10.4 Sydney

RAD Studio 10.4 トピック

他言語版

以前のバージョン

Assistance

ツール

RAD サーバー リソースの概要

目次

リソース クラスの定義

リソース クラスの宣言

リソース名

エンドポイント メソッドの定義

エンドポイント メソッドの宣言

エンドポイント メソッドの実装

要求メソッド

リソース サフィックス

リソース サフィックスに使用できる特別なセグメント

エンドポイント名

リソースのマッピングのカスタマイズ

リソース属性オブジェクトの定義

属性を使用したリソースのマッピングのカスタマイズ（Delphi）

リソースの登録

リソース属性オブジェクトを使ったリソースの登録

関連項目

案内メニュー

検索

RAD サーバーリソースの概要

リソースクラスの定義

リソースクラスの宣言

エンドポイントメソッドの定義

エンドポイントメソッドの宣言

エンドポイントメソッドの実装

リソースサフィックス

リソースサフィックスに使用できる特別なセグメント