デザイン > サービスコネクタのデザイン > オプション1: 新しいサービスコネクタの作成
  

オプション1: 新しいサービスコネクタの作成

プロパティを定義し、関数や変数を指定すると、サービスコネクタを作成できます。また、サービスコネクタと関連付けられたアクションを定義することもできます。
サービスコネクタを作成するには、次の手順を実行します。
  1. 1アプリケーションの統合で、［新規］ > ［サービスコネクタ］をクリックします。
  2. 2［新しいアセット］ダイアログボックスで、［フォームを使用したサービスコネクタ］をクリックし、［作成］をクリックします。
    3. この図は、［新しいアセット］ダイアログボックスを示しています。

プロパティの定義

サービスコネクタを作成してプロパティを定義するには、次の手順を実行します。
  1. 1アプリケーションの統合で、［新規］ > ［サービスコネクタ］をクリックします。
  2. 2［新しいアセット］ダイアログボックスで、［フォームを使用したサービスコネクタ］をクリックし、［作成］をクリックします。
  3. 3［定義］タブで、サービスコネクタの次の基本プロパティを定義します。
  4. 4［+］をクリックして、このサービスに接続するための接続プロパティを追加します。［接続プロパティ］セクションで、各接続プロパティについて次の詳細を指定します。
    5. 次の図に、サービスコネクタのサンプルを示します。
    この図はサービスコネクタのサンプルを示しています。
  5. 5接続プロパティを編集するには、接続プロパティを含んだ行の任意の場所をクリックします。
    6. 行のすべてのプロパティが編集可能になります。
  6. 6［保存］をクリックします。
サービスコネクタを定義するアクションおよびプロセスオブジェクトの詳細については、アクションの定義およびサービスコネクタプロセスオブジェクトの作成を参照してください。

関数と変数の指定

サービスコネクタを構成するには、バインディング、出力フィールド、その他のプロパティを定義するための変数と関数を指定する必要があります。

ビルトイン変数

これらの変数は、XQuery式を使用してサービスコネクタで参照できます。
変数
変数型
説明
$VariableName
すべての接続プロパティ
プロパティ、入力、その他のパラメータは、この形式を使用して指定できます。
$ResponseStatusCode
出力フィールドマッピング
HTTP応答コード。
$ResponseHeaders
出力フィールドマッピング
各項目が次のとおりの要素リスト内にHTTP応答ヘッダーが格納されます。
<header name="Content-Type">text/plain</header>
以下に例を示します。
$ResponseHeaders[@name = "Content-Type"]/text()
$RESTResponse
出力フィールドマッピング
ヘッダーとコードを含むRESTResponse XMLデータが格納されます。サービスコネクタのテスト結果内に表示されます。

出力フィールドマッピング関数

サービスコネクタでバインディングを定義するときは、式エディタで多くの関数を使用できます。
使用可能なすべての機能については、関数の使用および式エディタの使用を参照してください。
次の表に、サービスコネクタの出力フィールドのマッピングで使用できる関数を示します。
機能
構文
説明
responseHeaderExists
svc:responseHeaderExists($ResponseHeaders, headerName ) : boolean
ヘッダーパラメータが応答内にあるかどうかを示すBoolean値を返します。
getResponseHeader
svc:getResponseHeader( $ResponseHeaders, headerName, defaultValue ) : string
svc:getResponseHeader( $ResponseHeaders, headerName ): string
応答ヘッダー値を返します。ヘッダーパラメータが定義されていない場合、この関数は、オプションのデフォルト値を返します。
getResponseHeaderNames
svc:getResponseHeaderNames( $ResponseHeaders ) : list of strings
応答ヘッダー内のすべてパラメータの名前を格納したリストを返します。

アクションの定義

［アクション］タブで、サービスコネクタと関連付ける1つまたは複数のアクションを作成して記述できます。
次の図は、［アクション］タブを示しています。
編集する行を選択し、次の情報を［アクションの詳細］タブに入力します。
［+］をクリックし、新しい行を追加します。
各アクションについて、［入力］、［バインディング］、［出力］、［テスト結果］の各タブに、追加の詳細を指定します。

共有サービスアクション

共有サービスアクションを使用すると、共通の入力、バインディング、出力を定義し、親「抽象」アクションから「継承する」その他のアクションでこれらの定義を再利用できます。
例えば、次の同じ要素を共有する複数のアクションを設けられます。
この場合、次のように実行できます。
  1. 1すべての共通定義を含む抽象型アクションを定義します。
  2. 2これらの共通定義を使用する複数の継承タイプのアクションを作成し、特定のパラメータを拡張または追加します。
  3. 3例えば、継承アクションを次のようにできます。
以下に例を示します。
使用方法に関する注意
共有サービスアクションは次のとおりです。
継承アクションタイプを指定すると、多くのフィールドが無効になります。
ただし、特定のバインディングやその他のオプションの場合、次を選択できます。

