サービスのリクエスターに対して使用可能なファイルで、EGL インターフェース・パーツを定義します。インターフェース・パーツは、同じ EGL パッケージ内に存在しているか、別のパッケージからインポートできます。
EGL インターフェース・パーツには、1 つ以上の関数プロトタイプ が含まれています。関数プロトタイプは、特定のサービス操作にアクセスするためのコードの記述方法の説明です。関数プロトタイプには、操作名、パラメーター (ある場合)、および戻りの型 (ある場合) が含まれています。プロトタイプには、サービスでのみ使用可能な操作のロジックは含まれていません。
EGL REST-RPC サービスのインターフェース・パーツは、サード・パーティー REST サービスのインターフェース・パーツよりも単純です。
EGL REST-RPC サービスにアクセスするためのインターフェース・パーツ
以下の例で、EGL REST-RPC サービスにアクセスするためのインターフェース・パーツを示します。以下の例には、1 つの関数プロトタイプが含まれています。
Interface EmployeeService
Function GetEmployeeDetail(employeeCode STRING IN,
employeeSalary FLOAT OUT,
employeeStatus STRING INOUT)
returns(myEmployeeRecordPart);
end
さまざまな EGL データ型を指定でき、修飾子 IN、OUT、および INOUT を使用できます。
インターフェース・パーツを作成するには、以下のステップを実行します。
- 「プロジェクト・エクスプローラー」ビューで、サービスを定義する EGL ファイルを右クリックします。
- をクリックします。
- 「新規 EGL インターフェース・パーツ」ウィンドウで適切な詳細を指定して、「完了」をクリックします。
サード・パーティーの REST サービスにアクセスするためのインターフェース・パーツ
サード・パーティーの REST サービスにアクセスするためのインターフェース・パーツの例を以下に示します。
Interface WeatherForecast
Function GetWeatherByZipCode(zipcode string in) returns(myRecordPart)
{@GetRest{uriTemplate="/GetWeatherByZipCode?zipCode={zipcode}",
requestFormat = JSON,
responseFormat = JSON}};
end
インターフェース・パーツの目的が、(EGL REST-RPC サービスではなく) サード・パーティーの REST サービスで使用可能な操作を記述することである場合は、関数プロトタイプごとに複合プロパティーを指定する必要があります。このプロパティーの名前は、サービスのアクセスに使用される HTTP verb を示します。
- GET メソッドの場合、このプロパティー名は @GetREST です。
- POST メソッドの場合、このプロパティー名は @PostREST です。
- PUT メソッドの場合、このプロパティー名は @PutREST です。
- DELETE メソッドの場合、このプロパティー名は @DeleteREST です。
これらの複合プロパティーは@xREST プロパティーと呼ばれます。これは、これらの複合プロパティーには 3 つの同じプロパティー・フィールドがあるためです。これについては、このトピックの @xREST プロパティーのセクションで説明します。
サード・パーティーの REST サービスにアクセスするために使用されるサービス呼び出し文では、特定の関数パラメーターに渡される引数には、以下の 2 つの目的の 1 つがあります。
- 通常、引数は、リクエスターが URI に含める値を提供します。この使用法については、このトピックの @xREST プロパティーの説明で解説します。これらの値は、サービス・ロジックには渡されません。これらは、URI に組み込まれた値です。特に、プロパティーが@GetREST の場合、関数パラメーターに割り当てられるすべての引数を使用して URI が構成されます。
- 引数が (最大で) 1 つの場合は、その引数は、サービスによって処理される表現です。例えば、データベース表の行の作成に使用される値を含むレコードなどです。以下に詳細を示します。
- 特定の操作のプロパティーが @PostREST または @PutREST である場合は、追加の引数が存在する必要があり、関連するパラメーターは表現パラメーター と呼ばれます。
- プロパティーが @DeleteREST の場合にもこの引数が必要となることがあります。
この引数の必要性は、サービス・プロバイダーによって異なります。
uriTemplate プロパティー・フィールド (
@PostREST、
@PutREST、または
@DeleteREST が対象) で識別されていないパラメーターが関数プロトタイプにある場合、そのパラメーターは表現パラメーターです。以下のケースはいずれもエラーです。
- 表現パラメーターを複数指定
- @GetREST を使用しているときに表現パラメーターを指定
サービスに送信される引数に関する制約については、『サービス・アクセスのプロトタイプ』を参照してください。
インターフェース・パーツを作成する必要はありません。代わりに、IRest を使用できます。これは、ユーザーのために用意されているインターフェース・パーツであり、サード・パーティーの REST サービスにアクセスするために使用される変数の基礎にすることができます。このインターフェース・パーツについて詳しくは、『サード・パーティーの REST サービスにアクセスするためのインターフェース・パーツ』を参照してください。
サード・パーティーの REST サービスに使用される @xREST プロパティー
それぞれの @xREST 複合プロパティーに、uriTemplate、requestFormat、および responseFormat の各フィールドがあります。
- uriTemplate
- ほとんどの場合、相対 URI の概要を示すストリングまたはテンプレート。これは、サービスにアクセスするために使用される URI 内の最後の修飾子を識別します。背景情報については、『開発者向けの REST の概要』を参照してください。
最初の URI 修飾子であるベース URI は、以下の 3 つの方法のうちの 1 つで指定されます。
- インターフェース・パーツに基づく変数を宣言する場合は、ベース URI を設定できます。この場合は、ベース URI は開発時に設定され、構成時または実行時には変更できません。この使用法は単純かつ迅速ですが、柔軟性はありません。
- または、インターフェース・パーツに基づく変数を宣言する場合は、デプロイメント記述子で項目を識別できます。この場合は、ベース URI の初期値はデプロイメント記述子内にあり、構成時にコード・インストーラーでその値を変更できます。
- 初期値の指定方法に関係なく、実行時にベース URI の値を変更するには、serviceLib.setServiceLocation 関数を実行します。
ベース URI を設定しない場合は、uriTemplate プロパティー・フィールドの値には、完全な URI が含まれています。ほとんどの場合、uriTemplate プロパティーの値には、以下の 2 つの側面があります。
- uriTemplate プロパティーの値には、定数値を含めることができます。それらの文字は、関数にアクセスするために使用されるすべての URI 内または後に提示されます。前の例では、uriTemplate の値には照会変数が含まれており、定数値は以下のようになります。
/GetWeatherByZip?zipcode=
照会ストリングの代わりにパス変数を含めるように例を変更すると、定数値は以下のようになります。
/GetWeatherByZip/
- uriTemplate プロパティーの値には、パス変数と照会変数を含めることができます。前の例には、以下の単一の照会変数が含まれています。
{zipcode}
照会ストリングを使用した元の例では、サービスにアクセスするために使用される相対 URI と値は以下のとおりです。
/GetWeatherByZip?zipcode=02135
テンプレートが照会ストリングの代わりにパス変数を含む場合は、相対 URI は以下のとおりです。
/GetWeatherByZip/02135
EGL ランタイム・コードは、サービス呼び出しステートメントに指定されている各置換値に対して URI エンコードを自動的に実行しますが、例外が 1 つあります。
例えば、特定の置換変数の値が「Jeff Smith」であることをサービス呼び出し文が示している場合は、EGL ランタイム・コードは、URI が有効になるようにストリングを「Jeff%20Smith」に変換します。ただし、置換値の値が http で始まる場合は、サービス呼び出し文は完全な URI を提供する引数を指定しているため、EGL ランタイム・コードは URI のエンコードを行いません。URI のエンコードを行う必要がある場合は、 serviceLib.convertToURLEncoded システム関数に関する資料を参照してください。
uriTemplate フィールドのデフォルト値は空ストリングであるため、デフォルトでは、ベース URI を設定して完全な URI を指定できます。
- requestFormat
- サービスに送信される表現のフォーマットを示す値。
- XML。フォーマットが Extensible Markup Language であることを示します。
- NONE。表現はストリング (またはストリングと互換性がある値) であり、現状のまま送信されることを示します。
- JSON。フォーマットが JavaScript Object Notation であることを示します。
- FORM。フォーマットが、引数と値のペアで構成されるレコードであるフォーム・データであることを示します。サービスに送信される内容に関する次の例では、各ペアはアンパーサンド (&) で次の引数と分離されています。
division=Consumer&dept=Sales
フォーム・データの基礎であるレコード・パーツ内の特定のフィールド
の場合は、
FormName プロパティーを指定できます。このプロパティーを使用すると、EGL の予約語であったり、EGL では無効であったりする引数名を処理できます。以下に、
FormName プロパティーの使用例を示します。
record anyRecord
continue boolean {FormName="continue-content"};
end
このランタイム・コードでは、
FormName プロパティーの値を、サービスに送信される引数の名前として使用しています。サービスに送信される表現は次のようになります。
continue-content=yes
FormName プロパティーのデフォルト値は、レコード・フィールドの名前です。この例では、デフォルトは、continue です。
レコード・パーツに基づいたレコードを宣言するときに、FormName プロパティーの値をオーバーライドすることはできません。
表現がレコードである場合は、以下の記述が適用されます。
- requestFormat のデフォルト値は XML です。
- JSON も有効です。
- FORM は、レコード内のすべてのフィールドの型が、STRING であるか、STRING との代入互換性がある型である場合に限り有効です。レコードが別のレコードを参照している場合は、FORM は有効ではありません。
- responseFormat
- リクエスターに戻される表現のフォーマットを示す値。
- XML。戻される表現が XML フォーマットであることを示します。
- NONE。戻される表現がストリングであることを示します。
- JSON。戻される表現が JSON フォーマットであることを示します。
インターフェース・パーツの関数プロトタイプ内の戻り値がストリング (またはストリングと互換性がある値) である場合は、responseFormat のデフォルト値は、唯一の有効なフォーマットである NONE です。戻り値がレコードである場合は、responseFormat のデフォルト値は XML で、JSON も有効です。
プロパティー・フィールドに値を割り当てることなく
@xREST プロパティーを指定できます。
Interface IEmployeeService
Function GetEmployeeDetail() returns(myRecordPart)
{@GetRest{}};
end
プロパティー・フィールドがない場合は、以下のようになります。
- インターフェース・パーツの詳細を指定せずに、完全な REST サービス URI (http://www.ibm.com/myservice など) を指定する必要があります。ベース URI を指定するための 3 つの選択項目については、このトピックの uriTemplate の説明を参照してください。
- 表現パラメーター (または、@GetREST プロパティーの場合は戻り値) がストリングである場合は、EGL ランタイム・コードは変換を行いません。変換を処理する必要があります。また、そのためには、以下のいずれかの関数を使用できます。
- serviceLib.convertFromJSON
- serviceLib.convertToJSON
- XMLLib.convertFromXML
- XMLLib.convertToXML
- 表現パラメーターがレコードである場合は、EGL ランタイム・コードは、関連する引数を Extensible Markup Language (XML) フォーマットに変換します。
- @GetREST プロパティーでは、戻り値がレコードである場合は、EGL ランタイム・コードはレコードを XML フォーマットから変換します。
.