REST V1 Connector (Deprecated) - CData Arc Documentation

REST コネクタは、RESTful API Web サービスを利用するための動的なREST リクエストの構築をサポートします。

Key Capabilities

すべてのHTTP メソッド（GET、POST、PUT、PATCH、DELETE）をサポートする完全なRESTful API クライアント
API の自動設定とリクエスト生成のためのSwagger インポート機能
OAuth 2.0、Bearer Token、AWS Signature、Basic / Digest 認証を含む高度な認証
URL、ヘッダー、フォームデータでのArcScript サポートによる動的なリクエスト構築
raw、form-data、URL エンコード、ファイルアップロードを含む柔軟なボディタイプ

Overview

REST コネクタは、REST リクエストのヘッダー、認可、ボディ、HTTP メソッドを構築するためのシンプルなインターフェースを公開します。リクエストボディは、コネクタの設定で静的に設定することも、コネクタが処理するファイルに基づいて動的に生成することもできます。

Actions

Connector Configuration

REST Details Tab

コネクタのリクエスト詳細に関連する設定。

Authentication

REST サービスでの認証に関連する設定。

設定	説明
Authentication Type	REST サービスで使用する認証の種類。オプションは選択内容によって異なります。詳しくは、Authenticatingを参照してください。
TLS Server Certificate	TLS サーバーのアイデンティティを検証するために使用される公開鍵証明書。証明書をアップロードするか、フィールドを空白のままにして基底のOS / JVM に証明書の検証を実行させるか、または`Any Certificate` に設定してターゲットサーバーのアイデンティティを信頼することができます。Any Certificate は慎重に使用してください。証明書は、意図したサーバーに接続していることを検証するものです。

Request Details

設定	説明
Import from Swagger	アイコンをクリックすると、Swagger URL から直接API の詳細をインポートできます。
Test	フローに送信されるメッセージやトランザクションを作成せずに、現在の設定をテストします。Test をクリックすると、4つのタブを持つウィンドウが開きます（詳しくは、Testing Request Configurationsを参照してください）： Response Body：サーバーからの応答のボディを表示します。 Response Headers：サーバーからの応答に含まれていたヘッダーを表示します。 Message Headers：テストの出力に含まれていたメッセージヘッダーを表示します。 Log：コネクタログを表示します。
Action	コネクタが実行するアクション。（3つのオプションの詳細については、Actionsを参照してください。）
Request URL	REST リクエストのHTTP メソッドとターゲットHTTP URL。利用可能なメソッドのオプションは、GET、POST、PUT、PATCH、DELETE です。
Body Type	REST リクエストとともに供給されるボディコンテンツの種類。HTTP メソッドがGET の場合は表示されません。各オプションの説明については、Body Typesを参照してください。
Headers	Headers タブでは、送信するREST リクエストに含めるHTTP ヘッダーの一覧を追加できます。ヘッダーは名前と値のペアとして指定します。詳しくは、Static Requestsを参照してください。
Body	Body Type が`form-data` または`x-www-urlencoded` に設定されている場合は、Body タブを使用して、リクエストのボディを構成する名前と値のペア（フィールド）のセットを供給します。詳しくは、Body Typesを参照してください。

Settings Tab

コネクタのコアとなる設定に関連する設定。

Configuration

設定	説明
Connector Id	コネクタの静的で一意の識別子です。
Connector Type	コネクタ名とその機能の説明を表示します。
Connector Description	コネクタおよびフロー内でのその役割について自由形式の説明を提供するためのオプションフィールドです。

Advanced Settings

設定	説明
Local File Scheme	コネクタが出力するメッセージにファイル名を割り当てるためのスキーム。ファイル名にマクロを使用して、識別子やタイムスタンプなどの情報を動的に含めることができます。詳しくは、Macrosを参照してください。

Advanced Tab

TLS Client Authentication

双方向TLS 認証が必要な場合のクライアント認証に関する設定です。