［入力］タブ

［入力］タブを使用して、データの送信先サービスに固有の入力データ項目を定義します。
以下に例を示します。
サービスによっては、データ項目がない場合や、データ項目が多数ある場合があります。
各項目に対し、次のプロパティを入力します。
入力フィールドに値を入力した後に、行の外側の任意の場所をクリックして値を保存する必要があります。
［+］アイコンを使用し、新しい項目を追加します。［X］をクリックして現在の行を削除します。

サービスコネクタバインディング

サービスコネクタ内の各アクションに対し、バインディングオプションを使用することで、サービスと通信するために必要なインタフェースとパラメータを指定できます。

バインディングプロパティ

次のオプションに値を指定します。

その他のパラメータ

このセクションは、サービスに必要な入力パラメータを追加するために使用します。この値は、リテラルまたは式として指定できます。使用しているサービスからのドキュメントを参照してください。
行を追加し、複数のパラメータを入力するには、［+］記号をクリックします。行を削除するには、［X］をクリックします。
各行に次の値を入力します。
バインディングのためのオプションのパラメータを選択するには、［詳細の表示］をクリックします。
フィールドを非表示にするには、［詳細の非表示］をクリックします。

HTTPヘッダー

サービスに1つまたは複数のHTTPヘッダーが必要な場合、このセクションの各ヘッダーに、［名前］と［コンテンツ］（パラメータの値）を入力します。
SOAPベースのサービス接続を定義するには、「SOAPAction」ヘッダーと「Content-Type」ヘッダーの両方を追加する必要があります。SOAPActionの値は空にする、GETを使用して動的に設定する、WSDLで定義することができます。
サービスの応答ヘッダーにContent-Typeが設定されていない場合、サービスコネクタはコンテンツタイプをペイロードから推論しようとします。例えば、応答が{...}または[...]のいずれかで始まるか終わっている場合、その応答はJSONとして解析されます。応答のペイロードが山括弧（<）で始まっている場合、その応答はXMLとして扱われます。応答のペイロードが不具合のあるJSONまたはXMLであるために解析できない場合、通常の文字列として処理されます。
応答Content-Typeヘッダーの最初のパートにapplicationという用語、後続のパートにjsonという用語が含まれている場合、アプリケーション統合では応答ペイロードタイプがJSONとして推測されます。同様に、応答Content-Typeヘッダーの最初のパートにtextという用語、後続のパートにxmlという用語が含まれている場合、アプリケーション統合ではペイロードタイプがXMLとして推測されます。
一部のサービスには、MD5署名を要求するものがあります。MD5署名は、サービスコネクタアクションの［HTTPヘッダー］セクションで生成できます。
MD5署名を生成するには、次の手順を実行します。
サービスコネクタをテストまたは実行するときに、使用される変数に生成済み要求ペイロードのMD5チェックサムが格納されます。

コンテンツタイプと文字セット

要求ペイロードに使用する文字セットは、ここに示すように判断できます。

サービスコネクタプロパティの式エディタ

バインディングパラメータを定義するには、［URL］、［その他のパラメータ］、［HTTPヘッダー］の各フィールドに対して使用できる式エディタを使用できます。
式エディタを開くには、編集するフィールドの横の［f（x）］をクリックします。式エディタを開くと、図に示すように、使用可能な関数と、サービスコネクタに対して定義されたフィールドのリストにアクセスできます。
式に選択された型に基づいて、式エディタで構文検証が適用されます。この場合、post_urlフィールドは、XQuery変数として検証されます。
詳細については、式エディタの使用を参照してください。

［出力］タブ

［出力］タブを使用して、サービスコネクタがサービスから返されるデータを解析し、そのデータを変数に配置する方法を定義します。通常、サービスはデータをXML形式で返します。サービスがデータをJSON形式で返す場合、サービスコネクタはそれをXML形式に変換します。XMLは、次の2種類の方法で出力フィールドにマッピングできます。
  1. 1XMLタグ名またはJSONプロパティに基づいて、データを直接プロパティにマッピングします。
  2. 2式を使用して、要素を抽出します。
    3. 注: JDOMやWoodstoxなどのXML解析ツールを使用してXML応答を解析してから、値を抽出する（プレーン文字列検索を実行して名前空間とタグを照合するのではなく）ことをお勧めします。名前空間のプレフィックスが一定ではないため、プレーン文字列を照合するとエラーが発生する可能性があります。
次の図は、［出力］タブを示しています。
この図は、［出力］タブを示しています。
各出力データ項目について、次の要素を指定します。
出力フィールドに値を入力した後に、行の外側の任意の場所をクリックして値を保存する必要があります。
HTTPエラーの処理方法の詳細については、HTTPエラーのチェックを参照してください。

