外部Webサービスの呼出し

「外部Webサービスの呼出し」プロセッサは、プロセッサ構成情報、入力データおよびペイロード構造(ユーザー指定)を使用して、標準のHTTP/HTTPS接続を介してEDQサーバーから接続できる任意のREST Webサービスを呼び出し、このプロセッサの出力属性に対する結果を解析します。これは、スタンドアロン・プロセッサとして使用するか、他のプロセッサと組み合せて使用できます。たとえば、データを取得、挿入または更新するOracle SaaSアプリケーションREST Webサービスを呼び出します。

次の表に、「外部Webサービスの呼出し」プロセッサの構成オプションを示します。

構成	説明
入力属性	入力属性は、文字列、数値、文字配列または番号配列です。リクエスト・ペイロードでこれらの属性値を使用するか、または(あるいは同時に) WebサービスURLやHTTPヘッダーでそれらをかわりに使用できます(「拡張」タブから)。 注意: プロセッサを使用するには少なくとも1つの入力属性を指定する必要があります。
出力属性	出力属性には次の2つのタイプがあります。これらは次のとおりです: 固定出力属性 - これらの属性は、プロセッサにデフォルトで存在し、削除できません。固定出力属性は次のとおりです。 HTTPレスポンス・コード - Webサービスから受信されるHTTPレスポンス・コード(200や400など)。 HTTPレスポンス・メッセージ - プロセッサが構成済のWebサービスを呼び出すことができない場合に受信される標準のHTTPレスポンス。 Webサービスのエラー・メッセージ - プロセッサによるWebサービス呼出しが失敗した場合に受信されるWebサービス固有のエラー・メッセージ。 動的出力属性 - これらの出力属性は、プロセッサで構成され、その値はWebサービスからのレスポンスを解析することで作成されます。詳細は、「レスポンス」タブを参照してください。
オプション	次のオプションは「オプション」タブから使用できます。 メソッド - リクエストを処理するためのメソッドのタイプをこのドロップダウン・メニューから選択します。次のオプションから選択できます。 GET POST PUT DELETE PATCH デフォルトでは、POSTメソッドが選択されます。 URL - WebサービスのURL。置換構文を使用して、URLの一部として入力属性値を指定できます。 たとえば、http://URL/abc?ProductId=${Id}では、Idが入力属性で、実行時に${Id}は入力属性のIDの値に置換されます。 複数レコードのリクエスト/レスポンスか。 - このオプションを「はい」に設定すると、複数のレコードを送信して複数のレスポンスを取得できます。デフォルトでは、このオプションは「いいえ」に設定されます。 注意: このオプションは、POST、PUTおよびPATCHメソッドでのみ有効です。 「複数レコードのリクエスト/レスポンスか。」を「はい」に設定する場合、呼び出しているWebサービスが複数レコードのリクエストおよびレスポンスをサポートしている必要があります。 バッチ・レコード - 注意: 「バッチ・レコード」オプションは、「複数レコードのリクエスト/レスポンスか。」オプションが「はい」に設定されている場合にのみ有効です。 これにより、Webサービス呼出しごとに送信するレコードの数を指定します。デフォルトでは、このオプションは50に設定されます。 認証が必要か - このオプションは、WebサービスのBasic認証を使用する際に役立ちます。デフォルトでは、このオプションは「いいえ」に設定されます。このオプションを「はい」に設定すると、次の「ユーザー名」および「パスワード」フィールドが有効になります。 ユーザー名 - このオプションでは、前に選択したWebサービスの認証フィールドのユーザー名を入力できます。 パスワード - このオプションでは、Webサービスの認証に使用される、前に指定したユーザー・アカウントのパスワードを指定します。
リクエスト	「リクエスト」タブには、リクエスト・ペイロードが含まれます。その値は、「オプション」タブで実行した構成に基づいて大幅に変化します。この項では、次のコンポーネントについて説明します。 選択された属性 - このテキスト・ボックスには、選択したすべての入力属性が表示されます。 メソッドをGETまたはDELETEに設定した場合、「複数レコードのリクエスト/レスポンスか。」および「Jsonペイロード構造」オプションは無効になります。 「オプション」タブでメソッドをPOST、PUTまたはPATCHに設定し、「複数レコードのリクエスト/レスポンスか。」オプションを「いいえ」に設定した場合、次のオプションが表示されます: Jsonペイロード構造 - このオプションにより、ペイロード構造を入力できます。 例 - POST、PUTまたはPATCHリクエストのJSONペイロードの一部として入力属性値を送信するには、有効なJSONメッセージ構造内で${InputAttributeName}という構文を使用します。JSONでは、数値に引用符は不要ですが、文字列値には必要であることに注意してください。たとえば、数値型のId属性と文字列型のName属性を送信するには、{ "Id" : ${Id}, "Name" : "${Name}" }という構文を使用します 「オプション」タブでメソッドをPOST、PUTまたはPATCHに設定し、「複数レコードのリクエスト/レスポンスか。」オプションを「はい」に設定した場合、次のオプションが表示されます。 JSONメッセージ構造 - このオプションにより、ペイロード・オプションのメッセージ構造を構成できます。 注意: これを空白のままにすると、リクエスト・ペイロードは、レコード構造オプションに従って構成されたレコードの単純配列になります。それ以外の場合、メッセージの外部パートを指定し、このレコード配列で置換するために$records$を使用できます。 これは、実行時にJSONレコード構造によって置換される必須テンプレート$records$を使用します。 JSONレコード構造 - このオプションにより、ペイロードの特定の情報を構成できます。選択した入力に対してテンプレート${InputSelection}を使用し、実行時に入力値を渡すためにペイロードで使用できます。 例 - { "Id" : ${Id}, "Name" : "${Name}" } 「サンプル・ペイロードの生成」ボタンをクリックすると、このオプションのサンプル構成を取得できます。 例: 「JSONメッセージ構造」を指定した場合: JSONメッセージ構造 - {"ProductName":"edq","Record":$records$} JSONレコード構造 - {"ID":${id},"Name":"${Name}"} バッチ・レコード - 3 Webサービスに送信される実際のリクエスト・ペイロード - {"ProductName":"edq","Record":[ {"ID":1,"Name":"name1"},{"ID":2,"Name":"name2"},{"ID":3,"Name":"name3"}]} 「JSONメッセージ構造」が空白のままの場合: JSONメッセージ構造 - <空白のまま> JSONレコード構造 - {"ID":${id},"Name":"${Name}"} バッチ・レコード - 3 Webサービスに送信される実際のリクエスト・ペイロード - [ {"ID":1,"Name":"name1"},{"ID":2,"Name":"name2"},{"ID":3,"Name":"name3"}]
レスポンス	「レスポンス」タブは、Webサービス・レスポンスから出力属性を作成する際に役立ちます。これは、属性の作成時に、構成に従ってレスポンス・ペイロードから目的の値を読み取ります。これは、次の3つの属性を含みます。これらは次のとおりです: 名前 - 作成された出力属性の名前。 タイプ - 作成された出力属性のデータ型。これは、文字列、数値、文字配列または番号配列です。 ペイロード変数 - このオプションは、レスポンス・ペイロードの出力属性パスを示します。 Webサービスのレスポンス・ペイロード構造に従って、任意の数の出力属性を作成できます。 属性を作成するには、「レスポンス」タブの左下隅にある「追加」アイコンをクリックします。「属性の追加」ダイアログが表示され、属性名の入力、型(文字列、文字配列、数値または番号配列)の選択、ペイロード変数名の入力、およびレベル(レコードまたはメッセージ)の選択を行うことができます。 注意: 「レベル」オプションは、次の設定を行った場合にのみ有効化され、表示されます メソッドをPOST、PUTまたはPATCHに設定 「複数レコードのリクエスト/レスポンスか。」オプションを「はい」に設定(「オプション」タブ)。 「レベル」が「メッセージ」に設定された出力属性では、すべてのレコードに同じ値が割り当てられます。 レベルおよびペイロード選択の属性タイプの例は、次のとおりです。 レベル選択の例 レスポンス・ペイロードが{ "status":"ok","records":[{"Name":"John","Id":1},{"Name":"Michael","Id":12}] }の場合、出力のstatusのレベルは「メッセージ」で、出力のNameのレベルは「レコード」です。 ペイロード選択の例 レスポンス・ペイロード{"productname":"edq","details":{"type":1,"build":{"number":3,"version":"2.1.0"}}}, の場合 productnameはproductnameです typeはdetails.typeです numberはdetails.build.numberです ペイロード変数名は、実際のペイロードで指定された名前と同じである必要があります。 レコード・パス - このオプションは、複数レコードのWebサービス・レスポンスにおけるレコードのパスを示します。 注意: このオプションは、次の設定を行った場合にのみ有効化され、表示されます。 メソッドをPOST、PUTまたはPATCHに設定 「複数レコードのリクエスト/レスポンスか。」オプションを「はい」に設定(「オプション」タブ)。 例 - レスポンスがレコードの配列である場合、「レコード・パス」オプションは空白のままです([{"Name":"John","Id":1},{"Name":"Michael","Id":12}]など) レスポンスが{ "status":"ok","records":[{"Name":"John","Id":1},{"Name":"Michael","Id":12}] }の場合、レコード・パスはrecordsです レスポンスが{"status":"ok","data":{"type":1,"emprecords":[{"Name":"John","Id":1},{"Name":"Michael","Id":12}]} }の場合、レコード・パスはdata.emprecordsです
拡張	「拡張」タブでは、次のオプションを構成できます。 プロキシを使用しますか。 - プロキシ設定を構成する場合、このオプションを「はい」に設定します。デフォルトでは、これは「いいえ」に設定されます。このオプションを「はい」に設定すると、次のフィールドが有効になります。 ホスト名 - プロキシ・サーバーの名前。 ポート - リクエストをリスニングするために使用するプロキシ・サーバーのポート番号。 プロキシには認証が必要ですか。 - プロキシ認証を有効にする場合、このオプションを「はい」に設定します。 ユーザー名 - プロキシ・ユーザーの名前 パスワード - 前に構成したプロキシ・ユーザー・アカウントのパスワード タイムアウト - このオプションでは、ミリ秒単位でタイムアウト値を設定できます。任意のWebサービス・レスポンスをEDQが待機している状態で、この構成されたタイムアウト期間を超えると、レスポンスでタイムアウト・エラーが戻されます。デフォルトでは、このオプションは120000ミリ秒に設定されます。 HTTPヘッダー - このオプションでは、リクエストのHTTPヘッダー情報を構成できます。「追加」アイコンをクリックしてヘッダーの名前と値を追加するか、${ID}という形式でHTTP値に選択した入力属性をマップします(IDは入力属性です)。

