このトピックでは、SOAP ベースのウェブサービス用の API プロキシを作成する方法について説明します。Edge では 2 種類の SOAP プロキシを作成できます。一方はバックエンドの SOAP サービスに対する RESTful インターフェースを生成し、もう一方はバックエンドへの SOAP メッセージの「パススルー」を実行します。このトピックでは両方の方法について説明します。
この動画では、API プロキシ ウィザードを使用して Apigee Edge による REST サービスで SOAP サービスを調整する詳細なデモをご覧いただけます。ただし、SOAP-to-REST の変換を詳細に制御する場合は、ポリシーを使用してプロキシを構築します。詳しくは、このコミュニティ投稿をご覧ください。
SOAP ベースのサービスへの RESTful API プロキシの作成
このセクションでは、「Build a Proxy」ウィザードの「REST to SOAP to REST」オプションで RESTful SOAP API プロキシを作成する方法を説明します。
概要
「REST to SOAP to REST」オプションは、WSDL を処理して RESTful API プロキシを生成します。Edge は、サービスでサポートされているオペレーションや入力パラメータなどを WSDL から判断します。Edge は各オペレーションでどの HTTP メソッドが使用されるかを推測します。GET リクエストにはキャッシュ可能であるという利点があるため、Edge は通常、オペレーションを GET リクエストに変換します。Edge はバックエンド ターゲット エンドポイントもセットアップします。バックエンド ターゲット エンドポイントは SOAP オペレーションごとに異なることがあります。
このタイプのプロキシの場合、Edge は OpenAPI 仕様を自動生成します。この仕様を使用して API ドキュメントを作成できます。
基本的なステップ
Edge
Edge UI を使用して SOAP ベースのサービスに対する RESTful API プロキシを作成するには:
- apigee.com/edge にログインします。
- 左側のナビゲーション バーで [Develop] > [API Proxies] を選択します。
- [+Proxy] をクリックします。
- [SOAP service] をクリックします。
- [Proxy details] ページで、WSDL ファイルを指定します。
フィールド 説明 WSDL ファイルを提供する WSDL のソースを選択します。
- ウェブアドレス（URL）から - WSDL の URL を入力または貼り付けます。
- パソコンから - ローカル ディレクトリから WSDL ファイルをアップロードします。依存関係がある場合は、複数のファイルをアップロードできます。
- [Validate] をクリックして、WSDL を検証します。
- 次のプロキシの詳細を入力します。
フィールド 説明 名前 API に表示される名前。英数字、ダッシュ（-）、アンダースコア（_）を指定します。 ベースパス API プロキシの http(s)://[host] アドレスの後に表示される URI フラグメント。Edge は、ベースパス URI を使って、受信リクエスト メッセージの照合と正しい API プロキシへのルーティングを行います。
注: デフォルトでは、API プロキシのベースパスは、すべて小文字に変換された
Nameフィールドに指定された値になります。ベースパスの後ろには、追加のリソース URL があります。次に、クライアントが API プロキシを呼び出すために使用する完全な URL 構造を示します。
https://[host]/base_path/conditional_flow_path注: ベースパスは一意である必要があります。同じベースパスを持つ 2 つの API プロキシをデプロイすることはできません。デプロイされた API プロキシを編集し、ベースパスを別の API プロキシのベースパスと同じ値に設定すると、Edge は保存時に API プロキシを自動的にデプロイ解除します。API プロキシを再デプロイするには、ベースパスが一意になるように編集しておく必要があります。
ベースパスでワイルドカードを使用する
プロキシを将来の変更に柔軟に対応させるために、API プロキシのベースパスで 1 つ以上の
/*/ワイルドカードを使用できます。たとえば、ベースパスを/team/*/membersにすると、新しいチームに対応するために新しい API プロキシを作成する必要なく、クライアントがhttps://[host]/team/blue/membersとhttps://[host]/team/green/membersを呼び出すことができます。/**/はサポートされていないことに注意してください。説明 （省略可）API の説明。 - [Next] をクリックします。
- ウィザードの [Common policies] ページで、次のように構成します。
- [Security: Authorization] のセキュリティ認可要件。セキュリティの追加をご覧ください。
- [Security: Browser] でのクロスオリジン リソース シェアリング（CORS）のサポート。CORS のサポートの追加をご覧ください。
- [Quota] でのバックエンド サービスを高トラフィックから保護するための割り当て。割り当てをご覧ください（パススルー認可が選択されている場合は使用できません）。
- [WSDL operations] ページで、API プロキシのタイプとして [REST to SOAP to REST] を選択します。
Edge が WSDL ファイルで「検出」したオペレーションの一覧を示す表が表示されます。ユーザーは API プロキシに組み込むオペレーションを選択して構成できます。その表の例を次の図に示します。
- プルダウンから [Port Type] を選択して、使用するオペレーションの組み合わせを指定します。WSDL では、ウェブサービスで呼び出すことができるオペレーションがポートタイプ要素で定義されています。
- 必要に応じて、オペレーションに対する REST API パスを変更します。このパスは API プロキシ URL でリソース名として使用されます。
- 必要に応じて、オペレーションに関連付けられている Verb（HTTP メソッド）を変更します。
- [Next] をクリックします。
- ウィザードの [Virtual hosts] ページで、API プロキシがデプロイされるときにバインドする仮想ホストを選択します。詳しくは、仮想ホストについてをご覧ください。
- [Next] をクリックします。
- デプロイ環境を選択し、[Create and deploy] をクリックします。
新しい API プロキシが作成され、選択した環境にデプロイされます。 - [Edit proxy] をクリックして、API プロキシの詳細ページを表示します。
Classic Edge（Private Cloud）
Classic Edge UI を使用して SOAP ベースのサービスに対する RESTful API プロキシを作成するには:
http://ms-ip:9000にログインします。ここで、ms-ip は、Management Server ノードの IP アドレスまたは DNS 名です。- 上部のナビゲーション バーで [APIs] > [API Proxies] を選択します。
- [+ API Proxy] をクリックします。
- [Build a Proxy] ウィザードで SOAP サービスを選択します。
- [Next] をクリックします。
- [Details] ページで以下の選択を行います。[WSDL] を選択したら、必ず [Validate] をクリックしてください。
フィールド 操作内容 WSDL WSDL のソースを選択します。
- URL の場合 - 使用する WSDL の URL を入力します。
- ファイルの場合 - ファイル システム上の WSDL ファイルを選択します。追加の依存ファイルがある場合はそれをすべて選択できます。
- サンプル URL の場合 - 一般公開されているウェブサービスの WSDL のリストから選択します。これらは Edge の SOAP/API プロキシ機能を試すのに便利です。
Proxy Name 作成するプロキシの名前です。
Proxy Base Path API プロキシの http(s)://[host] アドレスの後に表示される URI フラグメント。Edge は、ベースパス URI を使って、受信リクエスト メッセージの照合と正しい API プロキシへのルーティングを行います。
注: デフォルトでは、API プロキシのベースパスは、すべて小文字に変換された
Nameフィールドに指定された値になります。ベースパスの後ろには、追加のリソース URL があります。次に、クライアントが API プロキシを呼び出すために使用する完全な URL 構造を示します。
https://[host]/base_path/conditional_flow_path注: ベースパスは一意である必要があります。同じベースパスを持つ 2 つの API プロキシをデプロイすることはできません。デプロイされた API プロキシを編集し、ベースパスを別の API プロキシのベースパスと同じ値に設定すると、Edge は保存時に API プロキシを自動的にデプロイ解除します。API プロキシを再デプロイするには、ベースパスが一意になるように編集しておく必要があります。
ベースパスでワイルドカードを使用する
プロキシを将来の変更に柔軟に対応させるために、API プロキシのベースパスで 1 つ以上の
/*/ワイルドカードを使用できます。たとえば、ベースパスを/team/*/membersにすると、新しいチームに対応するために新しい API プロキシを作成する必要なく、クライアントがhttps://[host]/team/blue/membersとhttps://[host]/team/green/membersを呼び出すことができます。/**/はサポートされていないことに注意してください。説明 プロキシの簡単な説明。 - [Next] をクリックします。
- [WSDL] ページで、API プロキシのタイプとして [REST to SOAP to REST] を選択します。
Edge が WSDL ファイルで「検出」したオペレーションの一覧を示す表が表示されます。ユーザーは API プロキシに組み込むオペレーションを選択して構成できます。その表の例を次の図に示します。
- [Port Type] 列で、使用するオペレーションの組み合わせを選択します。WSDL では、ウェブサービスで呼び出すことができるオペレーションがポートタイプ要素で定義されています。
- 必要に応じて、オペレーションに関連付けられている [HTTP Method] を変更します。
注: Edge は、各オペレーションで使用する HTTP メソッドとして「最適なものを推測」します。GET リクエストはキャッシュ可能であるため、通常は GET が優先されます。
- 必要に応じて、オペレーションに対する REST API パスを変更します。このパスは API プロキシ URL でリソース名として使用されます。
- ウィザードの残りの部分をクリックして、セキュリティを追加し、仮想ホストを選択し、デプロイ環境を選択します。
- [Build] ページで [Build and Deploy] をクリックします。Edge は、WSDL に基づいて新しい API プロキシを生成してデプロイします。
- 新しい API プロキシの概要ページに移動します。WSDL ファイルで検出されたオペレーションに基づいて、一連のリソースが構築されていることがわかります。
プロキシの [Overview] ページの [Resources] リストには、新しい API、その操作、パラメータの詳細な説明が表示されています。この表現は API のリファレンス ドキュメントと見なすことができます。Edge は API モデルのこのビューを自動的に生成します。リソースを展開すると、その説明とパス情報を確認できます。
最終的なプロキシについて
Edge が WSDL に基づいて生成した API プロキシは、実際には、データの変換、変数の抽出と設定、メッセージの操作などを行うためのポリシーが含まれている複雑なフローです。WSDL に基づくプロキシを生成したら、できあがったフローを API 管理 UI の「Develop」ビューで確認してください。 このビューでは、具体的にどのポリシーが追加されたのかがわかります。
たとえば、リクエスト側では、AssignMessage ポリシーを使用してターゲット URL が設定されています。応答側では、ポリシーを実行して、レスポンスを XML から JSON に変換し、レスポンスの SOAP ボディー部分から変数を抽出し、レスポンス メッセージを設定します。プロキシを作成すると、このようなポリシー（など）が自動で追加されます。
OpenAPI 仕様: このプロキシの自動生成された OpenAPI 仕様を表示するには、http(s)://[proxy_domain]/[proxy_base_path]/openapi.json にアクセスします。ただし、XML スキーマの一部のルールは OpenAPI 仕様で表現できないため、正確には変換されないことがあります。
SOAP ベースのサービスへのパススルー プロキシの作成
このセクションでは、[Create New Proxy] ダイアログの [Pass-Through Proxy] オプションを使用してパススルー プロキシを作成する方法について説明します。
概要
[Pass-Through Proxy] オプションを使用すると、リクエストに含まれている SOAP メッセージをそのままバックエンド サービスに渡すプロキシを作成できるため、SOAP ベースのウェブサービス用のプロキシを作成するのが非常に容易になります。その裏で、Edge が変換やその他のフロー アクティビティをすべて自動で処理します。たとえば、リクエストが JSON 形式だった場合、Edge は適切な名前空間を使用して有効な XML SOAP メッセージに変換してからサービスに POST します。同様に、サービスが XML ベースの SOAP レスポンスを返した場合、Edge はそれを JSON に変換してからクライアントに返します。さらに、Edge は、SOAP オペレーションごとに異なる可能性があるバックエンド ターゲット エンドポイントをセットアップします。
このタイプのプロキシの場合、Edge は WSDL をホストし、ユーザーがアクセスできるようにプロキシ内のフローを作成します。Edge がホストする WSDL へのこのアドレス http(s)://[proxy_domain]/[proxy_base_path]?wsdl が、プロキシを介して SOAP サービスを呼び出すクライアントの新しいサービス エンドポイントの URL になります。
基本的なステップ
Edge
Edge UI を使用して SOAP ベースのサービスへのパススルー プロキシを作成するには:
- apigee.com/edge にログインします。
- 左側のナビゲーション バーで [Develop] > [API Proxies] を選択します。
- [+Proxy] をクリックします。
- [SOAP service] をクリックします。
- [Proxy details] ページで、WSDL の詳細を指定します。
フィールド 説明 WSDL WSDL のソースを選択します。
- ウェブアドレス（URL）から - WSDL の URL を入力または貼り付けます。
- パソコンから - ローカル ディレクトリから WSDL ファイルをアップロードします。依存関係がある場合は、複数のファイルをアップロードできます。
名前 API プロキシの名前。
ベースパス ユーザーの API プロキシの http(s)://[host] アドレスの後ろにある URI フラグメントです。Edge は、ベースパス URI を使って、受信リクエスト メッセージの照合と正しい API プロキシへのルーティングを行います。
注: API のバージョニングに関する Apigee の推奨事項については、『ウェブ API 設計: ミッシング リンク』電子ブックのバージョニングをご覧ください。
ベースパスの後ろには、追加のリソース URL があります。次に、クライアントが API プロキシを呼び出すために使用する完全な URL 構造を示します。
https://[host]/base_path/conditional_flow_path注: ベースパスは一意である必要があります。このプロキシを後で編集し、そのベースパスを別の API プロキシと同じになるように設定した場合、この API プロキシは保存時に自動的にデプロイ解除されます。再デプロイする前にベースパスを編集する必要があります。
ベースパスでのワイルドカードの使用
プロキシを将来の変更に柔軟に対応させるために、API プロキシのベースパスで 1 つ以上の
/*/ワイルドカードを使用できます。たとえば、ベースパスを/team/*/membersにすると、新しいチームに対応するために新しい API プロキシを作成する必要なく、クライアントがhttps://[host]/team/blue/membersとhttps://[host]/team/green/membersを呼び出すことができます。/**/ はサポートされていないことに注意してください。注: API プロキシのベースパスは、[Base Path] フィールドのコンテンツを明示的に編集しない限り、[Name] フィールドに指定された値がすべて小文字に変換されたものになります。
説明 （省略可）API の説明。 - [Next] をクリックします。
- ウィザードの [Common policies] ページで、次のように構成します。
- セキュリティ認可要件。セキュリティの追加をご覧ください。
- クロスオリジン リソース シェアリング（CORS）のサポート。CORS のサポートの追加をご覧ください。
- バックエンド サービスを高トラフィックから保護するための割り当て。割り当てをご覧ください（パススルー認可が選択されている場合は使用できません）。
- 収益化を有効にしている組織での収益化制限の適用。API プロキシに収益化制限を適用するをご覧ください。
- [WSDL] ページで、API プロキシのタイプとして [Pass-Through SOAP] を選択します。
- プルダウンから [Port Type] を選択して、使用するオペレーションの組み合わせを指定します。WSDL では、ウェブサービスで呼び出すことができるオペレーションがポートタイプ要素で定義されています。
- [Next] をクリックします。
- ウィザードの [Virtual hosts] ページで、API プロキシがデプロイされるときにバインドする仮想ホストを選択します。詳しくは、仮想ホストについてをご覧ください。
- デプロイ環境を選択し、[Create and deploy] をクリックします。
新しい API プロキシが作成され、選択した環境にデプロイされます。 - [Edit proxy] をクリックして、API プロキシの詳細ページを表示します。
Classic Edge（Private Cloud）
Classic Edge UI を使用して SOAP ベースのサービスへのパススルー プロキシを作成するには:
http://ms-ip:9000にログインします。ここで、ms-ip は、Management Server ノードの IP アドレスまたは DNS 名です。- 上部のナビゲーション バーで [APIs] > [API Proxies] を選択します。
- [+ API Proxy] をクリックします。
- [Build a Proxy] ウィザードで SOAP サービスを選択します。
- [Next] をクリックします。
- [Details] ページで以下の選択を行います。[WSDL] を選択したら、必ず [Validate] をクリックしてください。
フィールド 操作内容 WSDL WSDL のソースを選択します。
- URL の場合 - 使用する WSDL の URL を入力します。
- ファイルの場合 - ファイル システム上の WSDL ファイルを選択します。追加の依存ファイルがある場合はそれをすべて選択できます。
- サンプル URL の場合 - 一般公開されているウェブサービスの WSDL のリストから選択します。これは Edge の SOAP/API プロキシ機能を試すのに便利です。
Proxy Name 作成するプロキシの名前です。
Proxy Base Path Proxy Base Path は、この API プロキシによってエクスポーズされている API を一意に識別する URI フラグメントです。API サービスでは、この Base Path URI を使用して、受信リクエスト メッセージを照合し、適切な API プロキシにルーティングします（ベースパスは API のドメインに追加され、組織名と API プロキシがデプロイされている環境に基づいて自動的に生成されます）。プロジェクト名にバージョン番号を含めることをおすすめします（例: /v1/delayedstockquote）。これにより、コンシューマ アプリがこの API を呼び出す方法が決まります。注: プロキシ ベースパスは、[Proxy Base Path] フィールドのコンテンツを明示的に編集しない限り、[Proxy Name] に指定された値がすべて小文字に変換されたものになります。
説明 プロキシの簡単な説明。 - [Next] をクリックします。
- [WSDL] ページで、API プロキシのタイプとして [Pass-Through SOAP] を選択します。
注: 各 WSDL 操作とその対応する SOAP ペイロードの一覧を示す表が表示されます。これは、バックエンドの SOAP サービスにパススルーされるペイロードです。
- [Port Type] 列で、使用するオペレーションの組み合わせを選択します。WSDL では、ウェブサービスで呼び出すことができるオペレーションがポートタイプ要素で定義されています。
- ウィザードの残りの部分をクリックして、セキュリティを追加し、仮想ホストを選択し、デプロイ環境を選択します。
- [Build] ページで [Build and Deploy] をクリックします。Edge は、WSDL に基づいて新しい API プロキシを生成してデプロイします。
最終的なプロキシについて
Edge が WSDL に基づいて生成したパススルー プロキシは、実際には、データの変換、変数の抽出と設定、メッセージの操作などを行うためのポリシーが含まれている複雑なフローです。パススルー プロキシを生成したら、出来上がったフローを API 管理 UI の「Develop」ビューで確認してください。 このビューでは、具体的にどのポリシーが追加されたのかがわかります。
たとえば、次の図はパススルー プロキシの Target Endpoint Preflow 部分です。要求側では、ターゲット URL の設定に AssignMessage ポリシーが使用されています。応答側では、ポリシーを実行して、レスポンスを XML から JSON に変換し、レスポンスの SOAP ボディー部分から変数を抽出し、レスポンス メッセージを設定します。プロキシを作成すると、このポリシー（および他のポリシー）が自動的に追加されます。
Edge-hosted WSDL: このタイプのプロキシ用に生成された、Edge がホストする WSDL を確認するには、http(s)://[proxy_domain]/[proxy_base_path]?wsdl にアクセスします。
高度な SOAP-to-REST プロキシの開発
前のセクションでは、Edge で API プロキシ ウィザードを使用した SOAP-to-REST API プロキシの作成について説明しました。ただし、SOAP-to-REST の変換に対してよりきめ細かい制御が必要な場合は、ウィザードで提供される自動化をバイパスし、必要とする動作のためのポリシーを手動で追加および構成することによってプロキシを構築できます。詳しくは、このコミュニティ投稿をご覧ください。