Web サービス呼び出しの追加 (REST-スタイル)

www.altova.com このトピックを印刷 前のページ 1つ上のレベル 次のページ

ホーム >  Web サービスの呼び出し >

Web サービス呼び出しの追加 (REST-スタイル)

ジェネリックな ( WSDL-スタイルではない) Web サービスには "REST" (また、通常 "RESTful" または REST-スタイル Web サービス)と称されるアーキテクチャのスタイルに従う Web サービスの大きなカテゴリが含まれます。ジェネリックな HTTP Web サービスでは、メッセージの本文は、通常カスタムリクエストまたはレスポンスです。MapForce は以下の種類のリクエスト、または、レスポンスボディをサポートします: JSON、XML、プロトコルバッファー、カスタム MIME 型を持つ構成されていないボディ。ですから、MapForce パースペクティブからは、Web サービスを呼び出す必要条件はリクエストの型により異なります:

 

XML または JSON リクエスト、または、レスポンスの場合、 MapForce は JSON、XML、または、 DTD スキーマとしてのリクエスト、または、レスポンスを必要とします。 MapForce は有効なスキーマレファレンスを持つ XML ファイルを構造として受け入れます。 Web サービスの構造は、 XML または JSON スキーマとしてのサービスプロバイダ、または、WADL などの正式な言語、または、人間が読解することのできる仕様により公開することができます。リクエスト/レスポンスの XML または JSON スキーマが既に存在する場合、 Web サービスの呼び出しを簡単に行うことができます。 WADL ファイルとしての Web サービスが存在する場合、WADL ファイルからインポートし、手動で調整することができます。  WADL は JSON 構造を定義する標準的な方法を提供しません。 XML 構造を定義する方法のみを提供します。 最後に、スキーマファイルが存在せず、 XML または JSON インスタンスファイルのみが存在する場合、 XMLSpy  (http://www.altova.com/ja/xmlspy.html) を使用してスキーマを作成、または、生成することができます。 必要であれば、 インスタンスファイルを XML から JSON  に、変換、またはその逆に変換することも可能です。
プロトコルバッファーリクエスト、または、レスポンスの場合、プロトコルバッファー バイナリファイルを説明する .proto ファイルが必要とされます。このシナリオでは、Web サービスのボディをプロトコルバッファーコンポーネントからマップすることができます。 詳細に関しては、サンプル: プロトコルバッファーからデータを読み取るサンプル: プロトコルバッファーにデータを書き込むを参照してください。
レスポンス構造が柔軟で、特定のスキーマに制限されていない個所でWeb サービスを呼び出す、または、リクエストすることができます。 このような場合、you can use MapForce built-in mime 関数を使用して Web サービスに送信される生メッセージボディを作成、または、Web サービス (MIME エンティティ) により返される MIME エンティティのマッピングを処理することができます。

 

ジェネリックな Web サービスに呼び出しを追加する方法

1.「挿入」 メニューから、 Web サービス関数」 をクリックします。(または、「Web サービス関数の挿入」 ic-wsdl-func ツールバーボタン をクリックします)。
2.サービスの定義から、 「手動」 を選択します。

mf_ws_01

3.任意で、 サービスを説明する WADL ファイルが存在する場合 「WADL ファイルからインポート」をクリックし、  ファイルを選択します ( WADL ファイルから Web サービス情報をインポートするを参照)。
4.MapForce が Web サービスを呼び出すために使用する HTTP リクエストメソッドを選択します。既存のリストから値を選択するか、または、リクエストメソッドの名前を入力します。 HTTPメソッドは大文字と小文字を区別します。
5.Web サービスの URL を入力します。Web サービスの URLがパラメーターを使用する場合、以下に注意してください:
a.Web サービスを "テンプレート" または 「マトリックス」 スタイルのパラメーターで呼び出す場合、パラメーターを中かっこで囲みます。例えば: http://example.org/api/products/{id} 「パラメーター」 テーブル 内で各パラメーターの実際の設定を定義します。ランタイムで、  MapForce は、中かっこ内のパラメーター名を処理し、実際の値を含む最終 URL を生成します。
b. "クエリ" URL パラメーターで Web サービスを呼び出す場合、 (例えば、 http://example.org/api/products?sort=asc&category=1&page=1)、 URL テキストボックス内にクエリの部分を入力せず、「パラメーター」 テーブル内でのみパラメーターを定義します。

サンプルに関しては、 Web サービスパラメーターの定義.を参照

6.任意で、タイムアウト の項目に、サーバーが応答しない場合、接続がタイムアウトする秒数を入力します。
7.HTTP メソッドが必要な場合、またはボディの部分(XML、 JSON および他)を返す場合、 「構造」 の下の「編集」ボタンをクリックし、ボディの部分の スキーマを参照します ( Web サービスのレスポンスとリクエストの構造の定義を参照)。
8.Web サービスのパラメーターを定義します。任意で、 URL からインポート」 をクリックして、 Web サービスのサンプル URL からパラメーターをインポートし、 「パラメーター」 テーブルを自動的に作成します ( URL ファイルから Web サービスパラメーターをインポートするを参照)。 パラメーターを URL からインポートした後、「パラメーター」 テーブルのコンテンツを必要があれば変更することができます。更に詳しい情報に関しては、 Web サービスパラメーターの定義を参照してください。

 

メモ:カスタムリクエストヘッダーを指定するには、 スタイル 「ヘッダー」 を持つパラメーターを、パラメーター名がヘッダー名に対応し、また、パラメーター値がヘッダーの値に対応する箇所に追加します。更に、マッピング自身からヘッダーのリクエストの値を提供する場合、パラメーター型を"マップ可能に設定します。

 

9.Web サービスが HTTP 認証 または 証明書-ベースのセキュリティを使用する場合、 「HTTP セキュリティ設定」 の下の「編集」ボタンをクリックし、必要とされるフィールドに入力します ( HTTP セキュリティの設定を参照)。

 

「OK」 をクリックした後、新規の Web サービス コンポーネントがマッピングエリアに追加されます。 例えば、下のマッピングは、GET リクエストを使用して、 ID により製品を取得するために Web サービス を呼び出します。この特別な例では、 HTTP リクエスト内で与えられた  ID は定数の値 「2」 を持ちます。しかしながら、 マッピングのパラメーターにもなることができます。 または、 MapForce によりサポートされる全てのコンポーネントにより与えられます。id パラメーターに加え、 リクエストは、 Accept: text/json を含みます。「ヘッダーパラメーター」を使用して、リクエストヘッダーを Web サービスパラメーターの定義で説明される通り設定します。

mf_ws_02

上記のマッピングは構成されており3つの出力が存在します:

 

1.Web サービス呼び出しにより返される HTTP ステータスコード
2.コンマで区切られた値としてのレスポンスヘッダー
3.レスポンス JSON 構造

 

これはデモを目的としたものです。1つの出力のみを持つマッピングをデザインすることもできます。例えば、 HTTP ステータスコードのみなど。 上記のようにマッピングに複数の出力が存在する場合、マッピングを作動する前に、その特定の出力へのコンポーネントの「プレビュー」 ic-preview-buttondown ボタンを押して確認することができます。

 

Web サービスコンポーネントは2つの部分から構成されています: リクエストレスポンスリクエスト パートにより、 Web サービスへマッピングからデータを提供することができ、レスポンス 部分により、 Web サービスにより返されたデータにアクセスすることができ、他のフォーマットにマップすることができます。リクエストとレスポンスの構造は、パラメータ、および、 excel1-compicon ボタンをクリックして定義されたリクエストとレスポンス構造により異なります。上記の Web サービスの呼び出しでは、リクエストボディの構造は設定されていませんが、 レスポンスボディの構造は、 JSON に設定されています。レスポンスボディの構造は、実際の JSON ファイルに Web サービスの結果をマップできるようにします。

 

(適用できる場合)リクエストパラメーター を持つ Web サービスを呼び出す場合、(例えば、 XML または JSON ファイルなどの)  MapForce によりサポートされるコンポーネントと 「リクエスト」 パート間にマッピング接続を描きます。同様に Web サービスにより返されたデータを他の書式にマップするには、 MapForce によりサポートされている レスポンスパートと他のコンポーネント型にマッピング接続を描きます。MapForce の初心者の場合は、マッピング接続の描き方の説明を確認してください。接続との作業を参照してください。

 

(「コンテンツ」で開始しない) 追加ヘッダーの場合 Web サービスにより返されるレスポンスヘッダーもマップ可能です。ヘッダーの値は2つの子アイテムを含む 「ヘッダー」 ( ic_http_headers )と呼ばれるアイテムを介してヘッダー値は Web サービスコンポーネント上で使用することができます: 「名前」と「値」。この構造はシーケンスとしての役割を果たし、 Web サービスにより返されたヘッダーの数からのデータをマップすることができます。レスポンスヘッダーからのデータを MapForce によりサポートされる他の書式にマップするには、 「ヘッダー」 構造ノードをマッピング内のターゲットシーケンスに接続します。 例えば、「ヘッダー」 シーケンス (とその子) を CSV コンポーネントの 「行」 シーケンス (とその子) に接続する場合、ヘッダーは CSV ファイル内の行に対応します。

 

Body mf_ic_body は、 HTTP メッセージのエンティティボディを表示しています。このレベルでのデータはエンコードされたバイナリですので、直接のインタラクションは MapForce mime 関数を必要とします。Web サービスが XML または JSON などの構造化されたデータを期待または返す場合、通常 ボディ とインタラクトする必要はありません。ボディ への直接のマッピングデータ、または、ボディ からのマッピングデータは、構造化されていないコンテンツを期待する、または、返す Web サービスを呼び出す場合のみ必要となります。

 

デフォルトでは、ボディ アイテムは HTTP ステータスコードが 200  から 299 への範囲の場合、結果を解析するように構成されています。これは、マッピングが 299 より多きステータスコードのためにエラーを返すことを意味します。また、レスポンスを解析できない場合、または、 Web サービスが接続エラー、または、DNS 精度の問題により呼び出されない場合にエラーが返されます。

 

一部の場合では、 HTTP ステータスコードが 299 より大きい場合でも、マッピングがエラーをスローしないことがあります。これを行うには、レスポンス ボディ の横の excel1-compicon ボタンをクリックし、 HTTP ステータスコードの範囲を変更します。または、 複数の レスポンス ボディ アイテムを作成することができます。複数の ボディ アイテムの作成は、 Web sサービスにより返される HTTP ステータスコードに従いマッピングを条件づけて処理する場合に役に立ちます。これを行うには、レスポンスパートの ボディ mf_ic_body を右クリックし、「前/後にボディノードを追加する」 をコンテキストメニューから選択します。例えば、2つの ボディ アイテムを作成することができます:

 

1.全てのステータスコード ボディ mf_ic_body は成功の範囲 (200 から 299) で、 excel1-compicon ボタンをクリックして構成することができます。このシナリオのために、ボディ 構造を通常、 JSON および XML ファイルなどの成功する出力にマップします。
2.他のステータスコードのための ボディ mf_ic_body は 300 と 599 の範囲内です。Web サービスの一部は、ボディ内のエラーステータスコードについての追加の情報を提供する可能性があります。エラーの理由を確認するには、エラーのある ボディ を(例えば、文字列などの)成功する出力以外にマップすることもできます。

 

複数の ボディ アイテムが存在する場合、MapForce はアイテムを上から下に評価します。優先順位を変更するには、 ボディ アイテムを右クリックし、「上に移動」 または 「下に移動」 をコンテキストメニューから選択します。HTTP レスポンスを条件付きで処理するための詳細に関しては、HTTP レスポンスを条件付きで処理するを参照してください。

 

ジェネリックな HTTP Web サービスの呼び出しを含むマッピングは、他のマッピング同様に実行することができます。具体的には以下の通りです:

 

MapForce を使用して、 出力 タブをクリックして手動で行います。この場合、マッピングの呼び出し結果はすぐに 「出力」 ペインで使用することができるようになります。上記のサンプル内のようにマッピングに複数の出力コンポーネントが存在する場合、マッピングに戻る前に希望するコンポーネント上の Preview「プレビュー」 ic-preview-buttondown ボタンをクリックします。
コマンドライン、または、MapForce Server (https://www.altova.com/ja/mapforce-server) と共に、コマンドラインまたは API 呼び出しを使用します。これは、マッピングをマッピング実行可能ファイルに最初にコンパイルすることを必要とします (MapForce Server 実行可能ファイルにマッピングをコンパイルするを参照してください)。
FlowForce Server コントロール下で作動する MapForce Server を使用した再帰的なジョブとして (https://www.altova.com/ja/flowforceserver)。 マッピングを FlowForce Server にデプロイする も参照してください)。

 

ジェネリックな Web サービスの呼び出しの作成方法のステップバイステップのサンプルに関しては、以下を参照してください:

 

例: REST-スタイル Web サービスの呼び出し
例: RSS フィードからのデータのマッピング

(C) 2019 Altova GmbH