設定	説明
Private Certificate	TLS クライアント認証時に提示されるプライベート証明書です。
Certificate Password	TLS クライアント証明書にアクセスするために必要なパスワードです。

Advanced Settings

前のカテゴリに含まれない設定。

設定	説明
ArcScript in Headers	クエリが発行される前に、ヘッダー内のArcScript 式の評価を許可します。例については、URL セクションを参照してください。
ArcScript in URL	クエリが発行される前に、URL 内のArcScript 式の評価を許可します。例については、Headers セクションを参照してください。
Output Error Responses	デフォルトでは、成功を示さないステータスコードで応答が送信された場合、コネクタはフローにメッセージを出力しません。この設定を有効にすると、こうしたエラー応答についてコネクタがフローにメッセージを出力するようになります。フローの後段でHTTP-Status-Code ヘッダーを使用してメッセージをフィルタリングできます。
Chunked Encoding	リクエストの送信時にHTTP Chunked Transfer Encoding を使用するかどうか。これにより、アプリケーションはメッセージの一部（チャンク）を順次送信し、接続への過負荷を回避できます。
Chunk Size	Chunked Encoding が有効な場合の各チャンクのサイズ（バイト単位）。
Compression	リクエストを送信する前に、PUT またはPOST リクエストのボディを`gzip` 形式に圧縮するかどうか。送信するリクエストにはContent-Encoding ヘッダーも追加されます。
GET Request Body	GET リクエストが入力メッセージのデータをリクエストのボディとして使用できるようにします。
HTTP Version	REST サービスへの接続時にHTTP 1.0、1.1、2.0 のいずれを使用するか。
Output Behavior	デフォルトでは、コネクタは`Response` データを含むメッセージを出力します。他のオプションでは、さらに処理できるように`Input Message` を出力したり、メッセージをまったく出力しないようにしたりできます。詳しくは、Response Eventを参照してください。
Timeout (seconds)	タイムアウトエラーをスローする前に、REST サーバーからの応答を待機する秒数。
Response Headers	設定すると、コネクタはREST メッセージから指定されたヘッダーを、ダウンロードされたメッセージのメタデータとして昇格させます。カンマ区切りのリストで複数のヘッダーを指定できます。
Preserve Cookies	出力メッセージにクッキーを保持するには、保持するクッキー名のカンマ区切りのリストを供給します。すべてのクッキーを保持するには`` を使用します。Note*：名前と値のペアのみが保持され、属性のチェックは実行されません。クッキーが意図しない宛先に漏洩しないようにするのはユーザーの責任です。
TLS Enabled Protocols	送信接続を確立する際にサポートされるTLS / SSL プロトコルのリスト。ベストプラクティスは、TLS プロトコルのみを使用することです。一部の古いオペレーティングシステムはTLS 1.2 をサポートしていません。

Proxy Settings

これらは、接続のルーティング先となるプロキシを識別し認証するための一連の設定です。デフォルトでは、このセクションはSecurity Settings ページのProxy Settings 部分にあるグローバル設定を使用します。チェックボックスをオフにすると、コネクタ固有の設定を指定できます。

設定	説明
Proxy Type	プロキシベースのファイアウォールで使用されるプロトコル。
Proxy Host	プロキシベースのファイアウォールの名前またはIP アドレス。
Proxy Port	プロキシベースのファイアウォールのTCP ポート。
Proxy User	プロキシベースのファイアウォールで認証するために使用するユーザー名。
Proxy Password	プロキシベースのファイアウォールで認証するために使用するパスワード。
Authentication Scheme	デフォルトのNone のままにするか、次の認証スキームのいずれかを選択します：Basic、Digest、Proprietary、またはNTLM。

Logging

ログの作成と保存を制御する設定です。