単純型のリストを使用する際のルールとガイドライン

サービスコネクタで単純型のリストを使用する場合は、次のルールとガイドラインを考慮してください。

簡易XML

Process Designerでは、標準XMLでプロセスの設計者にデータを提示するために必要とされる、名前空間、属性、兄弟、子が混在する複雑な構成の多くは、必要ありません。場合によって、［取得元］にXQueryオプションを使用する必要がありますが、多くのアプリケーションでこれは必要ありません。
簡易XMLは、XML内のデータを再配置し、プロセスオブジェクトで使用できるようにします。この再配置では、属性を子として扱い、名前空間を削除し、同じ名前の兄弟を連続させ、CDATAセクションにテキストを配置します。
［取得元］のオプションに［簡易XML］を選択すると、Process Designerにテキストフィールドが表示されます。このフィールドに何も入力しないと、Process Designerは受け取ったすべてのXMLを処理します。要素の名前を入力すると、Process Designerはこの要素で単純化を開始し、この要素とその内部にネストされた要素のみが処理されます。
ピリオド（.）を入力すると、空のフィールドとして扱われます（これがデフォルトです）。

HTTPエラーのチェック

サーバーに要求を送信し、サーバーがこの要求を完了できない場合、エラーステータスコードが返されます。サービスコネクタがHTTPエラー（HTTP応答内の4xxステータスコードと5xxステータスコード）を処理できる2種類の方法があります。
  1. 1［アクション］タブで定義できる各アクションについて、下の図に示すように、［HTTPエラー時に終了］を選択できます。デフォルトでは、このオプションが有効になっています。HTTP要求がHTTPエラーを返すと、サービスコネクタは終了します。
  2. 2［出力］タブで、各アクションに対してHTTPエラーの処理方法を指定します。このオプションを実装するには、［HTTPエラー時に終了］を無効にします。

HTTPエラー時に終了

［HTTPエラー時に終了］を有効にすると、HTTPエラーが返された場合、次のようになります。
HTTPエラーコードは、HTTP_NNNの形式に従います。例えば「HTTP_404」です。理由文字列にHTTPステータスメッセージが含まれます。
注: 内部エラーまたはシステムエラーは、SERVICE_CONNECTOR_ERRORと次の理由文字列のいずれかを返します。
［HTTPエラー時に終了］を無効にすると、HTTPエラーが返された場合、次のようになります。
ターゲットサービスが、ユーザーに頻繁に表示される可能性があるエラーコードを使用する場合、このオプションを有効にして、プロセスユーザーにわかりやすい情報が提供されるようにします。
次の図に、有効化された［HTTPエラー時に終了］オプションを示します。

HTTPエラーの処理

プロセスのHTTPエラーを処理するには、まず［HTTPエラー時に終了］が無効であることを確認します。
次に、プロセス内のHTTP応答ステータスコードを確認する必要があります。
これを行うには、「HTTP応答ステータスコード」を［出力］タブの変数として定義します。また、$ResponseStatusCodeを式フィールド内で使用して、変数を指定することもできます（以下の使用可能な機能を参照）。この方法では、ステータスコードをサービスコネクタの出力の一部として渡し、プロセス内で応答を処理できます。
これらの変数は、［出力］タブ内で作成するすべての変数と同様に、［テスト］をクリックすると表示されます。
［HTTPエラー時に終了］を選択し、HTTPエラーステータスコードが返される場合、出力にメッセージが含まれます。

式を使用するHTTP応答ヘッダー情報

次のいずれかを使用して、応答ヘッダーから詳細を取得できます。
$ResponseHeaders[@name = "Content-Type"]/text();
この定数には、HTTP応答ヘッダーが格納されます。
fn:getResponseHeader( $ResponseHeaders, header_name[, default_value] );
応答ヘッダー値を返します。ヘッダーパラメータが定義されていない場合、この関数は、オプションのデフォルト値を返します。
fn:responseHeaderExists( $ResponseHeaders, header_name );
ヘッダーパラメータが応答内にあるかどうかを示すBoolean値を返します。
fn:getResponseHeaderNames( $ResponseHeaders );
応答ヘッダー内のすべてパラメータの名前を格納したリストを返します。

サービスコネクタプロセスオブジェクトの作成

