インバウンドREST Webサービス

HTTPメソッドおよびパラメータ

インバウンドREST Webサービスの操作を定義する場合、製品ではHTTPメソッドのGET、PATCH、POST、PUTおよびDELETEがサポートされています。これらの様々なHTTPメソッドの製品のサポートは、Webサービスの目的を外部に伝達する1つの手段です。ただし、REST Webサービスの実際の動作は、基礎となるスキーマ・ベースのオブジェクト(ビジネス・オブジェクト、ビジネス・サービスまたはサービス・スクリプト)の動作によって決まります。たとえば、レコードを単に取得するサービス・スクリプトを参照する操作に、HTTPメソッドのPUTを構成できます。製品ではこのタイプの相違を検出できません。構成ユーザーは、そのサービスのロジックに基づいて使用する正しいメソッドを慎重に考慮する必要があります。

ビジネス・オブジェクトを参照する操作では、トランザクション・タイプを指定する必要があります。REST構文では、実行時にトランザクション・タイプを定義することはサポートされません。この場合、トランザクション・タイプおよびHTTPメソッドに関連して、いくつかの基本的な検証チェックがあります。たとえば、GETメソッドは読取りトランザクション・タイプでのみ意味を持ちます。

さらに、パラメータを定義できます。各パラメータに対して、要素への外部参照(このパラメータが外部コール元にどのように公開されるか、およびAPI仕様でどのように定義されるか)を定義します。これらのパラメータのそれぞれが、基礎となるビジネス・オブジェクト、ビジネス・サービスまたはサービス・スクリプトからのスキーマ要素のXPathにマップされます。各パラメータに対して、パス・パラメータであるか、問合せパラメータであるかを示します。

• パス・パラメータはエンドポイントの一部であり必須のパラメータです。各パス・パラメータを、中カッコで囲んで操作のURIコンポーネントに含める必要があります。

• 問合せパラメータはオプションです。それらはエンドポイントの一部ではありませんが、疑問符の後のエンドポイントURLに含まれ、名前値のペアがその後に続きます。

サンプルURLのパス・パラメータおよび問合せパラメータの例は、次のURLの項を参照してください。

URL構成

RESTサービスのエンドポイントURLを作成する場合、完全なURLを構成する主な部分が3つあります。

• 最初の部分は環境に固有の部分です。これは、クラウドの実装と比較して、オンプレミスの実装の場合は異なります。どちらにも環境を識別するホスト、ポート、および追加コンポーネントがあります。

• 2番目の部分は、製品によって指定されたハードコード済パス、つまり/rest/apisです。

  URLのこれらの2つの部分は、置換変数F1_​REST_​BASE_​URLで定義されます。これは環境を初期化するときに定義されます。詳細は、サーバー管理ガイドを参照してください。

URLの残りの部分は、各IWSおよびその操作の構成に基づいて動的に作成されます。コンポーネントは、/ownerURIComponent/resourceCategoryURIComponent/iwsURIComponent/operationURIComponentです

• 所有者URIコンポーネントは、インバウンドREST Webサービスの所有者フラグから取得されます。特別な拡張可能参照(RESTサービスの所有者構成)により、各所有者フラグに対してこのコンポーネントが定義されます。

• 各インバウンドREST Webサービスは、リソース・カテゴリを参照する必要があります。このカテゴリは、関連Webサービスをリソースの共通カテゴリに関連付けるために使用されます。複数のIWSレコードが同じリソース・カテゴリにリンクされる場合、外部カタログでこの情報を使用して、関連するWebサービスをグループ化できます。リソース・カテゴリは拡張可能参照であり、URIコンポーネントはこのレコードの属性です。

• 各REST IWSレコードにより、このIWSレコードの外部識別子として機能するURIコンポーネントが定義されます。値は、指定の所有者フラグ内で一意である必要があります。

• 各操作で、HTTPメソッドと、オプションでURIコンポーネントを定義する必要があります。パス・パラメータを定義する場合、中カッコを使用してパス・パラメータをURIコンポーネントに含める必要があります。

どの場合も、URIコンポーネントはスラッシュ(/)で開始する必要があります。

RESTサービスのURLの動的な部分の例をいくつか次に示します。最後の例は、問合せパラメータの使用を示しています。

ペイロード書式

RESTサービスは、XMLまたはJSON書式の要求ペイロードの受信をサポートし、XMLまたはJSONでペイロードを返します。返されるデフォルトの書式は、RESTエンジン・バージョンの値によって異なります。

• バージョン2.0のサービスでは、デフォルトとしてJSON書式を想定しています。デフォルトは、application/XMLの受入れヘッダーを指定することで上書きできます。

• バージョン1.0のサービスでは、デフォルトとしてXML書式を想定しています。デフォルトは、application/JSONの受入れヘッダーを指定することで上書きできます。

JSON書式のルート・ノード

JSON書式のペイロードを含むバージョン2.0のサービスは、ペイロードの周囲にあるルート・ノードを要求で受け入れないか、応答で返しません。次に、バージョン2.0のサービスのRESTコールの応答例を示します。

{
   "batchJobId": "string",
   "requestSuccessful": "string"
}

JSON書式のペイロードを含むバージョン1.0のサービスでは、要求でルート・ノードを想定し、応答でルート・ノードを返します。次に、バージョン1.0のサービスのRESTコールの応答例を示します。