設定	説明
Log Level	コネクタが生成するログの詳細度です。サポートを依頼する際は、これをDebug に設定してください。
Log Subfolder Scheme	選択した間隔に従って、コネクタがLogs フォルダ内のファイルをグループ化するよう指示します。Weekly オプション（デフォルト）は、コネクタが毎週新しいサブフォルダを作成し、その週のすべてのログをそのフォルダに保存するよう指示します。この設定を空白のままにすると、コネクタはすべてのログをLogs フォルダに直接保存します。多数のトランザクションを処理するコネクタでは、サブフォルダを使用することでログを整理しやすくなり、パフォーマンスが向上します。
Log Messages	処理したファイルのログエントリにファイル自体のコピーを含めるには、これをオンにします。これを無効にすると、Transactions タブからファイルのコピーをダウンロードできなくなる場合があります。

Miscellaneous

Miscellaneous 設定は、特定のユースケース向けの設定です。

設定	説明
Other Settings	非表示のコネクタ設定をセミコロン区切りのリストで設定できます（例：`setting1=value1;setting2=value2`）。通常のコネクタのユースケースや機能では、これらの設定の使用は必要ありません。

Automation Tab

Automation Settings

コネクタによるファイルの自動処理に関連する設定。

設定	説明
Send	ファイルの準備ができたときに、コネクタが自動的にファイルを送信するよう指示するトグル。
Retry Interval	失敗した送信を再試行するまでにコネクタが待機する間隔。
Max Attempts	コネクタがメッセージの送信を試行する回数。この値を 1 に設定すると、コネクタは再試行せずに最初の送信試行のみを行います。コネクタは各試行の間にRetry Interval で指定された時間だけ待機します。
Receive	設定された間隔でコネクタが自動的にREST リクエストを行うよう指示するトグル。
Receive Execution Interval	コネクタが設定されたREST リクエストを行う間隔。ここでの選択によって次のフィールドが異なります： Hourly：Minutes Past the Hour ドロップダウンメニューで、受信ファイルを処理する正時からの分数を指定できます。 Daily：受信ファイルを処理する時刻（UTC）を指定する Time フィールドが表示されます。 Weekly：2つのフィールドが表示されます。Day では処理する曜日を選択でき、Time では受信ファイルを処理する時刻（UTC）を指定できます。 Monthly：2つのフィールドが表示されます。Day では処理する日にちを選択でき、Time では受信ファイルを処理する時刻（UTC）を指定できます。 Minute：処理間隔の分数を指定する Minutes フィールドが表示されます。 Advanced：5つの位置を持つ Cron Expression フィールドで、正確な処理間隔を指定できます。
Minutes Past the Hour	1時間ごとのスケジュールの分オフセット。Receive Interval が Hourly に設定されている場合にのみ適用されます。例えば、この値が5に設定されている場合、オートメーションサービスは1:05、2:05、3:05 などにリクエストを送信します。

Performance

コネクタへのリソースの割り当てに関する設定です。

設定	説明
Max Workers	このコネクタでファイルを処理するためにスレッドプールから消費されるワーカースレッドの最大数です。設定すると、Advanced Settings ページのPerformance Settings 部分にあるデフォルト設定が上書きされます。
Max Files	コネクタに割り当てられた各スレッドが送信するファイルの最大数です。設定すると、Advanced Settings ページのPerformance Settings 部分にあるデフォルト設定が上書きされます。

Alerts Tab

SLAs Tab

Transactions Tab

このタブには、コネクタに関連するすべてのメッセージが一覧表示されます。検索バーを使用して特定のメッセージを見つけるか、じょうごアイコンをクリックしてフィルタを適用します。時間、メッセージの方向、ステータスでフィルタリングできます。このタブのオプションは、コネクタのアクションタイプによって異なります：

コネクタがTrigger の場合は、Receive Files ボタンを使用してフローを開始します。
コネクタがTransform またはTerminal の場合は、Upload Files ボタンを使用してフローにファイルをアップロードします。

Establishing a Connection