［プロセスオブジェクト］タブでは、サービスコネクタの1つ以上のプロセスオブジェクトを定義して、データをグループ化し、構造化オブジェクトを作成できます。プロセスオブジェクトがサービスコネクタ内で定義されている場合、そのサービスコネクタを使用するプロセスから使用できます。例えば、サービスが名前、住所、電話番号などの人口統計情報を返す場合、この情報を格納する単一の人口統計的プロセスオブジェクトを作成できます。
［アクション/出力］タブを使用して、サービスによって返された1つ以上のデータ要素と各プロセスオブジェクトを関連付けられます。
サービスコネクタのプロセスオブジェクトを作成するには、次の手順を実行します。
  1. 1サービスコネクタを作成するか、既存のコネクタを開きます。
  2. 2［プロセスオブジェクト］タブをクリックします。
  3. 3［+］記号をクリックし、新しいプロセスオブジェクトを追加するか、既存のプロセスオブジェクトをリストから選択します。各プロセスオブジェクトは、タブ内に行項目として表示されます。
  4. 4［プロパティ］タブで、各プロセスオブジェクトに対し、次の詳細を指定します。
  5. 5［フィールド］タブで、各プロセスオブジェクトに対し、次の詳細を指定します。
注: サービスコネクタ内で作成されるプロセスオブジェクトとそのネストされたオブジェクトに対して、インラインタイプの注釈を使用できます。ただし、プロセスオブジェクトタイプの注釈は、プロセスオブジェクトが作成されたサービスコネクタでのみサポートされます。
プロセスでのプロセスオブジェクトの使用の詳細については、プロセスでプロセスオブジェクトを使用するためのルールおよびガイドラインを参照してください。

サービスコネクタのテスト

サービスコネクタエディタを使用するときは、［テスト］をクリックしてサービスに要求を送信し、応答データを［テスト］タブに表示します。
ここでは、ペイロード、要求、応答データの違いを確認できます（図示することのみを目的としており、実際のテスト結果には、要求または応答データのみが表示されます）。
応答に1つ以上の添付ファイルが含まれている場合は、それらの添付ファイルをダウンロードすることもできます。次の図は、すべての添付ファイルをダウンロードできるマルチパート応答を示しています。
この図は、すべての添付ファイルをダウンロードできるマルチパート応答を示しています。
プロセスオブジェクトの生成
通常プロセスオブジェクトは、特定の要素セットに結び付けられます。場合によっては、多数の同一のオブジェクトを持ち、それぞれが1つの要素セットに適用されることがあります。例えば、返されるデータを定義するときに、返されるデータのサブセットを定義することのみを目的とするプロセスオブジェクトを作成します。これらのオブジェクトは再利用不可能であり、単一のプロセスオブジェクトフィールドのみが使用できます。オブジェクト名は、フィールドの名前でもあります。
再利用可能なオブジェクトを作成することもできます。例えば、NetSuiteのrefType要素には、nameとinternalIDという2つのフィールドがあります。これら2つのフィールドをそれぞれが含む多数のオブジェクトを作成するのでなく、1つの再利用可能なプロセスオブジェクトを作成できます。
  1. 1［プロセスオブジェクトの生成］をクリックして、サービスコネクタ用に定義したプロセスオブジェクトを表示します。
  2. 2再利用可能にするプロセスオブジェクトを選択し、［次へ］をクリックします。
    3. Process Designerに、生成されたプロセスオブジェクトの一覧が表示されます。
  3. 3［完了］をクリックします。

サービスコネクタのタイミング

サービスコネクタのタブで、HTTP応答解析時間、HTTP実行時間、およびリダイレクト数を参照できます。
タブの［REST応答］セクションで、次のHTTPヘッダーを参照できます。
HTTP応答解析時間
［バインディング］タブに入力したURLからの応答を解析するために、サービスコネクタが費やす時間（ミリ秒単位）。小さい要求のHTTP応答解析時間は、通常ゼロです。大きい要求で、特に添付ファイルのある要求の場合、HTTP応答解析時間は長くなります。
HTTP応答解析時間は、HTTPヘッダーのX-AE-HTTP-RESPONSE-PARSING-TIME-IN-MILLISを参照してください。
リダイレクト数
［バインディング］タブに入力したURLによって行われるリダイレクトの数（ある場合）。
例えば、サービス要求が、別のサービスにリダイレクトするサービスにリダイレクトする場合、リダイレクト数は2になります。サービス要求がリダイレクトなしで行われる場合、リダイレクト数はゼロになります。
リダイレクト数は、HTTPヘッダーのX-AE-REDIRECTION-COUNTを参照してください。
注: GET HTTP要求が別のGET HTTP要求にリダイレクトする場合、リダイレクト数はゼロのままです。これは制限事項の1つです。
HTTP実行時間
［バインディング］タブに入力したURLの応答時間（ミリ秒単位）。HTTP実行時間には、応答の解析時間や、サービスコネクタが他のタスクを実行するために使用した時間は含まれません。
HTTP実行時間は、HTTPヘッダーのX-AE-HTTP-EXECUTION-TIME-IN-MILLISを参照してください。
次の図は、X-AE-HTTP-RESPONSE-PARSING-TIME-IN-MILLIS、X-AE-REDIRECTION-COUNT、およびX-AE-HTTP-EXECUTION-TIME-IN-MILLISの各HTTPヘッダーを示します。