| Oracle® Fusion Middleware Oracle Service Busでのサービスの開発 12c (12.1.3) E53004-06 |
|
 前 |
 次 |
この章では、Service Busプロジェクト内でバインド・コンポーネントとしてRepresentational State Transfer (REST)操作を統合する方法について説明します。また、RESTfulサービスでWSDLに相当するWeb Application Definition Language (WADL)ドキュメントについても説明します。
RESTプロキシおよびビジネス・サービスを作成できるのは、JDeveloperからのみです。RESTサービスを作成したら、必要に応じてこれらをエクスポートし、Oracle Service Busコンソールにインポートできます。
この章の内容は次のとおりです。
RESTは、ネットワーク・アプリケーションの設計用のアーキテクチャです。RESTfulアプリケーションでは、HTTPリクエストを使用してデータのポスト(作成および更新)、データの取得(問合せの作成など)およびデータの削除を行います。RESTは、従来のWSDLベースのWebサービスの軽量な代替機能を提供します。
Service Busでは、次のRESTサポートを提供します。
プロキシおよびビジネス・サービスでのRESTサポート
外部REST APIとの統合
XML、JavaScript Object Notation (JSON) (XMLとの間の変換を含む)およびURLエンコード・データ
JDeveloperのRESTインタフェースとWSDLマッピングをモデル化するためのウィザード
必要なWADLファイルの自動作成
JDeveloper内からOracle RESTエンドポイントを参照および使用する機能
RESTセキュリティのためのOracle Web Service Manager (OWSM)ポリシー・サポート
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をサポートするための仮想レイヤーを提供します。つまり、プロキシおよびビジネス・サービスのみがRESTベースになります。これらのRESTサービスは、WSDLベースのパイプラインまたは分割-結合を呼び出すこともあれば、それらに呼び出されることもあります。RESTプロキシ・サービスは、パイプラインまたは分割-結合を呼び出す前にRESTネイティブ・ペイロードをSOAPに変換する一方、パイプラインまたは分割-結合によって呼び出されるRESTビジネス・サービスは、SOAPのペイロードをRESTに変換します。内部インタフェースはWSDLベースですが、外部ビジネスおよびプロキシ・サービスはRESTエンドポイントを公開します。
操作の単一の部分が単一の要素で定義されているSOAPドキュメント・スタイルのWSDLファイルのみが、RESTサービスでサポートされます。構文的に有効であるかぎり、SOAP拡張注釈がない、または前述の制限に必ずしも従わないWADLファイルを作成することは可能です。ただし、Service Busでは、RESTサービスで使用されるWADLを構文的にも意味的にもチェックし、確実にルールに従うようにしています。
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メディア・タイプに戻す必要があります。
問合せスタイルの操作パラメータを構成する場合、ペイロードまたはプロパティのいずれかに基づいて式を構成できます。ペイロードベースの式($msg.parameters/tns:symbolなど)では、対応する抽象リクエスト・メッセージ・パートの要素または属性の値を指定します。プロパティベースの式($property.PropertyNameなど)では、実行時に$inbound変数のリクエスト・メタデータの値を指定します。
プロキシ・サービスまたはインバウンド・リクエストの場合、パイプラインで$inbound変数に問合せを行い、指定のユーザーメタデータ要素の値を取得できます。たとえば、$property.PropertyNameの場合、$inbound/ctx:transport/ctx:request/tp:user-metadata[@name = 'PropertyName']/@valueの値を問い合せることができます。ビジネス・サービスまたはアウトバウンド・リクエストの場合、パイプラインの$outbound変数のパートの値を、対応するリクエスト・パラメータに割り当てることができます。
単一のパートが要素で定義される操作を含むSOAPドキュメントスタイルの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」を選択します。
WADLの作成ダイアログが表示されます。
次のいずれかを行います:
既存のWADLファイルからリソースを作成するには、「ファイルのアップロード」フィールドの横の「参照」をクリックしてから、使用するWADLファイルに移動してそのファイルを選択します。
「リソース名」フィールドに、ファイル拡張子なしのファイル名が自動的に移入されます。この名前は変更可能です。
新しいWADLファイルを作成するか、またはWADLファイルを後でアップロードするには、WADLリソースの一意の名前を入力します。
必要に応じて、リソースの簡単な説明を入力します。
「作成」をクリックします。
WADL要素(定義される場合)がWADL定義エディタに表示されます。
WADLファイルのコンテンツを変更するには、次のようにします。
ツールバーの「ソースの編集」をクリックします。
「ソースの編集」ダイアログが表示されます。
アップロードする新しいWADLファイルを参照して選択するには、「参照」をクリックします。
ファイルのコンテンツを変更するには、ダイアログの「コンテンツ」セクションでコードを直接更新します。
「保存」をクリックします。
WADL定義エディタのツールバーで、「保存」をクリックします。
新しいWADLドキュメントに未解決の参照がある場合は、エディタのタイトル・バーの横に「競合」アイコンが表示されます。戻る矢印と次に進む矢印ボタンを使用して、エラー全体をスクロールします。
セッションを終了して構成をランタイムにデプロイするには、「アクティブ化」をクリックします。
Service Busプロジェクト内でWADLドキュメントを作成したら、必要に応じてそのドキュメントを編集または削除できます。
WADLドキュメントは、JDeveloperの標準機能です。WADLドキュメントを標準エディタで表示して、ソース・コードを直接変更できます。
Oracle Service Busコンソールを使用している場合は、次の手順でWADLドキュメントを編集します。コードを直接編集するか、更新されたWADLファイルをリソースにアップロードできます。
コンソールでWADLドキュメントを編集するには:
RESTビジネスおよびプロキシ・サービスを作成できるのは、JDeveloperからのみです。Service Bus概要エディタでRESTバインディングの作成ウィザードを使用して新しいサービスを作成するか、既存のWSDLサービスを、パイプラインおよび分割-結合を含めてRESTとして公開できます。「MDSリポジトリに格納されたアーティファクトの使用」で説明されているように、Oracle Metadata Services (MDS)リポジトリに保存されたアーティファクトからRESTサービスを作成することもできます。
Oracle Service BusコンソールでRESTのプロキシおよびビジネス・サービスを使用するには、構成JARファイルからプロジェクトまたはリソースをインポートする必要があります。
WSDL SOAP 1.1または1.2バインディングを使用するRESTプロキシ・サービスは、次を呼び出すことができます。
同じWSDLバインドのWSDLベースのプロキシ・サービス、パイプライン、分割-結合またはビジネス・サービス。
SOAP 1.1または1.2バインディング・タイプのプロキシ・サービス、パイプラインまたはビジネス・サービス。SOAPバージョンは、呼び出すプロキシ・サービスと同じである必要があります。
同じWADL参照およびWSDLバインドのRESTビジネス・サービス。
RESTのプロキシ・サービスは、RESTおよびHTTPトランスポート・ビジネス・サービスによって呼び出すことができます。
RESTサービスとRESTバインディングの詳細は、『Oracle SOA SuiteでのSOAアプリケーションの開発』のSOAコンポジット・アプリケーションでのREST操作の統合に関する項を参照してください。
注意:
RESTバインディングを作成したら、フォルト・スキーマは変更しないでください。フォルト・バインディングの詳細は、Oracle SOA Suiteを使用したSOAアプリケーションの開発のRESTフォルト・バインディングに関する必知事項を参照してください。
RESTバインディングを使用してプロキシまたはビジネス・サービスを作成すると、Service Busでは、必要なWADLファイルがHTTPタイプのプロキシまたはビジネス・サービスとともに生成されます。RESTバインディングはWSDLドキュメントに基づいています。RESTバインディングの構成方法に応じて、プロキシ・サービスを既存のWSDLファイルに基づかせることも、プロキシ・サービスの生成時にWSDLファイルを作成することもできます。RESTビジネス・サービスの作成時に、ウィザードはWSDLファイルとWADLファイルの両方を生成します。
RESTプロキシまたはビジネス・サービスを作成するには:
「コンポーネント」ウィンドウから「Service Bus」を選択し、RESTバインディングをデザイナの「プロキシ・サービス」または「外部サービス」レーンにドラッグします。
ヒント:
また、スイムレーンを右クリックして、表示されたメニューから「REST」を選択することもできます。
RESTバインディングの作成ウィザードが表示されます。
名前を入力し、必要に応じてRESTサービスの簡単な説明を入力します。
ヒント:
構成フィールドについては、「ヘルプ」をクリックするか、[F1]キーを押してください。「ヘルプ」は、このプロセスで使用するすべてのダイアログで使用できます。
「タイプ」フィールドはデフォルト値のままにします。これは、プロキシ・サービスを作成しているのか(「サービス」)、ビジネス・サービスを作成しているのか(「参照」)によって選択されます。
RESTビジネス・サービスを作成している場合は、「ベースURI」に入力します。これは、ビジネス・サービスのエンドポイントURIです。
「リソース」セクションで次を実行します。
デフォルトのパス・エントリの/をダブルクリックします。
「RESTリソースの更新」ダイアログが表示されます。
「相対パス」フィールドで、リソース・パスを指定し、「OK」をクリックします。
追加リソースを定義して個々の操作に割り当てるには、「リソース」セクションの「追加」アイコンをクリックして、前述の手順を繰り返します。
「操作バインディング」セクションで「追加」アイコンをクリックし、次のいずれかを実行します。
「操作バインディングの追加」を選択し、手動で新しいREST操作を作成および定義します。複数のバインディングを追加できます。詳細は、「REST操作の作成または構成方法」を参照してください。
(ビジネス・サービスのみ)「WADLサービスに基づく操作の追加」を選択し、「WADLの選択」ダイアログを起動して実装する操作を含む既存のWADLファイルを選択します。ファイル・システム、アプリケーション、MDSリポジトリなどにあるWADLファイルを参照できます。
(プロキシ・サービスのみ)「RESTコンポーネントや参照の有効化」を選択し、「リソース・チューザ」を起動して、現在のアプリケーションでREST操作の生成元となるService Busコンポーネントを選択します。
(プロキシ・サービスのみ)「REST外部Webサービスの有効化」を選択し、「WSDLの選択」を起動して、REST操作の生成元となるWSDLファイルを選択します。ファイル・システム、アプリケーション、MDSリポジトリ、UDDIレジストリなどにあるWSDLファイルを参照できます。
「操作バインディング」表に操作が表示されます。最後の2つのオプションのいずれかを選択した場合、次の手順で説明するとおり、バインディングを構成する必要があります。最初の2つのオプションの場合、これは任意です。
バインディングを構成するには、次を実行します。
バインディングをダブルクリックします。
「REST操作バインディング」ダイアログが表示されます。
「REST操作の作成または構成方法」の説明に従ってバインディングを構成します。
RESTバインディングの作成ウィザードで「OK」をクリックします。
HTTPプロキシまたはビジネス・サービスが「プロキシ・サービス」または「外部サービス」レーンに追加され、そのファイルがプロジェクトに追加されます。関連付けられたWADLファイルがプロジェクトに追加されます。サービスとWADLファイルの両方に、手順2でRESTサービスに対して指定した名前と同じ名前が付けられます。
新しいビジネス・サービスを構成するには、「ビジネス・サービスの構成」を参照してください。新しいプロキシ・サービスを構成するには、「プロキシ・サービスの構成」を参照してください。
JDeveloperのツールバーで「すべて保存」をクリックします。
手動でREST操作を作成したり、それらの操作または既存のサービス・コンポーネントやWebサービスから生成した操作を手動で変更することが可能です。どちらのプロセスも「REST操作バインディング」ダイアログを使用します。これらの手順は、「Service BusのRESTサービスの作成方法」の手順6を参照してください。
注意:
操作を作成した方法、および操作を作成しているのか更新しているのかによって、次に説明するフィールドの一部は編集できない場合があります。
REST操作を作成または構成するには:
「RESTサービスの作成」ダイアログで、編集する操作をダブルクリックします。
「REST操作バインディング」ダイアログが表示されます。
新しい操作を作成している場合は、その操作の名前と必要に応じて説明を入力します。
必要に応じて「リソース」リストから新しいリソースを選択します。
「HTTP動詞」リストから、使用するHTTPメソッドを選択します。
リクエストのスキーマを定義するには、次のいずれかを実行します。
「スキーマ・ファイルを参照」をクリックして、その操作のXMLスキーマ・タイプに移動し、これを選択します。
「ネイティブ・フォーマットのスキーマの定義」をクリックし、ネイティブ・フォーマット・ビルダーを起動してカスタムの変換を定義します。
「要素」フィールドおよびURIパラメータが、選択内容に基づいて更新されます。
「URIパラメータ」セクションで次を実行します。
「サンプルURL」ページで実行時に操作を呼び出すURLを表示するには、操作のURLを生成をクリックします。
パラメータのスタイルを変更するには、パラメータの「スタイル」列をクリックし、「問合せ」または「テンプレート」を選択します。
パラメータのデフォルト値を入力するには、更新するパラメータの「デフォルト値」列をクリックし、使用する値を入力します。
XPath式関数の追加または更新のため、式ビルダーを起動するには、更新するパラメータの「式」列をクリックし、「式ビルダー」アイコンをクリックします。式ビルダーを使用して、使用するXPath式を定義します。
パラメータを手動で追加するには、「パラメータの追加」をクリックして、表示される新しい行に値を入力します。
パラメータを削除するには、その行を選択して、「パラメータの削除」をクリックします。
「レスポンス」タブをクリックして、レスポンスを構成します。
「HTTPステータス」フィールドに、成功した操作に対して返すHTTPステータス・コードを入力します(区切りは空白による)。
「ペイロード」フィールドで、レスポンスのペイロードのタイプを選択します。
後でファイルに保存可能なサンプル・ペイロードを生成するには、「サンプル・ペイロードの生成」をクリックします。
レスポンスのスキーマを定義するには、次のいずれかを実行します。
「スキーマ・ファイルを参照」をクリックして、その操作のXMLスキーマ・タイプに移動し、これを選択します。
「ネイティブ・フォーマットのスキーマの定義」をクリックし、ネイティブ・フォーマット・ビルダーを起動してカスタムの変換を定義します。
「要素」フィールドおよびフォルト・バインディングが、選択内容に基づいて更新されます。
フォルト・バインディングを手動で追加するには、「フォルト・バインディングの追加」をクリックします。「RESTフォルト・バインディング」ダイアログで次を実行します。
フォルトの名前を入力します。
フォルトに対して返されるHTTPのステータスのリストを入力します(区切りは空白による)。
フォルトのペイロードのタイプを選択します。フォルトのサンプル・ペイロードを生成するには、「サンプル・ペイロードの生成」をクリックします。
フォルトを定義するスキーマおよび要素を選択します。
「OK」をクリックします。
フォルトのHTTPステータスまたはペイロード・タイプを更新するには、フォルト・バインディング表でこれをダブルクリックし、「RESTフォルト・バインディング」ダイアログの情報を更新します。
「REST操作バインディング」ダイアログで「OK」をクリックします。
JDeveloperで、既存のWSDLベースのプロキシ・サービス、パイプライン、分割-結合またはビジネス・サービスを、プロキシ・サービスと関連付けられたWADLドキュメントを生成するRESTサービスとして公開できます。また、RESTベースのビジネス・サービスを公開することもできます。生成されたプロキシ・サービスは、自動的に作成元のサービスにワイヤリングされます。
Service Busサービスを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コンテンツは、次のイメージのような形式でブラウザに表示されます。