任意のREST サービスへの接続を確立するには、有効なターゲットURL が必要です。サービスURL はさまざまなHTTP メソッドをサポートでき、取得する特定のWeb サービスのアクションやデータセットに基づいてMethod を設定する必要があります。一部のサービスでは、サービスを利用するために認証やカスタムヘッダーのセットが必要になる場合もあります。ターゲットURL がHTTPS URL の場合は、TLS Server Certificate をサーバーを識別する公開鍵証明書に設定します。ターゲットエンドポイントを暗黙的に信頼するには、フィールドをAny Certificate に設定します。

Authenticating

REST コネクタはいくつかの認証タイプをサポートしており、各タイプにはそれぞれの要件があります：

Basic（プレーンテキスト）、Digest（暗号化）、NTLM では、ユーザー名とパスワードによる認証が必要です。これらの認証情報は、リクエスト内のヘッダーとしてREST サービスに供給されます。
OAuth 認証では、REST サービスのWeb ポータルまたは開発コンソールでのアプリ登録が必要です。アプリ登録に含めるCallback URL は、Arc のUI に表示されます。REST サービスに該当するGrant Type を選択し、REST サービスのWeb ポータルまたは開発コンソールに表示される詳細から残りの設定を指定します。次に、Get New Access Token をクリックして、サービスとやり取りするために必要なトークンを取得します。最初のトークンが取得されると、アプリケーションは有効期限が近づくとトークンを更新します。
Bearer Token 認証では、サービスのWeb ポータルまたは開発コンソールからのトークンが必要です。
Amazon に対して認証するためのAWS Signature 認証では、Amazon が提供する設定の認証情報（Access Key、Secret Key など）が必要です。

Testing Request Configurations

フローに送信されるメッセージやトランザクションを作成せずに、いつでも現在の設定をテストできます。REST Details タブでTest をクリックします。次の画像は、成功したテストのResponse Body の結果を示しています。

Response Body：サーバーから返された形式でREST リクエストの出力を表示します。
Response Headers：サーバーから返された応答に含まれていた応答ヘッダーを表示します。
Message Headers：テストの出力に含まれていたメッセージヘッダーを表示します。
Log：テストログを表示します。

Body Types

コネクタのRequest Details タブを使用して、ボディの構成方法と供給する情報の種類を指定します。次のリストでは、各オプションについてより詳しく説明します。

none：REST リクエストとともにボディは供給されません。
form-data：ボディは名前と値のペア（フィールド）のセットとして供給されます。Name の横にあるドロップダウンリストを使用して、フィールドタイプを選択します。
- Static：Name とValue の両方を供給します。
- XML：UI でName を供給します。Value は、コネクタが処理する入力ファイルから動的に読み取られます。詳しくは、Dynamic Form Dataを参照してください。
- File：各コネクタは、1つのボディフィールドをFile に設定できます。これにより、入力ファイルがリクエストのボディで送信されます。コネクタが入力ファイル自体をフォームデータとして使用するため、Value フィールドはグレーアウトされます。
  Note：File オプションは、動的リクエストや他のファイルリクエストと互換性がありません。このオプションを使用する場合は、静的フィールドとのみ組み合わせることができます。
- Header：Value フィールドを使用して、ボディのために入力メッセージから読み取るヘッダーを指定します。
- ArcScript：供給されたValue はArcScript としてレンダリングされ、結果の値がリクエストボディで使用されます。
x-www-urlencoded：ボディはform-data と同じ方法で構成されます。ただし、名前と値のペアはマルチパートフォームデータではなく、URL クエリ文字列としてエンコードされます。
raw：ボディは、コネクタが処理する入力ファイルの内容に設定されます。ドロップダウンを使用するか、Header セクションでカスタムヘッダーとして指定して、ボディのContent Type を選択します。

Static Requests