「外部Webサービスの呼出し」プロセッサの拡張機能の一部は、次のとおりです。

• 配列のサポート -

  • 入力属性 -
    1. このプロセッサでは、番号配列と文字配列がサポートされます。
    2. 選択した入力配列は、{"arr" : ${array}}としてリクエスト・ペイロードで使用できます(この配列は、選択した入力属性の名前です)。
  • 出力属性 - 「レスポンス」タブで、文字配列と番号配列のタイプの出力属性を作成できます。

  例 - {"arr" : ${array}}, {"arr" : ["a", "c\"d", null]}, {"arr" : [1,2,null, 3]}。

• HTTPヘッダー情報の追加 - 複数のHTTPヘッダーを定義できます。選択した入力属性を使用して、${InputAttribute}という形式でHTTPヘッダー値に置換できます。詳細は、「拡張」タブの項を参照してください。
• 複数の出力属性の追加 - 複数の出力を作成して、レスポンス・ペイロードから値を読み取ることができます。詳細は、「レスポンス」タブの項を参照してください。

• 複数レコードの処理 - Webサービスに対する単一のリクエストで複数のレコードを送信できます。この機能は、1つのリクエストで複数のレコードをサポートするWebサービスでのみ使用できます。

  この機能でサポートされる主な使用例は2つあります。これらは次のとおりです:

  1. ペイロード全体が複数のレコードを含む構造になっている複数レコードのWebサービス。

     この使用例を処理するには、「リクエスト」タブの「JSONメッセージ構造」を空のままにする必要があります。したがって、リクエストされたペイロードは、レコードの配列になります。

  2. 外部JSON構造の複数レコード構造および追加属性。

     この使用例を処理するには、「リクエスト」タブの「JSONメッセージ構造」で特別なテンプレートの$records$を使用する必要があります。

  例 -

  JSON Message Structure : 
  
  {
     "company":"Oracle",
      "data_type":"product_info",
      "records":$records$
  }
  
  JSON Record Structure :
  
  {
      "product_id":${id},
      "product_name":"${name}"
  }
  
  

  入力データ{(id=11,name=product1), (id=21,name=product2)}の最終リクエスト・ペイロードは、次のようになります。

  {
     "company":"Oracle",
      "data_type":"product_info",
      "records": [{"id":11,"name":"product1"},{"id":21,"name":"product2"}]
  }

  注意:

  JSONレコード構造で使用されるIdおよびnameは、プロセッサの選択済入力属性です。

  複数レコード固有の設定:

  • オプション - メソッドPOST、複数レコードのリクエスト/レスポンス = はい、バッチ・カウント(最小値50)
  • リクエスト - 「JSONメッセージ構造」および「JSONレコード構造」
  • レスポンス -
    1. Webサービスのレスポンス・ペイロード構造に従って、出力を作成します(詳細は、前述の「レスポンス」の項を参照してください)
    2. レコード・パス - レスポンス・ペイロードのレコードのパス。レスポンス・ペイロードがレコードの配列の場合、空白のままにできます。

    注意:

    N:Nリクエストがサポートされますが、この場合、リクエスト・ペイロードで送信されるNレコードに対して、レスポンス・ペイロードにNレコードが含まれる必要があります。
