主な機能
- すべてのHTTP メソッド（GET、POST、PUT、PATCH、DELETE）をサポートする完全なRESTful API クライアント
- API の自動設定とリクエスト生成のためのSwagger インポート機能
- OAuth 2.0、Bearer Token、AWS Signature、API Key、Basic / Digest 認証を含む高度な認証
- URL、ヘッダー、フォームデータでのScript サポートによる動的なリクエストの構築
- raw、form-data、URL エンコード、ファイルアップロードを含む柔軟なボディタイプ
概要
REST コネクタは、REST リクエストのヘッダー、認可、ボディ、HTTP メソッドを構築するためのシンプルなインターフェースを提供します。リクエストボディは、コネクタの設定で静的に設定することも、コネクタが処理するファイルに基づいて動的に生成することもできます。アクション
コネクタの設定
設定タブ
コネクタのコア設定に関連する設定。設定
高度な設定
REST Details タブ
コネクタのリクエスト詳細に関連する設定。
| 設定 | 説明 |
|---|---|
| REST Details | コネクタが実行するアクションを選択します。（3つのオプションの詳細については、アクションを参照してください。） |
| Import from Swagger |  アイコンをクリックすると、Swagger URL から直接API の詳細をインポートできます。 |
| Test | フローに送信されるメッセージやトランザクションを作成せずに、現在の設定をテストします。Test をクリックすると、追加のタブを含むウィンドウが開きます（詳細については、リクエスト設定のテストを参照してください）。 |
| Request URL | REST リクエストのHTTP メソッドと送信先HTTP URL です。利用可能なメソッドのオプションは、GET、POST、PUT、PATCH、DELETE です。 |
| Allow Script in URL | クエリが発行される前に、URL 内のScript 式の評価を許可するにはこれをチェックします。これを選択すると、Script エディタボタンが表示され（ ）、Script を使用して動的なリクエストURL を構築できます。詳細については、リクエストURL とヘッダーでのScript エディタの使用を参照してください。 |
| Body Type | REST リクエストとともに供給されるボディコンテンツのタイプです。HTTP メソッドがGET の場合は表示されません。各オプションの説明については、ボディを参照してください。 |
| Content Type | raw データ転送に使用されるコンテンツのタイプです。Body Type がraw に設定されている場合にのみ表示されます。 |
Query Params
このタブを使用して、リクエストURL にクエリパラメータを追加します。パラメータを名前と値のペアとして、必要に応じて説明とともに指定します。Save をクリックして、パラメータでURL を更新します。
api.example.com のリクエストURL は次のようになります：https://api.example.com/orders?status=pending&limit=50
右側の省略記号をクリックすると、Bulk Edit View とHide Description Column の2つのオプションを設定できます。
Authorization
このタブを使用して、API リクエストの認証資格情報を設定します。Headers
このタブでは、送信するREST リクエストに含めるHTTP ヘッダーのリストを追加できます。ヘッダーも名前と値のペアとして指定します。詳細については、静的リクエストと動的リクエストを参照してください。右側の省略記号をクリックすると、Bulk Edit View、Allow Script in Headers、Show Autogenerated Headers の3つのオプションにアクセスできます。Script エディタの使用方法の詳細については、リクエストURL とヘッダーでのScript エディタの使用を参照してください。Body
Body Type がform-data またはx-www-urlencoded に設定されている場合は、Body タブを使用して、リクエストのボディを構成する名前と値のペア（フィールド）のセットを供給します。次のリストでは、各オプションについてより詳細に説明します。
- none：REST リクエストとともにボディは供給されません。
- form-data：ボディは名前と値のペア（フィールド）のセットとして供給されます。Name の横にあるドロップダウンリストを使用して、フィールドタイプを選択します。
- Static：Name とValue の両方を供給します。
- XML：UI でName を供給します。Value は、コネクタが処理するインプットファイルから動的に読み取られます。詳細については、動的フォームデータを参照してください。
- File：各コネクタは、1つのボディフィールドをFile に設定できます。これにより、インプットファイルがリクエストのボディで送信されます。コネクタはインプットファイル自体をフォームデータとして使用するため、Value フィールドはグレーアウトされます。
- Header：Value フィールドを使用して、ボディの読み取り元となるインプットメッセージのヘッダーを指定します。
- Script：供給されたValue はScript としてレンダリングされ、結果の値がリクエストボディで使用されます。
- x-www-urlencoded：ボディはform-data と同じ方法で設定されますが、名前と値のペアはマルチパートフォームデータの代わりにURL クエリ文字列としてエンコードされます。
- raw：ボディは、コネクタが処理するインプットファイルの内容に設定されます。ドロップダウンを使用するか、Header セクションでカスタムヘッダーとして指定して、ボディのContent Type を選択します。
form-data およびx-www-form-urlencoded ボディタイプについて、フィールドごとにコンテンツタイプを供給できます。
Options
リクエストに関連する追加の設定。Advanced タブ
Authentication
高度な設定
前のカテゴリに含まれない設定。Proxy Settings
Logging
Miscellaneous
Automation タブ
Automation 設定
コネクタによるファイルの自動処理に関連する設定。Performance
Alerts タブ
SLAs タブ
Transactions タブ
このタブには、コネクタに関連するすべてのメッセージが一覧表示されます。検索バーを使用して特定のメッセージを見つけるか、じょうごアイコンをクリックしてフィルタを適用します。時刻、メッセージの方向、ステータスでフィルタリングできます。 このタブのオプションは、コネクタのアクションタイプに応じて異なります：- コネクタがTrigger の場合は、Receive Files ボタンを使用してフローを開始します。
- コネクタがTransform またはTerminal の場合は、Upload Files ボタンを使用してファイルをフローにアップロードします。
接続の確立
任意のREST サービスへの接続を確立するには、有効な送信先URL が必要です。サービスURL はさまざまなHTTP メソッドをサポートでき、取得する特定のWeb サービスアクションまたはデータセットに基づいてメソッドを設定してください。サービスによっては、サービスを利用するために認証またはカスタムヘッダーのセットが必要な場合もあります。 Authorization タブのCredentials セクションでは、接続資格情報を指定できます。次のオプションから選択します：- From Connection：以前に設定した の共有Connection を選択するか、Connection フィールドの横にあるプラス記号をクリックして接続の作成を行います。
- No Credentials：パブリックAPI の場合や、クエリパラメータやヘッダーを通じて認証を処理する場合に使用します。送信先URL がHTTPS URL の場合は、TLS Server Certificate をサーバーを識別する公開鍵証明書に設定します。送信先エンドポイントを暗黙的に信頼するには、フィールドを
Any Certificateに設定します。
接続の作成
新しい接続を作成するには、From Connection を選択し、Connection フィールドの横にあるプラス記号をクリックします。- 一意のConnection Name を入力します。
- Type は常にREST に設定されます。
- Auth Scheme を選択します。詳細については、認証を参照してください。
認証
REST コネクタは多数の認証タイプをサポートしており、各タイプには独自の要件があります：- Basic（プレーンテキスト）、Digest（暗号化）、NTLM には、ユーザー名とパスワードによる認証が必要です。これらの資格情報は、リクエストのヘッダーとしてREST サービスに供給されます。
- OAuth 認証には、REST サービスのWeb ポータルまたは開発コンソールでのアプリ登録が必要です。アプリ登録に含めるCallback URL は のUI に表示されます。REST サービスに適用されるGrant Type を選択し、REST サービスのWeb ポータルまたは開発コンソールに表示される詳細から残りの設定を指定します。次に、Get New Access Token をクリックして、サービスとやり取りするために必要なトークンを取得します。最初のトークンが取得されると、アプリケーションはトークンが有効期限に近づくとトークンを更新します。
- Bearer Token 認証には、サービスのWeb ポータルまたは開発コンソールから取得したトークンが必要です。
- AWS Signature 認証（Amazon に対する認証用）には、Amazon が提供する設定資格情報（Access Key、Secret Key など）が必要です。
- API Key 認証にはキーと値のペアが必要で、その後、キーをヘッダーとして追加するかクエリパラメータとして追加するかを指定する必要があります。
リクエスト設定のテスト
フローに送信されるメッセージやトランザクションを作成せずに、いつでも現在の設定をテストできます。REST Details タブでTest をクリックします。次の画像は、Trigger コネクタのテストが成功した際のResponse Body の結果を示しています。
- Response Body：サーバーから返された形式でREST リクエストの出力を表示します。
- Response Headers：サーバーから返されたレスポンスに含まれていたレスポンスヘッダーを表示します。
- Message Headers：テストの出力に含まれていたメッセージヘッダーを表示します。
- Log：テストログを表示します。
- XML タブは、次の画像に示すように、リクエストのボディでXML フィールドを定義した場合にのみ表示されます。
- Allow Script in URL またはAllow Script in Headers がチェックされている場合は、Headers タブを使用して、スクリプトのコンテキストで使用される可能性のあるメッセージヘッダーを供給します（これらのオプションの詳細については、リクエストURL とヘッダーでのScript エディタの使用を参照してください）。リクエストに
form-dataまたはx-www-form-urlencodedボディの要素として設定されたHeader がある場合、ここにヘッダー名が表示され、テストで使用する値を供給できます。 - Logs タブには、最後のテストの結果が含まれます。
静的リクエスト
完全に静的なコンテンツを持つREST リクエスト（HTTP GET メソッドを使用するリクエストなど）は、リクエストコンテンツがコネクタのUI で完全に設定されるため、インプットファイルを必要としません。必要な名前と値のペアを、Header セクションのカスタムヘッダーまたはBody セクションのフォームデータとして追加するだけです。 受信オートメーションが有効な場合、静的リクエストはスケジュールに従って自動的に送信できます。各リクエストへのレスポンスは、アウトプットフォルダに保存されるか、フロー内の次のコネクタに渡されます。 送信オートメーションが有効な場合、コネクタのトランザクションフォルダに到着したファイルも静的リクエストをトリガーします。インプットファイルの内容は無視され、リクエストはUI の設定に従って送信されます。動的リクエスト
REST リクエストには、コネクタのトランザクションフォルダに到着するファイルのデータを動的に取り込むことができます。Raw インプットデータ
リクエストのBody Type をraw に設定すると、インプットファイルの内容がREST リクエストのボディとして送信されます。
Content Type ドロップダウンを使用して、データの特定のコンテンツタイプを設定します。必要なコンテンツタイプがリストにない場合は、Header セクションに_Content-Type_ ヘッダーを追加できます。
動的フォームデータ
リクエストのBody Type をform-data またはx-www-urlencoded に設定すると、コネクタはインプットファイルから特定の値を探してリクエストに取り込みます。XML に設定された各名前と値のペアについて、コネクタはインプットファイルをスキャンして、フィールド名と同じ名前を共有し、次に示す特定のXML 構造を使用するXML 要素を探します：
CustomerID という名前の動的フィールドがあり、インプットファイルに次のXML が含まれている場合、REST コネクタはCustomerID フィールドの値を12354 に設定します。
XML Map を使用した動的テンプレート
XML Map コネクタをREST コネクタと組み合わせて使用すると、他のXML データ構造から動的なリクエストを簡単に構築できます。XML Map コネクタは、カスタムXML 構造をREST コネクタが期待するXML 構造に変換します。 まず、リクエストに存在すべき動的（および静的）なBody フィールドのセットでREST コネクタを設定します。次に、 のフローでXML Map コネクタをREST コネクタに接続し、フローの変更を保存します。これにより、XML Map コネクタは、REST コネクタが受信するインプットファイルで期待するフィールドを検出できます。 その後、XML Map コネクタ内で、Destination File ドロップダウンにREST リクエストスキーマが含まれます。これをDestination として選択し、Source File をカスタムXML 構造に設定します。これによりXML Map のマッピングエディタが取り込まれ、REST リクエストに含める必要があるデータをソース構造から送信先構造にドラッグアンドドロップできます。マッピングが完了すると、XML Map コネクタは、ソースファイルに一致するファイルを有効なREST リクエスト構造に自動的に変換します。 XML Map コネクタの使用方法の詳細については、XML Map コネクタのドキュメントを参照してください。動的ヘッダー
Script の式を評価して、ヘッダー値として動的な文字列を生成することもできます。詳細と例については、Headers を参照してください。リクエストURL とヘッダーでのScript エディタの使用
下に示すScript エディタを使用して、リクエストURL とヘッダーを構築できます。次の画像はリクエストURL エディタを示していますが、ヘッダー値エディタも同じように機能します。
http://myendpoint.com/api?day=[_ | now('yyyyMMdd HH:mm:ss')]
この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]
式を直接URL に追加することも、エディタを使用して記述することもできます。
Allow Script in Headers を選択すると、クエリが発行される前にヘッダー内のScript 式の評価が有効になります。例えば、次のヘッダーには日付と時刻が含まれています：
Timestamp [_ | now('yyyyMMdd')]
このヘッダーには、送信オートメーションを通じてトリガーされるクエリのための顧客Id が含まれています：
Customer [_message.header:customerid]
メッセージヘッダー
メッセージヘッダーは、 がフロー全体のデータの進行状況を追跡するのに役立ちます。すべての追跡されたヘッダーはエディタのMessage Header タブに表示され、式の中で参照できます。 エディタのAdd Message Header フィールドを使用して既存のヘッダーの名前を指定することで、式に他のメッセージヘッダーを含めることもできます。これらは追跡されたヘッダーである必要はありません。Vault
Vault タブを使用して、グローバル設定Vault のアイテムを式に追加します。これは、フロー全体のさまざまな場所で再利用する値がある場合に便利です。それらの値をVault で定義し、式の先頭で参照できます。マッピングでVault のアイテムの_値_ を使用したい場合は、角括弧内で参照する必要があることに注意してください。そうしないと、エディタはアイテムの_名前_ をリテラルとして解釈します。フォーマッタ
フォーマッタは、異なるxpath で返される値の操作をサポートします。フォーマッタは式の中でパイプ文字（|）で区切られ、左から右に評価されます。例えば：[xpath('City') | toupper | substring(0,3)]
この例では、City xpath の値が返される前に、すべての文字列文字が大文字に変換され、最初の3文字の部分文字列が結果として返されます。例えば、ソースドキュメントが次の値を持っていたとします：
<City>Durham</City>
結果の式は次を返します：
DUR
フォーマッタはFormatters タブに一覧表示されます。リスト内のフォーマッタをクリックして式に追加します。
レスポンスイベント
REST コネクタでレスポンスイベントを使用して、サーバーから受信したレスポンス（ボディ、ヘッダー、クッキーなどを含む）とやり取りし、コネクタが生成するアウトプットメッセージを強化できます。Response イベントでは、次の特別なアイテムを使用できます。
レスポンスイベントの例
次のスクリプトは、REST 呼び出しから受信したJSON レスポンスを読み取り、JSON に含まれるアクセストークンを解析して、REST コネクタが作成するアウトプットメッセージにヘッダーとして追加します：_response.body を介してアクセスされ、jsonDOMGet オペレーションのtext 属性に設定されます。jsonDOMGet の他の属性も取り込まれます。例えば、レスポンスボディ内の目的のトークンへのjsonpath を持つmap 属性などです。
2 jsonDOMGet オペレーションが呼び出されます。トークンがレスポンスJSON ボディで見つかった場合、_message.header:access_token 構文を介してREST コネクタのアウトプットメッセージにメッセージヘッダーとして追加されます。トークンが見つからない場合、access_token ヘッダーの値は静的な文字列：Token not found! に設定されます。
REST コネクタからのメッセージのアウトプットメッセージ詳細を表示すると、 ではその結果は次のように表示されます：
