CData Arc でAPI リクエストを動的に制御する方法

開発者は、外部RESTful API を使用してデータをArc のフローに取り込み、リクエストのパラメータと仕様を完全に制御することができます。このガイドでは、API リクエストを動的に入力する必要がある場合に、REST コネクタを介してRESTful API を使用する方法について詳しく説明します。

• 動的リクエスト本文
  • Raw リクエスト本文
  • 形式データ
    • 例：新しいコネクタの作成
• 動的なURL
  • AllowArcScriptInURL
  • ベストプラクティス：メッセージ項目
  • URL のArcScript

REST コネクタは、入力ファイルからのデータを解析することにより、動的なREST リクエストを作成します。コネクタによって処理される各ファイルは、ファイル内の値を反映するパラメータを持つ新しいリクエストになります。

REST コネクタは、次の2つのタイプの動的リクエスト本文をサポートします。

• Raw リクエスト本文
• フォームデータ

REST コネクタのBody Type フィールドが「raw」に設定されている場合、入力ファイルの内容全体がリクエストの本文として使用されます。REST リクエストの本文を管理および操作するために必要な手順は、REST コネクタによってファイルが処理される前に実行する必要があります。

このオプションは、任意のAPI リクエストを生成するための柔軟性が最も高くなりますが、以下で説明するフォームデータのアプローチを使用するよりも作業量が多くなる可能性があります。

Body Type が「form-data」または「x-www-form-urlencoded」に設定されている場合、REST コネクタは設定パネルのBody セクションにあるフィールドのセットで設定されます。コネクタで「動的」として設定された各フィールドには、入力ファイルの値が入力されます。

入力ファイルは、以下の構造を持つXML ファイルである必要があります。

<Items>
  <FormData>
    <FieldName1>value1</FieldName1>
    <FieldName2>value2</FieldName2>
  </FormData>
</Items>

REST コネクタは入力ファイルを解析して、各動的フィールド名と一致する要素を探します（これらの要素は上記のようにFormData 要素内になければなりません）。一致する要素が見つかると、そのXML 要素内の値が、対応するフィールドのForm 値として使用されます。

入力ファイルのXML 構造は具体的に定義されているため、REST コネクタの前にXML Map コネクタを使用して、任意のXML データを適切な構造に変換することを推奨します。

以下は、Arc の管理API を使用してREST コネクタ経由で新しいコネクタを作成する例です。コネクタのタイプと名前は、入力XML ファイルから動的に読み取られます。Arc の管理API を使用するための同じ原則は、外部のRESTfulAPI を動的に使用する場合にも適用されます。

Arc で新しいコネクタを作成するためのAPI リクエストには、次の必須パラメータがあります。

• ConnectorID（例：コネクタの名前）
• ConnectorType（例：REST、Script、AS2）
• Workspace（例：Default）

したがって、REST コネクタの「設定」タブのBody セクションには、これら3つのフィールドが設定されます。この例でWorkspace パラメータは、静的に「デフォルト」に設定され、残りのパラメータは入力ファイルから動的に入力されます。

この構成でREST コネクタによって処理されるファイルには、以下のようなXML コンテンツが含まれている必要があります。

<Items>
  <FormData>
    <ConnectorType>SFTP</ConnectorType>
    <ConnectorID>newSFTPConnector</ConnectorID>
  </FormData>
</Items>

静的URL は、REST API を使用するとき、必ずしも実行可能とは限りません。たとえば、着信Arc メッセージのデータによっては、URL にクエリパラメータを追加する必要がある場合があります。RESTコネクタは、動的URL を生成するためのURL フィールドへのArcScript の書き込みをサポートしています。

動的URL を有効にするには、REST コネクタのport.cfg ファイルで構成設定を直接有効にする必要があります。このファイルは、デフォルトでは以下のファイルパスにあります。

Windows：C:\Program Files\CData Arc\data\[connector_name]\port.cfg
Java：~/arcesb/data/[connector_name]/port.cfg

REST コネクタがデフォルト以外のワークスペースにある場合、上記のパスの 「data」フォルダはワークスペースの名前に置き換えられます。

このファイル内では、以下の設定をtrue に設定する必要があります。

AllowArcScriptInURL = true

この値が設定ファイルで設定されると、コネクタはURL フィールド内でArcScript を解釈します。

URL フィールドでArcScript を使用するには、_message 項目を参照することを推奨します。この特別な項目は、Arc メッセージ（関連するヘッダー / メタデータとともにArc Flow を通過するファイル）を表し、他のArcScript 項目と同様にアクセスできます。

手順は以下のとおりです。

• Script コネクタを使用して、必要な動的値（URL の後半で使用する必要がある値）を読み込み / 生成 / 計算するスクリプトを記述します。
• これらの値をScript コネクタの出力ファイルのカスタムヘッダーとしてプロモートします。
• ファイルを（カスタムヘッダーとともに）REST コネクタに渡します。
• _message 項目を使用して、REST コネクタのURL フィールドでこれらのカスタムヘッダーを参照します。

たとえば、GET リクエストを行う前にデータベースからクエリパラメータを読み込む必要があるとします。最初のステップは、データベースをクエリし、その結果をメッセージヘッダーとしてプロモートするスクリプトを記述することです。

<!-- configure database query -->
<arc:set attr= "myDb.conn" value="Server=hostName;Port=3306;Database=mydb;User=test;Password=test" />
<arc:set attr="myDb.driver" value="System.Data.CData.MySQL" />
<arc:set attr="myDb.query" value="SELECT targetColumn FROM my_table WHERE otherColumn = 'value' "/>

<!-- execute query and store output in myDb.output -->
<arc:call op="dbQuery" in="myDb" out="tempOut">
  <arc:set attr="myDb.output" value="[tempOut.db:targetColumn]" />
</arc:call>

<!-- generate output file -->
<arc:set attr="outputItem.filename" value="myOutputFile.txt" />
<arc:set attr="outputItem.data" value="" /> <!-- no file contents required in this example -->

<!-- promote a custom header in the output file -->
<arc:set attr="outputItem.header:myCustomHeader" value="[myDb.output]" />

<!-- push the output -->
<arc:push item="outputItem" />

このスクリプトは専用のスクリプトコネクタに配置し、そのスクリプトコネクタをフロー内のREST コネクタに接続する必要があります。

Script コネクタからREST コネクタにメッセージが渡されると、URL フィールドでこのカスタムヘッダーを参照するための構文は[_message.header:header_name] になります。例：

http://localhost:8001/api.rsc/connectors(ConnectorID='[_message.header:myCustomHeader]')

各値に固有のヘッダー名を指定し、URL 内の各ヘッダー名を参照することで、_message 項目を介して複数の動的値を渡すことができます。

上記の_message 項目のアプローチに加えて、カスタムロジックをArcScript でREST コネクタのURL フィールド内に直接実装できます。<arc:*> 要素内に含まれるスクリプトは、結果のURL には含まれず、代わりにスクリプトとして実行されます。ArcScript は、REST コネクタのport.cfg ファイルに直接書き込むことができます。

次に、port.cfg ファイルを介してURL にArcScript 変数を含める簡単な例を示します。

Url = "<arc:set attr='myParam' value='myConnectorName' />http://localhost:8001/api.rsc/connectors(ConnectorID='[myParam]')"

このURL へのGET リクエストは、Arc で提供される管理API を介してmyConnectorName のコネクタの詳細を返します。この方法を使用すると、ArcScript の動的な値を取得および計算する機能のすべてが利用可能です。