• URLでのパラメータ置換 - 選択した入力属性を使用して、WebサービスURLのパラメータ値を置換できます。

  例 - http:webservice.com?Product_id=${ID} (IDは選択した入力属性)。

リクエスト・ペイロードでのNull処理

null値を含む属性は、リクエスト・ペイロードに置換される場合、特別な方法で処理されます。3つのケースがあります。

1. 属性参照が引用符で囲まれない場合(数値、ブール値または配列値の場合)、属性はJSON値のnullに置換されます。たとえば、{ "num" : ${numval} }は、属性のnumvalがnullの場合、置換後に{ "num" : null }になります。
2. 属性参照が引用符で囲まれた値の唯一の内容である場合、引用符は削除され、置換後はJSON値のnullになります。たとえば、{ "str" : "${strval}" }は、属性のstrvalがnullの場合、置換後に{ "str" : null }になります。
3. 属性参照が引用符で囲まれた値の唯一の内容ではない場合、置換後の属性は空の文字列になります。たとえば、{ "str" : "abc${strval}def" }は、属性のstrvalがnullの場合、置換後に{ "str" : "abcdef" }になります。

例

1. この例では、「外部Webサービスの呼出し」を使用して、キャンパスの会社の詳細をフェッチします。キャンパス名がWebサービスURLの一部として送信され、Webサービスからのレスポンスには、その特定のキャンパス内で営業中の会社の詳細が含まれます。

   構成オプションは次のとおりです。

   構成オプション	値
   属性	選択した入力 名前 - キャンパス名 タイプ - 文字列
   オプション	メソッド - GET URL - http://webservice.com/companyinfo?name=${Campus Name } 複数レコードのリクエスト/レスポンス - 無効
   リクエスト	JSONペイロード構造 - 無効
   レスポンス	レスポンス・ペイロード構造 - { "Company": "Company Name", "Country”: "Country Code", "Departments":[{"id":DepartmentId,"Name":"DepartmentName"} ...] }
   出力属性	名前 = 会社名 タイプ = 文字列 ペイロード変数 = 会社 名前 = 国コード タイプ = 文字列 ペイロード変数 = 国 名前 = 部門リスト タイプ = 文字配列 ペイロード変数 = Departments.Name 名前 = 部門IDリスト タイプ = 番号配列 ペイロード変数 = Departments.Id

   Webサービス・リクエスト/レスポンス(入力あり):

   入力属性	URL	レスポンス・ペイロード
   キャンパス名 = Campus1	http://webservice.com/companyinfo?name=Campus1	{ "Company": "Oracle", "Country": "IN", "Departments":[{"id":101,"Name":"Department_1"},{"id":102,"Name":"Department_2"}, {"id":103,"Name":"Department_3"}] }

   サマリー・ビュー:

   キャンパス名	HTTPレスポンス・コード	HTTPレスポンス・メッセージ	Webサービスのエラー・メッセージ	会社名	国コード	部門リスト	部門IDリスト
   Campus1	200	OK	<Nil>	Oracle	IN	{Department_1}{Department_2} {Department_3}	{101}{102}{103}

2. この例では、「外部Webサービスの呼出し」を使用して、州の各市町村の詳細を取得します。

   構成オプションは次のとおりです。

   構成オプション	値
   属性	選択した入力: 名前 = 国 タイプ = 文字列 名前: = 状態 タイプ = 文字列 名前 = 参照ID タイプ = 数値
   オプション	メソッド - POST URL - http://webservice.com/cityinfo 複数レコードのリクエスト/レスポンス - いいえ
   リクエスト	JSONペイロード構造 { "CountryName" : "${Country}", "StateName" : "${State}", "RefId" : "${ReferenceId}" }
   レスポンス	レスポンス・ペイロード構造 - { "CountryName" : "Name", "CountryCode" : "Code", "StateName" : "State Name", "StateData" : {"id":id,"CityDetails":{"Count":count,CityList:["City1","City2", . . . . . ]}} }
   出力属性	名前 = 市区町村数 タイプ = 数値 ペイロード変数 = StateData.CityDetails.Count 名前 = 市区町村名 タイプ = 文字配列 ペイロード変数 = StateData.CityDetails.CityList

   Webサービス・リクエスト/レスポンス(入力あり):

   入力属性	URL	レスポンス・ペイロード
   国 = Country_1 州 = ST1 参照ID = 121	{ "CountryName" : "Country_1", "StateName" : "ST1", "RefId" : 121 }	{ "CountryName" : "Country_1", "CountryCode" : "CC", "StateName" : "ST1", "StateData" : {"id":221,"CityDetails":{"Count":21,CityList:["City1","City2","City3","City4"]}} }

   サマリー・ビュー:

   国名	状態	参照ID	HTTPレスポンス・コード	HTTPレスポンス・メッセージ	Webサービスのエラー・メッセージ	市区町村数	市区町村名
   Country1	State1	11	200	OK	<Nil>	21	{City1}{City2}{City3}{City4}

3. この例では、「外部Webサービスの呼出し」を使用して、製品を使用する顧客のリストを取得します。この構成では、単一のWebサービス呼出しで複数のレコードを送受信できます。単一のリクエストでNレコードが送信されると、Webサービスからの有効なレスポンスにもNレコードが含まれます。

   構成オプションは次のとおりです。

   構成オプション	値
   属性	選択した入力: 名前 = 製品名 タイプ = 文字列 名前 = コード タイプ = 数値
   オプション	メソッド - POST URL - http://webservice.com/multirecords 複数レコードのリクエスト/レスポンス - はい バッチ・レコード - 50
   リクエスト	JSONメッセージ構造 - { "Request Name" : "Product_Cus_List", "RefId" : 101, "Records" : $records$ } JSONペイロード構造 - { "ProductName" : "${ProductName}", "Product Code" : ${ code } }
   レスポンス	レスポンス・ペイロード構造 - { "Company" : "Company Name", "MetaData" : "Product Customer List", "Records" : [ {"ProductName" : "P1","Cus_List":["Cus1", "Cus2"]} . . . . . ] } レコード・パス - レコード
   属性オプション	名前 = 会社 タイプ = 文字列 ペイロード変数 = 会社 レベル = メッセージ 名前 = メタデータ タイプ = 文字列 ペイロード変数 = メタデータ レベル = メッセージ 名前 = 製品 タイプ = 文字列 ペイロード変数 = productName レベル = レコード 名前 = 顧客 タイプ = 文字配列 ペイロード変数 = Cus_List レベル = レコード

   Webサービス・リクエスト/レスポンス(5:5):

   入力属性	リクエスト・ペイロード	レスポンス・ペイロード
   製品名 = Prod1 コード = 41 製品名 = Prod2 コード = 512 製品名 = Prod3 コード = 986 製品名 = Prod4 コード = 994 製品名 = Prod5 コード = 208	{ "Request Name" : "Product_Cus_List", "RefId" : 101, "Records" : [ { "ProductName " : "Prod1", "Product Code":41}, { "ProductName " : "Prod2", "Product Code":512}, { "ProductName " : "Prod3", "Product Code":986}, { "ProductName " : "Prod4", "Product Code":994}, { "ProductName " : "Prod5", "Product Code":208} ] }	{ "Company": "Comp1", "MetaData" : "Product Customer List", "Records" : [ {"ProductName" : "Prod1","Cus_List":["P1_Cus1", "P1_Cus2", "P1_Cus3"]} , {"ProductName" : "Prod2","Cus_List":["P2_Cus1", "P2_Cus2"]}, {"ProductName" : "Prod3","Cus_List":["P3_Cus1", "P3_Cus2", "P3_Cus3"]}, {"ProductName" : "Prod4","Cus_List":["P4_Cus1", "P4_Cus2", "P4_Cus3"]}, {"ProductName" : "Prod5","Cus_List":["P5_Cus1", "P5_Cus2", "P5_Cus3", "P5_Cus4"]} ] }

   サマリー・ビュー:

   製品名	コード	HTTPレスポンス・コード	HTTPレスポンス・メッセージ	Webサービスのエラー・メッセージ	会社名	メタデータ	製品	顧客
   Prod1	41	200	OK	<Nil>	Comp1	Product Customer List	Prod1	{P1_Cus1}{P1_Cus2}{P1_Cus3}
   Prod2	512	200	OK	<Nil>	Comp1	Product Customer List	Prod2	{P2_Cus1}{P2_Cus2}
   Prod3	986	200	OK	<Nil>	Comp1	Product Customer List	Prod3	{P3_Cus1}{P3_Cus2}{P3_Cus3}
   Prod4	994	200	OK	<Nil>	Comp1	Product Customer List	Prod4	{P4_Cus1}{P4_Cus2}{P4_Cus3}
   Prod5	208	200	OK	<Nil>	Comp1	Product Customer List	Prod5	{P5_Cus1}{P5_Cus2}{P5_Cus3}{P5_Cus4}