# tRESTClient

CXF (JAX-RS)を使用してHTTPおよびHTTPSリクエストを送信し、対応するレスポンスを得ることで、RESTful Webサービスプロバイダーとのインタラクションを行います。

このコンポーネントは、 *Talend Runtime* との統合に優れており、HTTPSサポートが得られます。また、サポートされるQoS機能が増える予定です。

デフォルトで、このコンポーネントはTalend Studioと共には出荷されていません。機能マネージャーを使ってインストールする必要があります。 詳細は、[機能マネージャーを使って機能をインストール](https://help.qlik.com/talend/r/ja-JP/8.0/studio-user-guide/install-features-to-talend-studio)をご覧ください。

## tRESTClientの標準プロパティ

これらのプロパティは、標準ジョブのフレームワークで実行されているtRESTClientを設定するために使われます。

標準のtRESTClientコンポーネントは、ESBファミリーに属しています。

このフレームワーク内のコンポーネントは、すべてのTalend製品で利用できます。

## 基本設定

| プロパティ | 説明 |
| --- | --- |
| [URL] | 呼び出すRESTサーバーのURLアドレスを入力します。[Use Service Locator] (Service Locatorを使用)チェックボックスがオンの場合、このフィールドは表示されず、RESTサーバーのURLはService Locatorサーバーから自動的に取得されます。 |
| Relative Path | 呼び出すRESTサーバーの相対パスを入力します。<br><br>たとえば、http://localhost:8888/services/Customers/listにアクセスする場合:<br><br>[Use Service Locator (Service Locatorを使用)が無効になっている場合: アドレスの最初の部分からどれでもURLフィールドに入力し、2番目の部分を[Relative Path] (相対パス)フィールドに入力できます。たとえば、URLにhttp://localhost:8888、[Relative Path] (相対パス)に/services/Customers/listと入力できます。RESTサーバーの完全パスをURLに入力し、[Relative Path] (相対パス)を空白にしておくことも可能です。<br><br>[Use Service Locator (Service Locatorを使用)が有効になっている場合:Service LocatorによってURLの部分が与えられます。この場合、URLの部分を知っている必要があり、残りの部分を[Relative Path] (相対パス)に指定する必要があります。これは、リクエストするサービスに応じて異なります。たとえばtRESTRequestでは、[REST Endpoint] (RESTエンドポイント)をhttp://localhost:8888/servicesに指定し、[Use Service Locator] (Service Locatorを使用)を有効にします。次に、このサービスを使用する場合は、tRESTClient側で、[Relative Path] (相対パス)に/customers/listを指定します。<br><br>情報メモ警告: 相対パスを使う場合は、コンパイル時の問題を避けるために、host:portだけを指定するのではなく、URLフィールドにサブディレクトリーを少なくとも1つ指定してください。たとえば、http://localhost:8888の代わりにhttp://localhost:8888/servicesを使ってください。 |
| HTTP方式 | このリストから、目的のアクションを説明するHTTP方式を選択します。HTTP方式の具体的な意味は、Webサービスプロバイダーの定義によって異なります。一般的に受け入れられているHTTP方式の定義は、以下のとおりです。<br><br>- GET: 特定のパラメーターをベースにサーバーエンドからデータを取得します。<br><br>- POST: 特定のパラメーターをベースにサーバーエンドにデータをアップロードします。<br><br>- PUT: 特定のパラメーターをベースにデータをアップデートします。データが存在しない場合は作成します。<br><br>- PATCH: 特定のパラメーターをベースにデータを部分的に変更します。<br><br>- DELETE: 特定のパラメーターをベースにデータを削除します。 |
| [Content Type] (コンテンツタイプ) | サーバーエンドにアップロードするコンテンツのメディアタイプに応じて、[XML]、[JSON]、[FORM]のいずれかを選択します。<br><br>このリストは、POST、PUT、またはPATCH HTTP方式を選択した場合のみ表示されます。 |
| [Accept Type] (許可タイプ) | クライアントエンドで、サーバーエンドからの受信を許可するレスポンスのメディアタイプを選択します。<br><br>オプションには、[XML]、[JSON]、[ANY] (すべて)があります。[ANY] (すべて)を選択すると、すべてのタイプのレスポンスメールを受け入れ、文字列に変換します。 |
| クエリーパラメーター | URIクエリーパラメーターを名前/値のペアの形式で指定します。<br><br>このオプションは、GETメソッドで使用する場合がほとんどです。 |
| [Schema] (スキーマ)と[Edit Schema] (スキーマを編集) | スキーマとは行の説明で、処理された後に次のコンポーネントに渡されるフィールドの数を定義するものです。<br><br>このコンポーネントは、3つの組み込み、読み取り専用のスキーマを使用します。<br><br>スキーマストラクチャーを表示するには、[Edit Schema] (スキーマを編集)をクリックします。<br><br>情報メモ警告:<br><br>*スキーマタイプを変更すると、スキーマストラクチャーが失われ、コンポーネントが失敗する可能性があります。* |
| 入力スキーマ | 入力データのスキーマ。このスキーマには2つのカラムが含まれています。<br><br>- [body] (ボディ): ストラクチャー化された入力データのコンテンツを保存します。<br><br>- [string] (文字列): 入力コンテンツが文字列であるか、文字列として処理される場合に、それを保存します。 |
| [Response Schema] (レスポンススキーマ) | サーバーレスポンスのスキーマ。このスキーマは、[Row] (行) &gt; [Response] (レスポンス)リンク経由で次のコンポーネントに渡されます。また、次の3つのカラムが含まれています。<br><br>- statusCode: サーバーエンドからのHTTPステータスコードを保存します。<br><br>- [body] (ボディ): サーバーエンドからのストラクチャー化されたレスポンスのコンテンツを保存します。<br><br>- [string] (文字列): 文字列であるか、文字列として処理される場合に、サーバーエンドからのレスポンスコンテンツを保存します。 |
| [Error Schema] (エラースキーマ) | エラー情報のスキーマ。このスキーマは、[Row] (行) &gt; [Error] (エラー)リンク経由で次のコンポーネントに渡されます。また、次の2つのカラムが含まれています。<br><br>- errorCode: 呼び出し処理中にエラーが発生すると、サーバーエンドからのHTTPステータスコードを保存します。エラーコードの具体的な意味は、Webサービスプロバイダーの定義によって異なります。参照情報は、http://en.wikipedia.org/wiki/List\_of\_HTTP\_status\_codesをご覧ください。<br><br>- errorMessage: エラーコードに対応するエラーメッセージを保存します。 |
| Service Locatorを使用 | このチェックボックスをオンにすると、Service Locatorが有効になります。Service Locatorは、要求およびサービスレベル合意(SLA)を満たすよう、サービスの可用性を維持します。サービスネームスペースとサービス名をそれぞれのフィールドに指定します。 |
| [Use Service Activity Monitor] (サービスアクティビィティモニターの使用) | サービスアクティビティモニタリングを有効にするには、このチェックボックスをオンにします。このオプションにより、イベントがキャプチャーされ、それに関する情報が格納されて、サービスアクティビィティの詳細な分析とビジネストランザクションにおけるメッセージの追跡とトレースが行えます。これはサービス応答時間の分析、トラフィックパターンの特定、根本原因分析の実行などに使用できます。 |
| [Use Authentication] (認証を使用) | RESTサーバーエンドで認証が必要な場合は、このチェックボックスをオンにします。認証タイプを以下から選択します。<br><br><ul> <li> <span>[Basic HTTP] (Basic認証)</span>: <span>[Username] (ユーザー名)</span>と<span>[Password] (パスワード)</span>に認証情報を入力します。</li> <li> <span>[HTTP Digest] (Digest認証)</span>: <span>[Username] (ユーザー名)</span>と<span>[Password] (パスワード)</span>に認証情報を入力します。</li> <li> <span>[SAML Token (ESB runtime only)] (SAMLトークン(ESB実行時のみ))</span>: <span>[Username] (ユーザー名)</span>と<span>[Password] (パスワード)</span>に認証情報を入力します。</li> <li> <span>OAuth2 Bearer</span>: <span>[Bearer Token] (Bearerトークン)</span>フィールドにbase64でエンコードされた認証情報文字列を入力します。</li> <li> <span>[Open ID Connect] (ID接続を開く)</span>: <span>[Username] (ユーザー名)</span>と<span>[Password] (パスワード)</span>に認証情報を入力します。詳細は、<a href="https://help.qlik.com/talend/r/en-US/8.0/esb-infra-services-configuration-guide/talend-identity-and-access-management" target="_blank">Talend Identity and Access Management</a>および<a href="https://help.qlik.com/talend/r/en-US/8.0/administration-center-user-guide/managing-esb-resources-and-authorizations" target="_blank">ESBリソースと認証の管理</a>をご覧ください。</li> </ul><br><br>パスワードを入力するためには、パスワードフィールドの横にある[...]ボタンをクリックし、ポップアップダイアログボックスにパスワードを二重引用符で囲んで入力して[OK]をクリックし、設定を保存します。 |
| [Use Authorization] (認証サービスを使用) | このチェックボックスをオンにして、許可されたコールを有効にします。クライアントのロールを[Role] (ロール)フィールドに指定します。このオプションは、[Use Authentication] (認証を使用)リストで[SAML Token (ESB runtime only)] (SAMLトークン(ESB実行時のみ))を選択すると表示されます。<br><br>ユーザーのロールと権限の管理については、[Managing ESB Resources and authorizations](https://help.qlik.com/talend/r/en-US/8.0/administration-center-user-guide/managing-esb-resources-and-authorizations)と[Talend Identity and Access Management](https://help.qlik.com/talend/r/en-US/8.0/esb-infra-services-configuration-guide/talend-identity-and-access-management)をご覧ください。 |
| [Use Business Correlation] (ビジネスコリレーションを使用) | このチェックボックスをオンにしてこのコンポーネントにコリレーションIDを作成します。<br><br>コリレーションIDは[Correlation Value] (コリレーション値)フィールドで指定できます。この場合、コリレーションIDはIDが呼び出すサービスに渡されます。その結果、連鎖型のサービスコールがこのコリレーションIDの下にまとめられます。このフィールドを空白にすると、実行時にこの値が自動的に生成されます。<br><br>このオプションを有効にすると、tRESTClientはレスポンスヘッダーからコリレーションIDも抽出してコンポーネント変数に保存し、フローで引き続き利用できるようにします。 |
| [Check server identity] (サーバーIDをチェック) | このチェックボックスをオンにすると、URLのホスト名とサーバーの共通名(CN)の一致を確認できるようになります。不一致の場合は、java.io.IOException.HTTPS hostname wrongというエラーが返されます。 |
| [Re-use SSL connection] (SSL接続を再使用) | このオプションはデフォルトで無効になっています。有効になると、1つのジョブで同じサーバーが複数回コールされた場合にSSL設定が一度作成され、他のコールのために再利用されます。<br><br>このオプションは、URLフィールドや[Relative Path] (相対パス)フィールドに設定されたクエリーパラメーターをサポートしません。このオプションを正しく動作させるためには、すべてのクエリーパラメーターを[Query parameters] (クエリーパラメーター)テーブルに追加する必要があります。 |
| [Die on error] (エラー発生時に強制終了) | このチェックボックスをオンにすると、エラーが発生したジョブは強制終了されます。エラーの発生した行をスキップし、エラーが発生していない行の処理を完了するには、このチェックボックスをオフにします。 |

## 詳細設定

| プロパティ | 説明 |
| --- | --- |
| [Log messages] (ログメッセージ) | サービスプロバイダーとコンシューマーの間のメッセージ交換を記録するには、このチェックボックスをオンにします。 |
| [Follow redirects] (リダイレクトをフォロー) | このチェックボックスをオンにすると、自動リダイレクトに従うようになります。 |
| [Allow non-same host redirects] (異なるホストへのリダイレクトを許可) | このオプションは、[Follow redirectes] (リダイレクトをフォロー)が有効である場合に表示されます。このチェックボックスをオンにすると、異なるホストでのリダイレクトが許可されます。 |
| [Maintain session] (セッションを維持) | このオプションは、[Follow redirectes] (リダイレクトをフォロー)が有効である場合に表示されます。このチェックボックスをオンにすると、複数のリダイレクトを行う場合にセッションクッキーを共有できるようになります。セッションクッキーは、メッセージ交換の終了後に他のCookieと同じように収集され、後続の処理で利用できるようになります。<br><br>情報メモ注: このオプションは、Talendが提供するR2022-12以降のTalend Studioマンスリーアップデートをインストール済みである場合のみ利用できます。詳細は管理者にお問い合わせください。 |
| [Enable WebClient Operation Reporting] (WebClientオペレーションレポートの有効化) | このチェックボックスをオンにすると、CXFエンドポイントプロパティがクライアントサイドで設定されます。一部の出力CXFメトリクスインターセプターはこれを使用し、URLを使用してサービスリクエストを追跡します。<br><br>設定されるプロパティはorg.apache.cxf.resource.operation.nameで、HTTP方式名と共にサービスURLが含まれています(たとえば、GET:http: //example.com:8080/service/)。<br><br>このチェックボックスをオンにしていない場合、プロパティは設定されず、一部のメトリクスがカウントされないため、パフォーマンスが向上する場合があります。 |
| [Convert Response To DOM Document] (DOMドキュメントにレスポンスを変換する) | サーバーからのレスポンスをドキュメントタイプに変換する場合は、このチェックボックスをオンにします。<br><br>レスポンスが文字列として処理されるようにするには、このチェックボックスをオフにします。 |
| [Convert Types To Strings] (タイプを文字列に変換) | このオプションは、[Content Type] (コンテンツタイプ)がJSONであるか、[Accept Type] (許可タイプ)がJSONまたは[any] (すべて)の場合に表示されます。JSONのすべての値を引用符の間の文字列に変換するには、このチェックボックスをオンにします。たとえば、このオプションを有効にすると、JSONデータは:<br><br>```<br>"root": {<br>"test": 111<br>}<br>```<br><br>以下に変更されます。<br><br>```<br>"root": {<br>"test": "111"<br>}<br>``` |
| [Drop JSON Request Root] (JSONリクエストルートを削除) | このオプションは、[HTTP Method] (HTTP方式)がPOST、PUT、またはPATCHで、[Content Type] (コンテンツタイプ)がJSONの場合に表示されます。ルートJSONエレメントをドロップするには、このチェックボックスをオンにします。 |
| [Wrap JSON Response] (JSONレスポンスをラップ) | このオプションは、[Basic settings] (基本設定)ビューの[Accept Type] (許可タイプ)リストでJSONが選択されている場合に表示され、デフォルトで有効になっています。<br><br>このチェックボックスをオンにすると、レスポンスは*root*エレメントでラップされます。レスポンスから*root*エレメントを削除するには、このチェックボックスをオフにします。 |
| [Force HTTP version to 1.1] (HTTPバージョンを1.1に強制) | tRESTClientは、デフォルトでHTTPバージョン1.2を使用します。ターゲットHTTPサーバーがHTTP 1.1のみをサポートしている場合、バージョン1.1を有効にするためには、このチェックボックスをオンにします。<br><br>情報メモ注: このオプションは、Talendが提供するR2025-06以降のTalend Studioマンスリーアップデートをインストール済みである場合のみ利用できます。詳細は、管理者にお問い合わせください。 |
| [HTTP Headers] (HTTPヘッダー) | HTTPヘッダーに名前/値のペアを入力して、リクエストされたHTTPオペレーションのパラメーターを定義します。<br><br>HTTPヘッダーの具体的な定義は、REST Webサービスプロバイダーにお問い合わせください。参照情報は、http://en.wikipedia.org/wiki/List\_of\_HTTP\_headersをご覧ください。 |
| [Disable chunked encoding] (チャンクエンコードの無効化) | このオプションは、[HTTP Method] (HTTP方式)がPOST、PUT、またはPATCHの場合に表示されます。payloadのチャンクエンコードを無効にする場合は、このチェックボックスをオンにします。 |
| [Service Locator Customer properties] (Service Locatorの顧客プロパティ) | このオプションは、[Basic settings] (基本設定)タブで[Use Service Locator] (Service Locatorを使用)が有効である場合に表示されます。[+]をクリックして、テーブルに必要なだけのプロパティを追加します。[Property Name] (プロパティ名)フィールドおよび[Property Value] (プロパティ値)フィールドにプロパティの名前と値をそれぞれ入力して、サービスを特定します。 |
| [Service Activity Customer Properties] (サービスアクティビティの顧客プロパティ) | このオプションは、[Basic settings] (基本設定)タブで[Use Service Activity Monitor] (サービスアクティビティモニタリングの使用)が有効である場合に表示されます。[+]をクリックして、テーブルに必要なだけのプロパティを追加します。[Property Name] (プロパティ名)フィールドおよび[Property Value] (プロパティ値)フィールドにプロパティの名前と値をそれぞれ入力して、サービスを特定します。 |
| [Connection timeout] (接続タイムアウト) | クライアントが接続を試みてタイムアウトになるまでの時間を秒数で設定します。*0*に設定すると、接続の試行にタイムアウトがなくなります(デフォルト: 30)。<br><br>このオプションは、 Talend Runtimeでは動作しません。ESBを Talend Runtimeにデプロイする場合、このパラメーターは無効になります。設定ファイル&lt;TalendRuntimePath&gt;/container/etc/org.apache.cxf.http.conduits-common.cfgには、たとえば、HTTPとHTTPSの両方のリクエストを処理し、このHTTPコンジットファイル内にclient.ConnectionTimeoutパラメーターをミリ秒単位で指定するurl = http://.\*のように、サービスを網羅するURLが必要です。[Receive timeout] (受信タイムアウト)オプションを使用する必要がある場合は、client.ReceiveTimeoutもミリ秒で指定してください。 |
| [Receive timeout] (受信タイムアウト) | クライアントがレスポンスを待機してタイムアウトになるまでの時間を秒数で設定します。*0*に設定すると、クライアントは無期限に待機することになります。(デフォルトは60)<br><br>このオプションは[Connection timeout] (接続タイムアウト)オプションに似ています。コンポーネントが Talend Runtimeでデプロイされた後にこのコンポーネントを使用する方法は、[Connection timeout] (接続タイムアウト)オプションをご覧ください。 |
| [Use HTTP proxy] (HTTPプロキシの使用) | プロキシサーバーを使用する場合は、このチェックボックスをオンにします。選択すると、接続の詳細(ホスト、ポート、ユーザー名、パスワード)を入力する必要があります。 |
| [tStatCatcher Statistics] (tStatCatcher統計) | このチェックボックスをオンにすると、ジョブレベルおよび各コンポーネントレベルでジョブ処理メタデータが収集されます。 |

## グローバル変数

| 変数 | 説明 |
| --- | --- |
| グローバル変数 | NB\_LINE: 処理された行の数。これはAfter変数で、整数を返します。<br><br>HEADERS: HTTPレスポンスヘッダー。これはFlow変数で、HTTPレスポンスヘッダー値のリストを返します。<br><br>CORRELATION\_ID: チェーンされたサービス呼び出しがグルーピングされるコリレーションID。これはFlow変数で、文字列を返します。<br><br>ERROR\_MESSAGE: エラーが発生した時にコンポーネントによって生成されるエラーメッセージ。これはAfter変数で、文字列を返します。この変数はコンポーネントにこのチェックボックスが存在し、[Die on error] (エラー発生時に強制終了)がオフになっている場合のみ機能します。<br><br>Flow変数はのコンポーネントの実行中に機能し、After変数はコンポーネントの実行後に機能します。<br><br>フィールドまたは式に変数を入力する場合は、Ctrl + スペースを押して変数リストにアクセスし、使用する変数を選択します。<br><br>変数の詳細は、[コンテキストと変数を使用](https://help.qlik.com/talend/r/ja-JP/8.0/studio-user-guide/contexts-and-variables)をご覧ください。 |

## 使用方法

| 使用方法のガイダンス | 説明 |
| --- | --- |
| **使用ルール** | このコンポーネントは、RESTfulサービスプロバイダーと通信するためにRESTful Webサービスクライアントとして使用され、サービスリクエストをジョブに入力し、ジョブの結果をサービス応答として返すことができます。実行するアクションに応じて、通常はジョブまたはサブジョブ内の開始または中間コンポーネントとして機能します。 |
| [Dynamic settings] (ダイナミック設定) | [ + ]ボタンをクリックしてテーブルに行を追加し、[Code] (コード)フィールドにコンテキスト変数を入力して、[Log messages] (ログメッセージ)、[Use Authentication] (認証を使用)、[Use HTTP proxy] (HTTPプロキシを使用)のいずれかのオプションがランタイムでダイナミックにオン、またはオフになるようにします。テーブルに3行追加すれば、オプションをすべて設定できます。<br><br>ダイナミックパラメーターを定義すると、[Basic settings] (基本設定)ビューまたは[Advanced settings] (詳細設定)ビューで対応するオプションがハイライトされ、利用できなくなります。<br><br>ダイナミックパラメーターの定義法を示すユースケースについては、[コンテキストベースのダイナミック接続によってデータベースからデータを読み取り](https://help.qlik.com/talend/r/ja-JP/8.0/components/defining-context-groups/reading-data-from-databases-through-context-based-dynamic-connections)と、[ダイナミックにロードされた接続パラメーターを使って異なるMySQLデータベースからデータを読み取り](https://help.qlik.com/talend/r/ja-JP/8.0/components/context/reading-data-from-different-mysql-databases-using-dynamically-loaded-connection-parameters)をご覧ください。ダイナミック設定とコンテキスト変数の詳細は、[ダイナミックスキーマ](https://help.qlik.com/talend/r/ja-JP/8.0/studio-user-guide/dynamic-schema)と[コンテキストグループを作成し、その中でコンテキスト変数を定義](https://help.qlik.com/talend/r/ja-JP/8.0/studio-user-guide/creating-context-group-and-define-context-variables-in-it)をご覧ください。 |
| 接続 | 出力リンク:<br><br>[Row] (行): レスポンス、エラー。<br><br>[Trigger] (トリガー): サブジョブがOkの場合、サブジョブがエラーの場合、コンポーネントがOkの場合、ifを実行、コンポーネントがエラーの場合<br><br>入力リンク:<br><br>[Row] (行): メイン、リジェクト。<br><br>[Trigger] (トリガー): 条件付き実行、サブジョブがOKの場合、サブジョブがエラーの場合、コンポーネントがOKの場合、コンポーネントがエラーの場合。<br><br>接続の詳細は、[ジョブにおける接続の使い方](https://help.qlik.com/talend/r/ja-JP/8.0/studio-user-guide/using-connections-in-job)をご覧ください。 |
| 制限事項 | コンテキスト変数をダイナミックエンドポイントやService Locatorのネームスペースに利用できるのは、Talend Studio内のみです。 Talend Runtimeではサポートされていません。 |

**関連概念**

* [tXMLMapでJSONドキュメントをビルドしてRESTサービスを呼び出す](https://help.qlik.com/talend/ja-JP/components/8.0/esb-rest/trestclient-txmlmap-tfileinputdelimited-tfileinputdelimited-building-json-document-with-txmlmap-to-call-rest-service-standard-component "このシナリオでは、REST呼び出しの入力リクエストとしてのtXMLMapコンポーネントでJSONドキュメントをビルドする方法について説明されています。")
* [RESTfulサービスとのインタラクションによってユーザー情報を取得](https://help.qlik.com/talend/ja-JP/components/8.0/esb-rest/trestclient-txmlmap-tlogrow-tlogrow-getting-user-information-by-interacting-with-restful-service-standard-component-this)
* [HTTP POSTリクエストを受け入れてレスポンスを送信するRESTサービスの使用](https://help.qlik.com/talend/ja-JP/components/8.0/esb-rest/trestrequest-trestclient-tlogrow-using-rest-service-to-accept-http-post-requests-and-send-responses-standard-component-esb-this)
* [RESTfulサービスとのインタラクションでユーザー情報をアップデートする](https://help.qlik.com/talend/ja-JP/components/8.0/esb-rest/trestclient-txmlmap-tfileinputdelimited-tfileinputdelimited-updating-user-information-by-interacting-with-restful-service-standard-component-this)
* [データサービスのRESTエンドポイントURLでコンテキスト変数を使用](https://help.qlik.com/talend/ja-JP/components/8.0/esb-rest/trestclient-using-context-variables-in-rest-endpoint-urls-in-data-services-context)