完全に静的なコンテンツを持つREST リクエスト（HTTP GET メソッドを使用するリクエストなど）は、リクエストのコンテンツがコネクタのUI で完全に設定されるため、入力ファイルを必要としません。Header セクションにカスタムヘッダーとして、またはBody セクションにフォームデータとして、必要な名前と値のペアを追加するだけです。 Receive Automation が有効な場合、静的リクエストはスケジュールに従って自動的に送信できます。各リクエストへの応答は、出力フォルダに保存されるか、フロー内の次のコネクタに渡されます。 Send Automation が有効な場合、コネクタの入力フォルダに到着したファイルも静的リクエストをトリガーします。入力ファイルの内容は無視され、UI の設定に従ってリクエストが送信されます。

Dynamic Requests

REST リクエストは、コネクタの入力フォルダに到着したファイルのデータで動的に設定できます。

Raw Input Data

リクエストのBody Type をraw に設定すると、入力ファイルの内容がREST リクエストのボディとして送信されます。 Content Type ドロップダウンを使用して、データの特定のコンテンツタイプを設定します。必要なコンテンツタイプが一覧にない場合は、Header セクションに Content-Type ヘッダーを追加できます。

Dynamic Form Data

リクエストのBody Type をform-data またはx-www-urlencoded に設定すると、コネクタは入力ファイルから特定の値を探してリクエストを設定します。XML に設定された各名前と値のペアについて、コネクタは入力ファイルをスキャンして、フィールド名と同じ名前を共有し、次に示す特定のXML 構造を使用するXML 要素を探します：

<Items>
  <FormData>
    <FieldName></FieldName>
  </FormData>
</Items>

この構造に合わせるため、CData は、後述のとおり、フロー内でREST コネクタの前にXML Map コネクタを使用することを強く推奨します。コネクタがフィールド名と必要なXML 構造に一致する要素を見つけると、この要素内の値が名前と値のペアの値として使用されます。例えば、ボディにCustomerID という名前の動的フィールドがあり、入力ファイルに次に示すXML がある場合、REST コネクタはCustomerID フィールドの値を12354 に設定します。

<Items>
  <FormData>
    <CustomerID>12354</CustomerID>
  </FormData>
</Items>

Dynamic Templates with XML Map

REST コネクタと組み合わせてXML Map コネクタを使用すると、他のXML データ構造から動的リクエストを簡単に構築できます。XML Map コネクタは、カスタムXML 構造を、REST コネクタが期待するXML 構造に変換します。まず、リクエストに含めるべき動的（および静的）なBody フィールドのセットでREST コネクタを設定します。次に、Arc フローでREST コネクタにXML Map コネクタを接続し、フローの変更を保存します。これにより、XML Map コネクタは、REST コネクタが受信する入力ファイルでどのフィールドを期待しているかを検出できるようになります。その後、XML Map コネクタ内で、Destination File ドロップダウンにREST リクエストスキーマが含まれます。これをDestination として選択し、Source File をカスタムXML 構造に設定します。これによりXML Map のMapping Editor が設定され、REST リクエストに含める必要があるデータをソース構造からデスティネーション構造にドラッグアンドドロップできます。マッピングが完了すると、XML Map コネクタは、ソースファイルに一致するファイルを有効なREST リクエスト構造に自動的に変換します。 XML Map コネクタの使用に関する詳細については、XML Map コネクタのドキュメントを参照してください。

URL

コネクタ設定ペインのAdvanced tabでAllow ArcScript in URL を選択すると、ArcScript の式を評価して、URL として動的な文字列を生成できます。例えば、次のURL には日付と時刻が含まれます： http://myendpoint.com/api?day=[_ | now('yyyyMMdd')] 次のURL には、送信オートメーションを通じてトリガーされるクエリのために、受信メッセージのヘッダーが含まれます： http://myendpoint.com/api?customer=[_message.header:customerid] 最後に、次のURL は、最後のクエリの時刻から現在のタイムスタンプまでの動的な日付範囲を使用し、最初のクエリにはデフォルトのタイムスタンプを使用します：