{
  "F1CnclBatJob": {
    "batchJobId": "string",
    "requestSuccessful": "string"
 }
}

インバウンドWebサービス保守ページに表示されるOpen API仕様には、仕様を表示する際のレコードのRESTエンジン・バージョンに基づいて、予期される書式が表示されます。

JSONのデータ型書式

JSON書式では、文字列は引用符で囲み、数値およびブール・データは引用符で囲みません。RESTエンジン・バージョン2.0のすべてのサービスは、この標準に従います。当初、RESTエンジン・バージョン1.0のサービスは、数値およびブール・データを文字列として誤って処理し、データを引用符で囲んで返していました。これは修正されました。

バージョン1.0のサービスのこの動作に対処した統合に対応するために、このルールの例外であるインバウンドWebサービスを識別する機能が用意されています。例外として識別されたインバウンドWebサービスでは、引き続きJSON応答で数値およびブール・データが文字列として処理されます。1つ以上のIWSレコードを例外リストに追加する手順は、次のとおりです。

• 「機能構成」に移動します。

• 機能タイプが「外部メッセージ」である既存の機能構成を探します。存在しない場合は作成します。

• オプション・タイプ「インバウンドWebサービスJSONデータ型例外」のオプションを追加します。

• オプション値で、例外であるIWSレコードを指定します。オプション・タイプには複数のオプションを追加できます。また、オプション値はカンマ区切りリストをサポートします。

外部向けスキーマ

デフォルトでは、基礎となるサービスのスキーマ(サービス・スクリプト、ビジネス・オブジェクト、ビジネス・サービスなど)もRESTインバウンドWebサービス操作のスキーマであり、その要求スキーマと応答スキーマの両方として機能します。この製品では、RESTインバウンドWebサービス(IWS)操作の明示的なスキーマを定義できるため、ユーザーは外部向けコンシューマのスキーマを調整できます。IWS操作スキーマでは、インバウンドWebサービス操作スキーマに対してのみ追加機能を定義できる特別な構成もサポートされています。

この操作スキーマでは、次の機能がサポートされています。

• 要素が要求スキーマにのみ属するか、応答スキーマにのみ属するか、両方に属する(デフォルト)か、または完全に除外されているかの宣言。これは、要求スキーマ定義と応答スキーマ定義を明確に区別するために使用されます。

• 内部要素に別の要素名を割り当てます。これにより、内部サービス要素名は、必要に応じて要素への内部参照とより厳密に一致させることができます。外部向け要素名は異なるため、スキーマがより読みやすくなります。

• 内部サービス処理に影響を与えない方法で、リンクやその他のタイプの構造標準をサポートする特殊な要素を導入します。

詳細は、「Webサービスのスキーマ・ノードおよび属性」を参照してください。

RESTサーブレットは、要求スキーマと応答スキーマを使用して、要素を内部スキーマとの間でマップします。

動的リンク

公開されたAPIに、応答で返されるデータに関連するGET操作のエンドポイントURLを含む"_​self"要素が含まれるユース・ケースがあります。さらに、応答ペイロードに外部キーが含まれる場合があり、それらのエンティティについて、応答にはそのエンティティに対するGET操作のエンドポイントURLを含む"_​link"要素が含まれます(存在する場合)。

構文は、_​self要素および_​link要素のランタイム・エンドポイントURLの作成をサポートするために、RESTインバウンドWebサービス操作スキーマで提供されます。現在の環境の詳細に基づいてURLの静的部分を動的に作成することに加えて、URLの動的部分も作成します。操作のURLコンポーネントを置き換え、パス・パラメータを置き換えます。この構文では、特定のインバウンドWebサービス操作を定義したり、メンテナンス・オブジェクトを参照することができます。システムにより実行時にメンテナンス・オブジェクトのGET操作が決定され、それに応じてURLが作成されます。

構文の例:

  <_link getOperation="mo:'TO DO ENTRY';pk1:toDoEntryId;"/>

ランタイム・エンドポイントURLの例:

  _link: "http://.../common/toDos/toDoEntries/28937296450934"

GET操作をメンテナンス・オブジェクトに関連付けて、これがエンティティのデフォルトのGET操作であることを示すことができます。メンテナンス・オブジェクト・レベルおよびビジネス・オブジェクト・レベルの「GET操作」オプションを使用して、このデフォルトを上書きできます。エンティティがビジネス・オブジェクトに関連付けられていないか、またはビジネス・オブジェクトがそのようなオプションに関連付けられていない場合は、メンテナンス・オブジェクト(存在する場合)に関連付けられた操作が使用されます。

Open API仕様のドキュメント

インバウンドWebサービスには、次のドキュメント情報が提供されます。

• 各操作の簡潔で詳細な説明。

• 個々の要素のヘルプ・テキストを提供できます。インバウンドWebサービスのすべての操作において、複数の要素間で同じテキストを共有できます。要素がヘルプ・テキストに関連付けられていない場合は、かわりに内部フィールドのラベルが使用されます。

• 操作ごとにサンプル要求およびサンプル応答のドキュメントを提供できます。

• 操作は、Open API仕様に表示される順序を制御するシーケンス番号に関連付けることができます。