| Oracle® Fusion Middleware Oracle Service Busでのサービスの開発 12c (12.2.1) E69914-01 |
|
 前 |
 次 |
この章では、Service Busプロジェクト内でバインド・コンポーネントとしてRepresentational State Transfer (REST)操作を統合する方法について説明します。また、RESTfulサービスでWSDLに相当するWeb Application Definition Language (WADL)ドキュメントについても説明します。
RESTプロキシおよびビジネス・サービスを作成できるのは、JDeveloperおよびService Busコンソールからのみです。
この章の内容は次のとおりです。
RESTは、ネットワーク・アプリケーションの設計用のアーキテクチャです。RESTfulアプリケーションでは、HTTPリクエストを使用してデータのポスト(作成および更新)、データの取得(問合せの作成など)およびデータの削除を行います。RESTは、従来のWSDLベースのWebサービスの軽量な代替機能を提供します。
Service Busでは、次のRESTサポートを提供します。
プロキシ・サービスとビジネス・サービス、およびパイプラインでのRESTサポート
外部REST APIとの統合
XML、JavaScript Object Notation (JSON), (XMLとの間の変換を含む)およびURLエンコード・データ
JDeveloperのRESTインタフェースとWSDLマッピングをモデル化するためのウィザード
ベースとなるWSDL (SOAPからREST)に基づく、または「RESTバインディング」ウィザードでのAPI指定によるWADLファイルの自動作成。
JDeveloper内からOracle RESTエンドポイントを参照および使用する機能
RESTセキュリティのためのOracle Web Service Manager (OWSM)ポリシーおよびOAuth 2ポリシーのサポート
Service Busは、Hypermedia as the Engine of Application State (HATEOAS)アプローチに従ってはいませんが、パイプラインでアクションを定義することによって、特定のHATEOAS機能をサポートします。これには次の機能が含まれます。
RESTプロキシ・サービス・レスポンスでのHTTPリンク・ヘッダーの設定
RESTビジネス・サービス・レスポンス内のHTTPリンク・ヘッダーの値の読取り
RESTビジネス・サービス・リクエストのエンドポイントURIのオーバーライド
RESTプロキシ・サービスを作成すると、これをスタンドアロンのRESTクライアントから呼び出すことができます。作成したRESTビジネス・サービスは、WSDLベースのサービスとして呼び出すことができます。
注意:
添付ファイル・コンテンツへのリンクを含むペイロードを返すことはできますが、Service Busでは、RESTでMIME添付ファイルをサポートしていません。
Service Busは、このリリースでRESTをネイティブにサポートするよう拡張されました。以前のService Busリリースでは、RESTをサポートするための仮想レイヤーを提供していました。つまり、プロキシおよびビジネス・サービスのみがRESTベースになっていました。これらのRESTサービスは、WSDLベースのパイプラインまたは分割-結合を呼び出すこともあれば、それらに呼び出されることもありました。RESTプロキシ・サービスは、パイプラインまたは分割-結合を呼び出す前にRESTネイティブ・ペイロードをSOAPに変換する一方、パイプラインまたは分割-結合によって呼び出されるRESTビジネス・サービスは、SOAPのペイロードをRESTに変換していました。内部インタフェースはWSDLベースですが、外部ビジネスおよびプロキシ・サービスはRESTエンドポイントを公開していました。このリリースでは、RESTプロキシ・サービスはRESTネイティブ・ペイロードをSOAPに変換する必要はありません。これらのペイロードはRESTベースのパイプラインで、XMLに変換、またはXMLから変換せずにネイティブに処理できます。
注意:
ネイティブRESTサービスについては、Service BusがクライアントのHTTP Acceptヘッダーに基づいて、インバウンド・レスポンスを自動的に変換することはありません。RESTバインディングを使用するとき、RESTバインディングで選択されているペイロードのタイプが1つのみでなければ、戻りペイロードはユーザーのAcceptヘッダーに基づいています。たとえば、$bodyのJSONペイロードは、インバウンド・リクエストのAccept Valueヘッダーの値に関係なく、そのまま(JSON)送信されます。パイプラインでは、nXSD変換アクションを使用して、必要に応じて手動で変換します。
このリリースのService Busでは、次の新しいネイティブRESTサービス・タイプが使用可能です。
未入力のRESTプロキシ・サービスおよびビジネス・サービス: デザイン・タイムでメソッド(操作)情報が通知されない可能性のあるサービス。
入力済RESTプロキシ・サービスおよびビジネス・サービス: デザイン・タイムでメソッド(操作)情報が通知されるサービス。これらのサービスのメソッド情報は、WADLファイルに定義されます。サービスを作成する場合、WADLファイルを指定するか、ウィザードを使用してサービスのメソッドを定義し、WADLファイルを作成できます。12.1.3 REST WADLファイルがサポートされています。REST操作をWSDLにマッピングするために定義されたSOA拡張は無視されます。ただし、Service Busでは、RESTサービスで使用されるWADLを構文的にも意味的にもチェックし、確実にルールに従うようにしています。
RESTベースのパイプライン: ネイティブRESTプロキシ・サービスによって呼び出されるパイプライン。ネイティブRESTプロキシおよびビジネス・サービスによって、RESTベースのパイプラインは入力済または未入力のいずれかにできます。新しいRESTブランチ・ノードは、未入力のRESTベース・パイプラインまたはパイプライン・テンプレートで使用できます。詳細は、「RESTブランチ」を参照してください。
注意:
12.1.3スタイルのWADLを参照するネイティブRESTパイプラインは作成できません。WADL参照はネイティブREST WADLである必要があります。
Service Busでは、12c 12.1.3リリースからのRESTサービスの実装もサポートしています。これらのサービスは、WSDLベースの内部インタフェースによって、引き続きJDeveloperを使用して作成できます。詳細は、「JDeveloperを使用したService Bus用のWSDLベースRESTサービスの作成方法」を参照してください。また、Service Busコンソールを使用して、SOAP XMLスキーマからの要素に基づく入力済RESTビジネス・サービスを作成することもできます。
ネイティブRESTサービスを呼び出す、またはこのサービスによって呼び出されるサービス・タイプは次のとおりです。
未入力のRESTプロキシ・サービスは別のネイティブRESTサービス(パイプラインまたはビジネス・サービス)のみを呼び出します。
入力済ネイティブRESTプロキシ・サービスは、同じWADLを参照して未入力のネイティブRESTサービス、または入力済RESTサービス(パイプラインまたはビジネス・サービス)を呼び出すことができます。
注意:
ローカル・トランスポート・プロキシ・サービスを除き、ネイティブRESTプロキシ・サービスを呼び出せるコンポーネント(プロキシ、パイプラインまたは分割-結合)はありません。
ネイティブRESTビジネス・サービスはどのパイプラインからでも呼び出せます。
ネイティブRESTサービスは、JSON、XML、フォームURLエンコード、テキスト、および不透明のタイプのペイロードを送受信できます。
JSON
注意:
SOAPからRESTの場合は、ネイティブRESTとはみなされません。このタイプのサービスでは、application/xmlまたはapplication/jsonタイプのペイロードのみをサポートします。
コンテンツ・タイプapplication/jsonのペイロードはJSONペイロードとみなされ、それに応じてJSONネイティブ・データ・モデルに解析されます。$bodyをログ記録する場合、次の例に示すように、JSONペイロードの文字データはsoap:Bodyタグでラップされます。
$body = <soap-env:Body><![CDATA[{ “foo1” : “foo2”}]]><soap-env:Body>
JSONペイロードはOSB内部で文字データとしては表現されなくても、ログ記録用には表現されます。これは、メッセージング/テキスト・サービス・タイプのペイロードの表現モデルと類似している部分があります。JSONペイロードをJavaScriptまたはアクションで操作する必要がある場合(次を参照)、JSONネイティブ・オブジェクトは、JavaScriptで必要とされるスクリプト可能なファサードにラップされます。
JSONペイロードは解析され、パイプラインがコンテンツ・ストリーミング用にマークされているかどうかに関係なく、JSONデータ・モデル・オブジェクトに完全にマテリアライズされます。
XML、テキスト、およびフォームURLエンコード
前述の定義済ネイティブRESTサービス・タイプは、コンテンツ・タイプのあるペイロードの送受信に使用できるようになります
text/xml or application/xml – これはXMLペイロードとみなされます。
text/plain、application/text、またはx-www-form-urlencoded – テキスト・ペイロードとみなされます。
ネイティブRESTバインディングのXMLペイロードは、任意のXMLまたはメッセージング/XMLコンテンツのモデル化と完全に同じようにモデル化され、$bodyのコンテンツには、インライン・ペイロードXMLが含まれます。
ネイティブRESTバインディングのテキスト・ペイロードは、メッセージング/テキスト・コンテンツのモデル化と完全に同じようにモデル化され、$bodyのコンテンツには、インライン・ペイロード文字データが含まれます。
パイプラインのコンテンツ・ストリーミングが有効な場合、テキストおよびXMLコンテンツは、AnyXMLおよびメッセージング・サービスの処理方法と同じように、完全にマテリアライズされずに処理されます。
不透明(バイナリ)
次に示すもの以外のRESTサービスで受信したコンテンツ・タイプ値は、不透明(またはバイナリ)ペイロードとみなされます。
application/json
application/xml
text/xml
text/plain
application/text
application/x-www-form-urlencoded
不透明なペイロードは、イメージ・ファイルなどのバイナリ・メッセージをRESTプロキシからのレスポンス、またはRESTビジネス・サービスへのリクエストとしてバイナリ・メッセージを送信可能にするか、バイナリ・メッセージをRESTビジネス・サービスへのレスポンス、またはRESTプロキシへのリクエストとして受信可能にすることを目的としています。不透明なペイロード・コンテンツは、バイナリ・リポジトリに格納されます。$bodyには、<ctx:binary-content>要素を使用したこのコンテンツへの参照が含まれています。
example/bookmarks+xmlなどのカスタム・メディア・タイプを使用する場合は、バイナリからテキスト、XML、またはJSONテキストへの変換にカスタムXPath関数またはJavaコールアウト・アクションを使用できます。
パイプラインのコンテンツ・ストリーミングが有効な場合、不透明なぺイロードは、メッセージング/バイナリ・サービス・タイプの場合と同じように、ストリーミング形式で処理されます。
正常なレスポンス、および失敗レスポンスには、それぞれ単一のデフォルト値を設定できます。ステータス・コードは、200から300の範囲になる場合は成功とみなされます。
ネイティブRESTプロキシ・サービスのランタイムでは、HTTPステータス・コードがインバウンド・レスポンス・メタデータに設定されていない場合、対応するREST操作のWADLに定義されたデフォルトの成功ステータス・コードが正常なレスポンス・コードとして送信されます。HTTPステータス・コードがインバウンド・レスポンス・メタデータで設定されている場合は、そのステータス・コードが返されます。
同様に、失敗した場合は、HTTPステータス・コードがインバウンド・レスポンス・メタデータに設定されていなければ、対応するREST操作のWADLに定義されたデフォルトの失敗ステータス・コードがクライアントに返されます。
ビジネス・サービスの場合、RESTウィザードで作成されたWADLには、ステータス・コードは定義されていません。既存のWADLにステータス・コードがある場合、ランタイムでは無視されます。このため、レスポンス・コードはビジネス・サービス起動から消費されます。
未処理のエラーが発生した場合、ネイティブRESTサービスによって、Errors.xsdに定義されているスキーマに従ってコール元にペイロードが返されます。
<element name="RestError" type="err:RestErrorType"/>
<complexType name="RestErrorType">
<sequence>
<element name="errorMessage" minOccurs="0" type="string" />
<element name="errorCode" minOccurs="0" type="string" />
</sequence>
</complexType>
受信するHTTP Acceptヘッダーの値がapplication/jsonまたはnullの場合、次の例に示すとおり、前述のペイロードがJSON形式で返されます。
{
"errorMessage" : "XPath can only be executed against XML or MFL content",
"errorCode" : "OSB-395357"
}
HTTP Acceptヘッダーの値がapplication/xmlの場合はXML形式で返されます。HTTP Acceptヘッダーの値がapplication/json、application/xml、またはnull以外の場合、ペイロードは返されません。エラー・レスポンスはHTTPステータス・コード500で返されます。
Service BusのRESTサービスのセキュリティは、Oracle Web Services Manager (OWSM)ポリシーで保護されます。詳細は、『Oracle Web Services ManagerによるWebサービスの保護とポリシーの管理』のRESTful WebサービスおよびクライアントでサポートされるOWSMポリシーに関する項を参照してください。
RESTエンドポイントによるサービスも、OAuthを使用してセキュリティ保護できます。「OAuthを使用したRESTエンドポイントによるサービスの保護」を参照してください。
ネイティブRESTプロキシ・サービスは、Basic認証やSSLなど、任意のHTTPプロキシ・サービスですでにサポートされているトランスポート・レベルの認証メカニズムをサポートしています。ただし、メッセージ・レベルのセキュリティはサポートされていません。
RESTバインディングに基づいてプロキシまたはビジネス・サービスを作成する場合、JDeveloperは必要なWADLドキュメントを自動的に生成します。RESTバインディングの作成ウィザードで生成されるWADLファイルは、既存のWSDLファイル、またはRESTバインディング・ウィザードでユーザが作成するWSDLファイルに基づいています。それはサービスの構造を定義します。実行時に、Service BusはWADLドキュメントを使用して、関連するWSDL操作を計算し、メッセージ・ペイロードを変換します。ペイロードは、JSON、XML、URLエンコードなどのRESTメディア・タイプから、パイプラインで期待される形式に変換され、その後サービスで期待されるRESTメディア・タイプに戻されます。単一の部分を単一の要素で定義する操作を含むSOAPドキュメント・スタイルのWSDLファイルのみがRESTサービスでサポートされます。
WADLファイルは、拡張子.wadlでJDeveloperに保存されます。JDeveloperの標準XMLエディタを使用して、RESTバインディング・ウィザードで作成したWADLファイルを編集できます。WADLファイルには、1つ以上のXMLスキーマに対する依存関係を含めることができます。
設計時、Service BusではWADLドキュメントを使用して、新しいサービスの構造を定義します。実行時に、Service BusはWADLドキュメントを使用して、関連するWSDL操作を計算し、メッセージ・ペイロードを変換します。ペイロードは、JSON、XML、URLエンコードなどのRESTメディア・タイプから、パイプラインで期待される形式に変換する必要があります。その後、サービスで期待されるRESTメディア・タイプに戻す必要があります。
ネイティブRESTサービスに対応するWADLには、どのメディア・タイプについても、関連付けられた型/スキーマ情報(メッセージの形状)がありません。次の個別ケースのリストは、JSON、XML、テキスト、フォームURLエンコード、および不透明(バイナリ)のサービス・タイプ用にWADLでサポートされています。
JSON
JSONベース表現はメディア・タイプapplication/jsonで定義されます。これはWADLに次の表現があります。
<representation mediaType=”application/json”>
ランタイムでは、これは「ネイティブRESTサービスによってサポートされているペイロード」に示すJSONペイロードとして扱われます。
XML
対応するWADL表現要素には、次の形式があります。
<representation mediaType=”application/xml”> or <representation mediaType="text/xml">
要素属性はXML要素をポイントします。XMLスキーマはWADL内の<grammars>の一部です。
ランタイムでは、これは「ネイティブRESTサービスによってサポートされているペイロード」に示すXMLペイロードとして扱われます。
テキスト
テキスト・ベース表現はメディア・タイプapplication/textで定義されます。これには次の表現が含まれます。
<representation mediaType=”application/text”> or <representation mediaType=”text/plain”>
ランタイムでは、これは「ネイティブRESTサービスによってサポートされているペイロード」に示すテキスト・ペイロードとして扱われます。
フォームURLエンコード
URLエンコード表現は、次の表現によって定義されています。
<representation mediaType="application/x-www-form-urlencoded">
ランタイムでは、これは「ネイティブRESTサービスによってサポートされているペイロード」に示すテキスト・ペイロードとして扱われます。
不透明(バイナリ)
バイナリ・ベース表現(つまり、このセクションでリストされているもの以外のすべて)は、メディア・タイプ*/*によって定義されます。これには次の表現が含まれます。
<representation mediaType=”*/*”>ランタイムでは、これは「ネイティブRESTサービスによってサポートされているペイロード」に示す不透明なペイロードとして扱われます。
注意:
最初の段落にあるテキストは、Service Bus 12.1.3で使用されるものと同様に、WSDLベースRESTサービスで使用されるWADLにのみ適用されます。
問合せスタイルの操作パラメータを構成する場合、ペイロードまたはプロパティのいずれかに基づいて式を構成できます。ペイロードベースの式($msg.parameters/tns:symbolなど)では、対応する抽象リクエスト・メッセージ・パートの要素または属性の値を指定します。プロパティベースの式($property.PropertyNameなど)では、実行時に$inbound変数のリクエスト・メタデータの値を指定します。
プロキシ・サービスまたはインバウンド・リクエストの場合、パイプラインで$inbound変数に問合せを行い、指定のユーザーメタデータ要素の値を取得できます。たとえば、$property.PropertyNameの場合、$inbound/ctx:transport/ctx:request/tp:user-metadata[@name = 'PropertyName']/@valueの値を問い合せることができます。ビジネス・サービスまたはアウトバウンド・リクエストの場合、パイプラインの$outbound変数のパートの値を、対応するリクエスト・パラメータに割り当てることができます。
問合せパラメータは、$inbound HTTP固有のメタデータで使用できます。
インバウンド・リクエストの場合、テンプレート・パラメータの値はリクエスト・メタデータ内で使用可能になります。次に例を示します。
<param name="param1" style="template" type="xsd:string"/>
ランタイムでは、次の例に示すとおり、param1テンプレート・パラメータの値がリクエスト・メタデータの作成に使用されます。
$inbound = …
<ctx:transport>
<ctx:request>
<headers …>
<ctx:user-metadata name=”param1” value=”1234” />
</ctx:request>
</ctx:transport>
アウトバウンド・リクエストの場合、ランタイムは$outboundメタデータ内で対応するWADLリソース/メソッドのテンプレート・パラメータ値を検索します。たとえば、WADLリソースが次のように定義される場合:
<resource path="/containers/{container}">ランタイムでは$outboundにcontainerという名前のユーザー・メタデータ要素が含まれると想定され、その値が使用されます。
追加情報:
soa:expression WADL属性はService Bus 12.1.3にあったため、WADLファイルのテンプレート・パラメータおよびクエリ・パラメータにはありません。
テンプレート(パス)・パラメータのランタイム・プロパティ名は単なるパラメータ名です。
リソースとメソッドを識別するため、WADLインタフェースで定義されているすべてのリソースで、メソッド識別子(名前)を付けるようにWADLが拡張されています。
RESTウィザードUIでは、変更可能なデフォルト・メソッド名が生成されます。メソッド名は一意です。カスタム属性soa:nameは、この情報をメソッド要素に格納します。この例は、次のとおりです。
<method name="POST" soa:name="create_order">
create_orderは一意のメソッドIDです。
Service Busランタイムでは、この一意の識別子は$operationシステム変数にマッピングされます。
単一のパートが要素によって定義される操作を含め、SOAPドキュメントスタイルのWSDLドキュメントのみがWSDLベースRESTサービスでサポートされます。SOAP RPCスタイルと汎用XMLスタイルのWSDLドキュメントはサポートされません。これは設計時の検証で実施されます。各操作またはメソッドについては、要素タイプのみが表現に対してサポートされます。スキーマ・タイプは使用されません。
WSDLベースのサービスと同様に、Service Busでは、Service Bus RESTfulサービスの開発時に作成する実際の.wadlファイルのかわりに、有効なWADLドキュメントを実行時に使用します。有効なWADLドキュメントとは、Service Busで構成されたサービスのWADLプロパティを表し、この中には、ソースWADLドキュメントの外部で構成された追加のプロパティも含まれます。有効なWADLドキュメントと設計時のWADLドキュメントでは、次の点が異なります。
有効なWADLドキュメントには、サービス・エンドポイントURLを含むベースURI情報があります。
有効なWADLドキュメントには、SOA拡張属性は含まれません。
設計時のファイルと有効なファイルとの違いについては、「有効なWSDLドキュメントと生成されたWSDLドキュメントについて」を参照してください。
JDeveloperでRESTバインディングに基づいてビジネスまたはプロキシ・サービスを作成する場合、RESTバインディングの作成ウィザードはサービスのWADLファイルを自動的に生成します。手順の詳細は、「RESTサービスの作成」を参照してください。
Oracle Service Busコンソールを使用する場合、WADLドキュメントを作成するには、ドキュメントをインポートするか、WADLリソースを作成して既存のWADLファイルを新しいリソースにアップロードします。
この項では、既存のWADLファイルを新しいWADLリソースにアップロードする方法を説明します。リソースのインポート方法の詳細は、「リソースおよび構成のインポートとエクスポート」を参照してください。
コンソールでWADLリソースを作成するには:
セッションをまだ作成していない場合は、「作成」をクリックして新しいセッションを作成するか、「編集」をクリックして既存のセッションを入力します。
プロジェクト・ナビゲータで、新しいWADLドキュメントを含めるプロジェクトまたはフォルダを右クリックして、「作成」をポイントし、「リソース」を選択します。「インタフェース」をクリックし、「WADL」、「OK」の順にクリックします。
WADLの作成ダイアログが表示されます。
次のいずれかを行います:
既存のWADLファイルからリソースを作成するには、「ファイルのアップロード」フィールドの横の「参照」をクリックしてから、使用するWADLファイルに移動してそのファイルを選択します。
「リソース名」フィールドに、ファイル拡張子なしのファイル名が自動的に移入されます。この名前は変更可能です。
新しいWADLファイルを作成するか、またはWADLファイルを後でアップロードするには、WADLリソースの一意の名前を入力します。
必要に応じて、リソースの簡単な説明を入力します。
「作成」をクリックします。
WADL要素(定義される場合)がWADL定義エディタに表示されます。
WADLファイルのコンテンツを変更するには、次のようにします。
ツールバーの「ソースの編集」をクリックします。
「ソースの編集」ダイアログが表示されます。
アップロードする新しいWADLファイルを参照して選択するには、「参照」をクリックします。
ファイルのコンテンツを変更するには、ダイアログの「コンテンツ」セクションでコードを直接更新します。
「保存」をクリックします。
WADL定義エディタのツールバーで、「保存」をクリックします。
新しいWADLドキュメントに未解決の参照がある場合は、エディタのタイトル・バーの横に「競合」アイコンが表示されます。戻る矢印と次に進む矢印ボタンを使用して、エラー全体をスクロールします。
セッションを終了して構成をランタイムにデプロイするには、「アクティブ化」をクリックします。
Service Busプロジェクト内でWADLドキュメントを作成したら、必要に応じてそのドキュメントを編集または削除できます。
WADLドキュメントは、JDeveloperの標準機能です。WADLドキュメントを標準エディタで表示して、ソース・コードを直接変更できます。
Oracle Service Busコンソールを使用している場合は、次の手順でWADLドキュメントを編集します。コードを直接編集するか、更新されたWADLファイルをリソースにアップロードできます。
コンソールでWADLドキュメントを編集するには:
JDeveloperを使用して、RESTビジネスおよびプロキシ・サービスを作成できます。Service Bus概要エディタで「RESTバインディングの作成」ウィザードを使用して新しいサービスを作成、既存のWSDLサービスを、パイプラインおよび分割-結合を含めてRESTとして公開、または「プロキシ・サービスの作成」または「ビジネス・サービスの作成」ウィザードを使用してRESTサービスを作成できます。「MDSリポジトリに格納されたアーティファクトの使用」で説明されているように、Oracle Metadata Services (MDS)リポジトリに保存されたアーティファクトからRESTサービスを作成することもできます。
また、RESTプロキシおよびビジネス・サービスは、Service Busコンソールから作成するか、JDeveloperで作成されたリソースを含むプロジェクトまたはリソースを構成JARファイルを使用してコンソールにインポートできます。
RESTプロキシ・サービスは、次のものを呼び出すことができます。
同じWSDLバインドのWSDLベースのプロキシ・サービス、パイプライン、分割-結合またはビジネス・サービス。
SOAP 1.1または1.2バインディング・タイプのプロキシ・サービス、パイプラインまたはビジネス・サービス。SOAPバージョンは、呼び出すプロキシ・サービスと同じである必要があります。
同じWADL参照およびWSDLバインドのRESTビジネス・サービス。
その他のRESTベース・ビジネス・サービスまたはプロキシ・サービス。
RESTのプロキシ・サービスは、RESTおよびHTTPトランスポート・ビジネス・サービスによって呼び出すことができます。
RESTサービスとRESTバインディングの詳細は、『Oracle SOA SuiteでのSOAアプリケーションの開発』のSOAコンポジット・アプリケーションでのREST操作の統合に関する項を参照してください。
注意:
RESTバインディングを作成したら、フォルト・スキーマは変更しないでください。フォルト・バインディングの詳細は、Oracle SOA Suiteを使用したSOAアプリケーションの開発のRESTフォルト・バインディングに関する必知事項を参照してください。
ネイティブRESTサービスは、JDeveloperおよびService Busコンソールを使用して作成できます。
次のトピックを参照して、ネイティブRESTプロキシ・サービスを作成します。
次のトピックを参照して、ネイティブRESTビジネス・サービスを作成します。
RESTバインディングを使用してプロキシまたはビジネス・サービスを作成すると、Service Busでは、必要なWADLファイルがHTTPタイプのプロキシまたはビジネス・サービスとともに生成されます。RESTバインディングはWSDLドキュメントをベースにすることができます。これにより、XMLに変換された受信ペイロードを使用して、RESTリソース/動詞を内部WSDL操作およびXMLスキーマにマッピングします。RESTバインディングの構成方法に応じて、プロキシ・サービスが既存のWSDLファイルに基づくことも、ユーザーがプロキシ・サービスの生成時にWSDLファイルを作成することもできます。
かわりに入力済のネイティブRESTサービスを作成する方法については、「JDeveloperを使用したService Bus用の入力済RESTサービスの作成方法」を参照してください。
JDeveloperでWSDLベースRESTプロキシまたはビジネス・サービスを作成するには:
「コンポーネント」ウィンドウから「Service Bus」を選択し、RESTバインディングをデザイナの「プロキシ・サービス」または「外部サービス」レーンにドラッグします。
ヒント:
また、スイムレーンを右クリックして、表示されたメニューから「REST」を選択することもできます。
RESTバインディングの作成ウィザードが表示されます。
RESTサービスの名前を入力します。
ヒント:
構成フィールドについては、「ヘルプ」をクリックするか、[F1]キーを押してください。「ヘルプ」は、このプロセスで使用するすべてのダイアログで使用できます。
「タイプ」フィールドはデフォルト値のままにします。これは、プロキシ・サービスを作成しているのか(「サービス」)、ビジネス・サービスを作成しているのか(「参照」)によって選択されます。
「サービスはWSDLインタフェースを使用してコンポーネントを起動します」オプションを選択します。
(オプション)「XMLスキーマの順序付けの適用」オプションを選択し、JSONペイロードがXMLスキーマの要素順に一致するよう並べ替えます。これには、インバウンド・リクエスト・ペイロードおよびアウトバウンド・リクエストからのレスポンスが含まれます。
RESTビジネス・サービスを作成している場合は、「ベースURI」に入力します。これは、ビジネス・サービスのエンドポイントURIです。
「リソース」セクションで次を実行します。
デフォルトのパス・エントリの/をダブルクリックします。
「RESTリソースの更新」ダイアログが表示されます。
「相対パス」フィールドで、リソース・パスを指定し、「OK」をクリックします。
追加リソースを定義して個々の操作に割り当てるには、「リソース」セクションの「追加」アイコンをクリックして、前述の手順を繰り返します。
次のいずれかを実行して、操作バインディングを追加および定義します。
手動で操作バインディングを作成し、定義するには、「操作バインディングの追加」を選択し、手動で新しいREST操作を作成および定義します。複数のバインディングを追加できます。詳細は、「REST操作の作成または構成方法」を参照してください。
(ビジネス・サービスのみ)「構成ショートカット」セクションから「追加」をクリックし、「WADLサービスに基づく操作の追加」を選択して「WADLの選択」ダイアログを起動し、実装する操作を含む既存のWADLファイルを選択します。ファイル・システム、アプリケーション、MDSリポジトリなどにあるWADLファイルを参照できます。
(プロキシ・サービスのみ)「構成ショートカット」セクションから「追加」をクリックし、「RESTコンポーネントや参照の有効化」を選択して「リソース・チューザ」を起動し、現在のアプリケーションでREST操作の生成元となるService Busコンポーネントを選択します。
(プロキシ・サービスのみ)「構成ショートカット」セクションから「追加」をクリックし、「REST外部Webサービスの有効化」を選択して「WSDLの選択」を起動し、REST操作の生成元となるWSDLファイルを選択します。ファイル・システム、アプリケーション、MDSリポジトリ、UDDIレジストリなどにあるWSDLファイルを参照できます。
「操作バインディング」表に操作が表示されます。
バインディングを構成するには、次を実行します。
バインディングをダブルクリックします。
「REST操作バインディング」ダイアログが表示されます。
「REST操作の作成または構成方法」の説明に従ってバインディングを構成します。
RESTバインディングの作成ウィザードで「OK」をクリックします。
HTTPプロキシまたはビジネス・サービスが「プロキシ・サービス」または「外部サービス」レーンに追加され、そのファイルがプロジェクトに追加されます。関連付けられたWADLファイルがプロジェクトに追加されます。サービスとWADLファイルの両方に、手順2でRESTサービスに対して指定した名前と同じ名前が付けられます。
新しいビジネス・サービスを構成するには、「ビジネス・サービスの構成」を参照してください。新しいプロキシ・サービスを構成するには、「プロキシ・サービスの構成」を参照してください。
JDeveloperのツールバーで「すべて保存」をクリックします。
RESTバインディングを使用してプロキシまたはビジネス・サービスを作成すると、Service Busでは、必要なWADLファイルがHTTPタイプのプロキシまたはビジネス・サービスとともに生成されます。RESTバインディングの構成方法に応じて、プロキシ・サービスが既存のWADLファイルをベースにすることも、ユーザーがプロキシ・サービスの生成時にWADLファイルを作成することもできます。
かわりにWSDLベースRESTサービス(Service Bus 12.1.3で使用)を作成する場合は、「JDeveloperを使用したService Bus用のWSDLベースRESTサービスの作成方法」を参照してください。
JDeveloperで入力済ネイティブRESTプロキシまたはビジネス・サービスを作成するには:
「コンポーネント」ウィンドウから「Service Bus」を選択し、RESTバインディングをデザイナの「プロキシ・サービス」または「外部サービス」レーンにドラッグします。
ヒント:
また、スイムレーンを右クリックして、表示されたメニューから「REST」を選択することもできます。
RESTバインディングの作成ウィザードが表示されます。
RESTサービスの名前を入力します。
ヒント:
構成フィールドについては、「ヘルプ」をクリックするか、[F1]キーを押してください。「ヘルプ」は、このプロセスで使用するすべてのダイアログで使用できます。
「タイプ」フィールドはデフォルト値のままにします。これは、プロキシ・サービスを作成しているのか(「サービス」)、ビジネス・サービスを作成しているのか(「参照」)によって選択されます。「次へ」をクリックします。
RESTビジネス・サービスを作成している場合は、「ベースURI」に入力します。これは、ビジネス・サービスのエンドポイントURIです。
「リソース」セクションで次を実行します。
デフォルトのパス・エントリの/をダブルクリックします。
「RESTリソースの更新」ダイアログが表示されます。
「相対パス」フィールドで、リソース・パスを指定し、「OK」をクリックします。
追加リソースを定義して個々の操作に割り当てるには、「リソース」セクションの「追加」アイコンをクリックして、前述の手順を繰り返します。
次のいずれかを実行して、メソッドを追加および定義します。
RESTメソッドを手動で作成し、定義するには、「メソッド」セクションで「追加」アイコンをクリックします。詳細は、「JDeveloperでのRESTメソッドの作成または構成方法」を参照してください。
「構成ショートカット」セクションから「追加」をクリックし、「WADLサービスからリソースとメソッドを追加」を選択して「WADLチューザ」ダイアログを起動し、追加するメソッドを含む既存のWADLファイルを選択します。ファイル・システム、アプリケーション、MDSリポジトリなどにあるWADLファイルを参照できます。
メソッドが「メソッド」表に表示されます。
メソッドを構成するには、次を実行します。
メソッドをダブルクリックします。
「RESTメソッド定義」ダイアログが表示されます。
「JDeveloperでのRESTメソッドの作成または構成方法」に示すとおり、メソッドを構成します。
RESTバインディングの作成ウィザードで「OK」をクリックします。
HTTPプロキシまたはビジネス・サービスが「プロキシ・サービス」または「外部サービス」レーンに追加され、そのファイルがプロジェクトに追加されます。関連付けられたWADLファイルがプロジェクトに追加されます。サービスとWADLファイルの両方に、手順2でRESTサービスに対して指定した名前と同じ名前が付けられます。
新しいビジネス・サービスを構成するには、「ビジネス・サービスの構成」を参照してください。新しいプロキシ・サービスを構成するには、「プロキシ・サービスの構成」を参照してください。
JDeveloperのツールバーで「すべて保存」をクリックします。
手動でREST操作を作成したり、それらの操作または既存のサービス・コンポーネントやWebサービスから生成した操作を手動で変更することが可能です。どちらのプロセスも「REST操作バインディング」ダイアログを使用します。これらの手順は、「JDeveloperを使用したService Bus用のWSDLベースRESTサービスの作成方法」の手順8にあります。
注意:
操作を作成した方法、および操作を作成しているのか更新しているのかによって、次に説明するフィールドの一部は編集できない場合があります。
REST操作を作成または構成するには:
「RESTサービスの作成」ダイアログで、編集する操作をダブルクリックします。
「REST操作バインディング」ダイアログが表示されます。
新しい操作を作成している場合は、その操作の名前と必要に応じて説明を入力します。
必要に応じて「リソース」リストから新しいリソースを選択します。
「HTTP動詞」リストから、使用するHTTPメソッドを選択します。
リクエストのスキーマを定義するには、次のいずれかを実行します。
「スキーマ・ファイルを参照」をクリックして、その操作のXMLスキーマ・タイプに移動し、これを選択します。
「ネイティブ・フォーマットのスキーマの定義」をクリックし、ネイティブ・フォーマット・ビルダーを起動してカスタムの変換を定義します。
「要素」フィールドおよびURIパラメータが、選択内容に基づいて更新されます。
「URIパラメータ」セクションで次を実行します。
「サンプルURL」ページで実行時に操作を呼び出すURLを表示するには、操作のURLを生成をクリックします。
パラメータのスタイルを変更するには、パラメータの「スタイル」列をダブルクリックし、「スタイル」リストの「問合せ」または「テンプレート」を選択します。
パラメータのタイプを変更するには、パラメータの「タイプ」列をダブルクリックし、「タイプ」リストから新しいタイプを選択します。
パラメータのデフォルト値を入力するには、更新するパラメータの「デフォルト値」列をダブルクリックし、「デフォルト値」フィールドで使用する値を入力します。
XPath式関数の追加または更新のために式ビルダーを起動するには、更新するパラメータの「式」列をダブルクリックし、「式」フィールドの隣の「式ビルダー」アイコンをクリックします。式ビルダーを使用して、使用するXPath式を定義します。
パラメータを手動で追加するには、「パラメータの追加」をクリックして、表示される新しい行に値を入力します。
パラメータを削除するには、その行を選択して、「パラメータの削除」をクリックします。
「レスポンス」タブをクリックして、レスポンスを構成します。
「HTTPステータス」フィールドに、成功した操作に対して返すHTTPステータス・コードを入力します(区切りは空白による)。
「ペイロード」フィールドで、レスポンスのペイロードのタイプを選択します。
後でファイルに保存可能なサンプル・ペイロードを生成するには、「サンプル・ペイロードの生成」をクリックします。
レスポンスのスキーマを定義するには、次のいずれかを実行します。
「スキーマ・ファイルを参照」をクリックして、その操作のXMLスキーマ・タイプに移動し、これを選択します。
「ネイティブ・フォーマットのスキーマの定義」をクリックし、ネイティブ・フォーマット・ビルダーを起動してカスタムの変換を定義します。
「要素」フィールドおよびフォルト・バインディングが、選択内容に基づいて更新されます。
フォルト・バインディングを手動で追加するには、「フォルト・バインディングの追加」をクリックします。「RESTフォルト・バインディング」ダイアログで次を実行します。
フォルトの名前を入力します。
フォルトに対して返されるHTTPのステータスのリストを入力します(区切りは空白による)。
フォルトのペイロードのタイプを選択します。フォルトのサンプル・ペイロードを生成するには、「サンプル・ペイロードの生成」をクリックします。
フォルトを定義するスキーマおよび要素を選択します。
「OK」をクリックします。
フォルトのHTTPステータスまたはペイロード・タイプを更新するには、フォルト・バインディング表でこれをダブルクリックし、「RESTフォルト・バインディング」ダイアログの情報を更新します。
「REST操作バインディング」ダイアログで「OK」をクリックします。
手動でRESTメソッドを作成したり、それらのメソッドまたは既存WADLから生成したメソッドを手動で変更することが可能です。どちらのプロセスも、「RESTメソッド定義」ダイアログを使用します。これらの手順は、「JDeveloperを使用したService Bus用の入力済RESTサービスの作成方法」の手順6にあります。
注意:
メソッドを作成した方法、およびメソッドを作成しているのか更新しているのかによって、次に説明するフィールドの一部は編集できない場合があります。
RESTメソッドを作成または構成するには:
「RESTサービスの作成」ダイアログで、編集するメソッドをダブルクリックします。
「RESTメソッド定義」ダイアログが表示されます。
新しいメソッドを作成している場合は、その名前とオプションの説明を入力します。
必要に応じて「リソース」リストから新しいリソースを選択します。
「HTTP動詞」リストから、使用するHTTPメソッドを選択します。
「URIパラメータ」セクションで次を実行します。
「サンプルURL」ページで実行時にメソッドを呼び出すURLを表示するには、「メソッドのサンプルURLを生成します」をクリックします。
パラメータのスタイルを変更するには、パラメータの「スタイル」列をダブルクリックし、「スタイル」リストの「問合せ」または「テンプレート」を選択します。
パラメータのタイプを変更するには、パラメータの「タイプ」列をダブルクリックし、「タイプ」リストから新しいタイプを選択します。
パラメータのデフォルト値を入力するには、更新するパラメータの「デフォルト値」列をダブルクリックし、「デフォルト値」フィールドで使用する値を入力します。
パラメータを手動で追加するには、「パラメータの追加」をクリックして、表示される新しい行に値を入力します。
パラメータを削除するには、その行を選択して、「パラメータの削除」をクリックします。
「レスポンス」タブをクリックして、レスポンスを構成します。
「HTTPステータス」フィールドに、成功したメソッドと失敗したメソッドに対して返すHTTPステータス・コードを入力します。
「ペイロード」フィールドで、レスポンスのペイロードのタイプを選択します。
「RESTメソッド定義」ダイアログで、「OK」をクリックします。
JDeveloperで、既存のWSDLベースのプロキシ・サービス、パイプライン、分割-結合またはビジネス・サービスを、プロキシ・サービスと関連付けられたWADLドキュメントを生成するRESTサービスとして公開できます。また、RESTベースのビジネス・サービスを公開することもできます。生成されたプロキシ・サービスは、自動的に作成元のサービスにワイヤリングされます。
Service BusサービスをRESTとして公開するには:
12.1.3スタイルでWSDLベースRESTサービスのRESTバインディングを作成するとき、XPath式を使用して、操作のURIパラメータの値を定義できます。問合せスタイルの操作パラメータを構成する場合、ペイロードまたはプロパティに基づいた式にできます。$msg.parameters/tns:symbolのようなペイロードに基づく式は、該当する抽象リクエスト・メッセージ部分の要素または属性の値を指定します。$property.SomePropertyのようなプロパティに基づく式は、実行時に$inbound変数のリクエスト・メタデータの値を指定します。
インバウンド・リクエストの場合、パイプラインの$inbound変数を問い合せ、指定のメタデータ要素の値を取得できます。アウトバウンド・リクエストの場合、パイプラインの$outbound変数の部分に適した値を対応するリクエスト・パラメータに割り当てることができます。
設計時のWADLドキュメントと有効なWADLドキュメントはどちらもWebブラウザを介して表示できます。ブラウザ・ウィンドウからファイルにアクセスすると、ファイルのコンテンツがXML形式で表示されます。Service Busでは、コンテンツの閲覧が容易になるようにユーザーが読取り可能なインタフェースも用意されています。
次のいずれかを実行して、Service Bus WADLドキュメントをWebブラウザで表示します。
サービスの有効なWADLを表示するには、次の構文を使用して固定HTTP URLをWebブラウザに入力します。
http://host:port/sbresource?PROXY/project_path/proxy_service_name
または
http://host:port/sbresource?BIZ/project_path/business_service_name
この方法は、Service Busが、サービスの有効なWADLドキュメントを生成できるサービスすべてに使用できます。このサービスにWSDLドキュメントも関連付けられている場合、前述の構文では、サービスの有効なWADLドキュメントのみが表示されます。
設計時のWADLドキュメントを表示するには、次の構文を使用して固定HTTP URLをWebブラウザに入力します。
http://host:port/sbresource?WADL/project_path/wadl_name
設計時のWADLドキュメントおよびサービスの有効なWADLドキュメントは、読みやすい形式を使用してブラウザで表示できます。WADLドキュメントを表示するには、Webブラウザを開き、次の説明に従いサービスのURLを入力します。
サービスの有効なWADLドキュメントを表示するには、次の構文を使用します。
http://host:port/sbresource?PROXY/project_path/proxy_service_name&HTML=true
または
http://host:port/sbresource?BIZ/project_path/business_service_name&HTML=true
このサービスにWSDLドキュメントも関連付けられている場合、前述の構文では、サービスの有効なWADLドキュメントのみが表示されます。
設計時のWADLドキュメントを表示するには、次の構文を使用します。
http://host:port/sbresource?WADL/project_path/wadl_name&HTML=true
WADLコンテンツは、次のイメージのような形式でブラウザに表示されます。