http://myendpoint.com/api?DateFrom=[_connector.lastruntimestamp | def('2025-01-01T00:00:00-04:00')]&DateTo=[_connector.currenttimestamp]

Headers

コネクタ設定ペインのAdvanced tabでAllow ArcScript in Headers を選択すると、ArcScript の式を評価して、ヘッダー値として動的な文字列を生成できます。例えば、次のヘッダーには日付と時刻が含まれます： Timestamp [_ | now('yyyyMMdd')] 次のヘッダーには、送信オートメーションを通じてトリガーされるクエリのために、顧客Id が含まれます： Customer [_message.header:customerid]

Response Event

REST コネクタでレスポンスイベントを使用すると、サーバーから受信した応答（ボディ、ヘッダー、クッキーなどを含む）とやり取りし、コネクタが生成する出力メッセージを拡充できます。Response イベントでは、次の特別なアイテムを使用できます。

Response Event Example

このスクリプトは、REST 呼び出しから受信したJSON 応答を読み取り、JSON に含まれるアクセストークンを解析し、それをREST コネクタが作成する出力メッセージのヘッダーとして追加します：

<arc:set attr="json.text" value="[_response.body]" />
<arc:set attr="json.map:access_token" value="/json/args/token" />
<arc:call op="jsonDOMGet" item="json">
  <arc:set attr="_message.header:access_token" value="[json.access_token | def('Token not found!')]"/>
</arc:call>

次の手順で何が行われるかを詳しく説明します： 1 Arc のREST コネクタにサーバーから返された応答のボディは、_response.body を介してアクセスされ、jsonDOMGet オペレーションのtext 属性に設定されます。jsonDOMGet の他の属性も設定されます。例えば、応答ボディ内の目的のトークンへのjsonpath を持つmap 属性などです。 2 jsonDOMGet オペレーションが呼び出されます。トークンが応答のJSON ボディ内で見つかると、_message.header:access_token 構文を介して、REST コネクタの出力メッセージにメッセージヘッダーとして追加されます。トークンが見つからない場合、access_token ヘッダーの値は静的な文字列 Token not found! に設定されます。 REST コネクタからのメッセージの出力メッセージ詳細を表示すると、Arc ではその結果が次のように表示されます：

この種のスクリプトは、サーバーにリクエストを送信した後にサーバーから返された生のJSON 応答ボディからデータを解析する必要がある場合に役立ちます。その後、ヘッダーを読み取り、フロー内の後続のコネクタで使用できます。

サーバーがXML を使用して応答する場合は、xmlDOMget を使用して同じ結果を得ることができます。

​Key Capabilities

​Overview

​Actions

​Connector Configuration

​REST Details Tab

​Authentication

​Request Details

​Settings Tab

​Configuration

​Advanced Settings

​Advanced Tab

​TLS Client Authentication

​Advanced Settings

​Proxy Settings

​Logging

​Miscellaneous

​Automation Tab

​Automation Settings

​Performance

​Alerts Tab

​SLAs Tab

​Transactions Tab

​Establishing a Connection

​Authenticating

​Testing Request Configurations

​Body Types

​Static Requests

​Dynamic Requests

​Raw Input Data

​Dynamic Form Data

​Dynamic Templates with XML Map

​URL

​Headers

​Response Event

​Response Event Example

​Macros

​Examples

Key Capabilities

Overview

Actions

Connector Configuration

REST Details Tab

Authentication

Request Details

Settings Tab

Configuration

Advanced Settings

Advanced Tab

TLS Client Authentication

Advanced Settings

Proxy Settings

Logging

Miscellaneous

Automation Tab

Automation Settings

Performance

Alerts Tab

SLAs Tab

Transactions Tab

Establishing a Connection

Authenticating

Testing Request Configurations

Body Types

Static Requests

Dynamic Requests

Raw Input Data

Dynamic Form Data

Dynamic Templates with XML Map

URL

Headers

Response Event

Response Event Example

Macros

Examples