HTTPクライアントのプロパティ

アクセスしたいベースURLアドレスを入力します。

例: https://www.example.com/v1.0/

URLの2番目の部分は、HTTPクライアントのデータセット設定のPathパラメーターで設定する必要があります。

また、Data Shaping Selector Language構文を使ってプレースホルダーを定義すると、受信レコードから抽出された値で一部が動的に入力されます。例:

ベースURL = "https://{.input.job_url}"、およびパス = "{.input.job_url_path}"

• [No authentication] (認証なし): サーバーへのアクセスで認証が必要とされない場合
• [Basic] (基本): ユーザー名とパスワードが求められます(corresponding documentationをご覧ください)。
• [Digest] (ダイジェスト): ユーザー名とパスワードが求められます(corresponding documentationをご覧ください)。
• [Bearer Token] (Bearerトークン): 生のアクセストークンが求められます。Authorization: Bearer <your token>としてHTTPリクエストヘッダーに組み込まれます。
• NTLM: ユーザー名(ドメイン名を含む場合あり)とパスワードが求められます(corresponding documentationをご覧ください)。
• [API Key] (APIキー): 渡す場所、名前、プレフィックスを選択できるなど、柔軟な方法でAPIキートークンをサーバーに渡します。
  • [Destination] (デスティネーション): トークンを設定する場所として、指定された名前を持つHTTPヘッダー、または指定された名前を持つHTTPクエリパラメーター(トークンがログに残る可能性があるため推奨しません)を指定します。
  • [Name] (名前): ヘッダーまたはクエリーパラメーターの名前を入力します。
  • [Prefix] (プレフィックス) (オプション): トークンの前に追加するプレフィックスを入力します([Destination]　(デスティネーション)が[Request header] (リクエストヘッダー)である場合のみ)。
  • [Token] (トークン): 認証トークンを入力します。
• OAuth 2.0 は、OAuthサーバーに対するアクセストークンの取得と更新を自動的に管理した後、Bearerトークンとしてターゲットエンドポイントに渡します。
  • [Flow] (フロー): 実行したいOAuthフローです。現在のところ、サポートされているのは[Client Credentials] (クライアント認証情報)フローのみです。
  • [Authentication mode] (認証モード): サポートされているどの認証方式についても、フローとスコープのパラメーターがボディで設定されます。使用される形式はapplication/x-www-form-urlencodedで、キーはgrant_type=xxx&scope=xxxxとなります。
  • [Token endpoint] (トークンエンドポイント):
  • oauth2/mydomain.com/tokenという形式で認証トークンを入力します。
  • [Client ID] (クライアントID)と[Client secret] (クライアントシークレット): クライアントIDとクライアントシークレットを入力します。
  • [Additional parameters] (追加パラメーター): 追加したい属性(たとえばscope)を入力します。

アクセスしたいベースURLアドレスを入力します。

例: https://www.example.com/v1.0/

URLの2番目の部分は、HTTPクライアントのデータセット設定のPathパラメーターで設定する必要があります。

この切り替えを有効にすると、クライアントとサーバー間の接続はHTTPかSOCKSプロキシを介して確立されます。

• [Proxy type] (プロキシタイプ): 使用したいプロキシのタイプを選択します。HTTPプロキシでは基本認証がサポートされています。
• [Proxy host] (プロキシホスト)と[Proxy port] (プロキシポート): プロキシのアドレスとポートを入力します。
• [Proxy login] (プロキシログイン)と[Proxy password] (プロキシパスワード) (HTTPのみ): プロキシへの認証に必要な認証情報を入力します。

• [Initial backoff (ms)] (初期バックオフ(ミリ秒)): HTTPコールの最初の再試行までの待機時間をミリ秒単位で入力します。
• [Backoff factor] (バックオフ係数): 試行が失敗した場合、各コール間の遅延を増加させるため、待機時間にはこの係数が掛け合わされます。係数が1の場合、遅延はすべて同じ値になります。
• [Maximum number of retries] (最大再試行回数): 1つのHTTPクエリーの最大試行回数を入力します。初回コールはこの数字に含めないようにしてください。

次の設定の例:

初回バックオフ: 300ミリ秒、バックオフ係数: 2、最大試行回数: 4

HTTP Clientコネクターはサーバーに対して最初のGET操作(第1コール)を行います。接続タイムアウトエラーが返され、再試行メカニズムが作動し、コネクターは300ミリ秒待機します。その後、2回目(第1再試行)が行われます。503HTTPレスポンスが返されると、待機時間が2倍になり、コネクターは600ミリ秒待機します。その後、3回目(第2再試行)が行われます。500内部サーバーエラーが返されると、待機時間がさらに2倍になり、コネクターは1200ミリ秒待機します。4回目(第3再試行)が行われ、今回は成功します。追加試行は行われず、レスポンスが返されます。

• [Batch] (バッチ) HTTPクエリーを1回だけ実行したい場合に選択します。このデータセットを使用するパイプラインはバッチパイプラインとなります。
• [Streaming] (ストリーミング): ストリーミングパイプラインでHTTPクエリーをNミリ秒ごとに実行したい場合に選択します。このデータセットを使用するパイプラインはストリーミングパイプラインとなります。ポーリング間隔は、ソースデータセットの[Min poll interval (ms)] (最小ポーリング間隔(ミリ秒))フィールドでミリ秒単位で定義できます。

このデータセットが作成された接続の構成で前に設定されたURLの2番目の部分を入力します。両者を連結したものによって、このデータセットで対象としているリソースが決定されます。

ベースURL (接続)の値とパス (データセット)の値は連結し、必要であれば/という文字が追加されます。

また、Data Shaping Selector Language構文を使ってプレースホルダーを定義すると、受信レコードから抽出された値で一部が動的に入力されます。例:

ベースURL = "https://{.input.job_url}"、およびパス = "{.input.job_url_path}"

このオプションを有効にすると、名前-値ペアの形式でベースURLまたはパスを完成させるために必要な追加パラメーターを指定できます。

たとえばベースURLがhttps://www.example.comでパスが/{api_version}であれば、このテーブルにパラメーターを追加し、[Name] (名前)をapi_versionに、[Value] (値)をv1.0にすることでパスを設定できます。

• [Name] (名前): パラメーターの名前を入力します。
• [Value] (値): パラメーターの値を入力します。静的値(UUID-1234567など)、受信レコードからの抽出値({.input.user.id}など)、両方の混合値(UUID-{.input.user.id}など)のいずれか

例: クエリーパラメーター名 = entityId、およびクエリーパラメーター値 = UUID-1234567

• [Name] (名前): ヘッダーの名前を入力します。
• [Value] (値): ヘッダーの値を入力します。静的値(text/html; charset=utf-8など)、受信レコードからの抽出値({.input.meta.content}など)、両方の混合値(text/{.input.document.format}; charset={.input.document.charset}など)のいずれか
• [Query] (クエリー): このヘッダー設定を適用するクエリーを選択します。

例: ヘッダー名 = Content-Type、およびヘッダー値 = text/html;charset=utf-8

• [Text] (テキスト): ドロップダウンリストの下にあるテキストフレームに、メッセージのボディをプレーンテキストで入力します。Data Shaping Selector Language構文を使ってプレースホルダーを定義すると、受信レコードから抽出された値で一部が動的に入力されます。例:

  id={.input.user.id}
  name={.input.user.name}  

• JSON: ドロップダウンリストの下にあるテキストフレームに、メッセージのボディをJSON形式で入力します。Data Shaping Selector Language構文を使ってプレースホルダーを定義すると、受信レコードから抽出された値で一部が動的に入力されます。例:

  {
   "id": "{.input.user.id}",
   "name": "{.input.user.name}",
   "age": "{.input.user.age}",
   }

• XML: ドロップダウンリストの下にあるテキストフレームに、メッセージのボディをXML形式で入力します。Data Shaping Selector Language構文を使ってプレースホルダーを定義すると、受信レコードから抽出された値で一部が動的に入力されます。例:

  <user>
   <id>{.input.user.id}</id>
   <name>{.input.user.name}</name>
   <age>{.input.user.age}</age>
  </user>

• [Form data] (フォームデータ)とx_www_urlencoded: 属性名と値のペアを持つマルチパートフォーム、または属性名と値のペアを持つURLエンコードフォームを使ってボディを作成します。ドロップダウンリストの下にあるテーブルの行に、属性の名前と値を入力します。Data Shaping Selector Language構文を使ってプレースホルダーを定義すると、受信レコードから抽出された値で一部が動的に入力されます。

• [Binary] (バイナリ): 500MBを超えるデータファイルを分割してアップロードする場合は、このオプションを選択します。選択すると、[File path] (ファイルパス)フィールドが表示され、ローカルアップロードフォルダーを指定できるようになります。

• [Text] (テキスト): プレーンテキストのメッセージを返す場合はこの形式を選択します。この場合、レスポンスペイロードは解析されず、そこからサブ部分を抽出できなくなります。
• JSON: 受信したレスポンスがJSON形式の場合はこの形式を選択します。その場合、ペイロードは正しく解析されたJSONレコードに変換されます。

このフィールドはオプションであり、JSONレスポンス全体を取得するためには空のままにしておく必要があります。

使用例については、HTTPクライアントを使ったデータの抽出方法に関する追加情報をお読みください。

• [Body] (ボディ): [Response body format] (レスポンスボディ形式)ドロップダウンリストで[Text] (テキスト)が選択された場合、bodyという文字列属性を1つだけ持つレコードが生成され、その中にペイロードがすべてコピーされます。[Response body format] (レスポンスボディ形式)ドロップダウンリストでJSONが選択された場合は、解析済みドキュメントの階層ストラクチャーを表すレコードが生成されます。制限事項: メインフロー内のボディ部分が200MBを超えると、レコードは切り詰められ、警告がスローされます。

• [Status, headers and body] (ステータス、ヘッダー、ボディ): レコードの生成は、HTTPステータスコードが含まれているstatus属性(INT型)、すべてのレスポンスヘッダーがネスト済みレコードであるheaders属性、ペイロード全体がテキストとして含まれている単純文字列([Reponse body format] (レスポンスボディ形式)ドロップダウンリストからTextが選択された場合)、または解析済みドキュメントを表す階層型オブジェクト([Reponse body format] (レスポンスボディ形式)ドロップダウンリストでJSONが選択された場合)であるbody属性で行われます。制限事項: メインフロー内のボディ部分が200MBを超えると、レコードは切り詰められ、警告がスローされます。
• [Download file only] (ファイルのみダウンロード) このオプションを選択すると、メインフローで返されるコンテンツを制限し、HTTPレスポンスボディをファイルとしてダウンロードするかキャッシュするのみとなるため、メインフローにレコードをビルドせずにリソースを節約します。このオプションは、Talend Studioのオンプレミスコンポーネントでの使用を想定しており、Talend Cloudでの使用は推奨されません。

値はコンポーネントの入力値かHTTPレスポンスから選択できます。値がコンポーネント入力からの場合は[Value] (値)に"{.input.<dssl_path>}"と、HTTPレスポンスの場合は"{.response.<dssl_path>}"と入力します。

HTTPサーバーからデータを取得する場合は、スキーマ、[Guess schema] (推測スキーマ)ボタン、[Response body format] (レスポンスボディ形式)オプション、[Returned content] (返されたコンテンツ)オプション、[Extract a sub-part of the response] (レスポンスのサブ部分を抽出)オプション、[Output key/value pairs] (出力キー/値のペア)オプションを使い、取得するデータの形式とコンテンツを指定できます。詳細は、tHTTPClient: 設定と出力をご覧ください。

このオプションは、[Output key/value pairs] (出力キー/値のペア)が選択されている場合に利用できます。

• [Maximum number of redirects] (最大リダイレクト数): コネクターが従う最大リダイレクト数を設定します。設定した数を超えるリダイレクトがある場合は、最後のリダイレクトがクエリーの結果として返されます。
• [Redirect only on same host] (同じホストでのみリダイレクト): 同じホストを使用している場合のみリダイレクトを実行したい場合は、このオプションを有効にします。

なお、ページネーションはJSONペイロードとのみ互換性があります。目的のエレメントはJSONペイロード内の配列であることが必要です。

ページネーションを正しく動作させるためには、次のオプションを設定する必要があります。

• [Pagination strategy] (ページネーション方式): 使用するページネーション方式を選択します。
  • [Offset/limit] (オフセット/制限): このストラテジーは、特定サイズのページの特定の位置から始まるエレメントを取得します。offsetパラメーターは最初のエレメントからのオフセットによって開始エレメントを指定します。limitパラメーターは、エレメントの数によってページの最大サイズを指定します。このストラテジーを適用した場合、最後の呼び出しで0個のエレメントが返されるとページネーションが停止します。
  • マーカー: このストラテジーは、「マーカー」(多くの場合、最後に取得した項目のID)を使用して、次の結果セットを取得します。マーカーは、データの次のページがどこから始まるかを示すポインターとして機能し、APIがマーカー以降の結果を返すことを可能にします。このストラテジーを適用すると、レスポンスにマーカー要素が含まれている場合にページネーションが停止します。
  • Next link(次リンク): このストラテジーは、レスポンスに「次のリンク」(またはURL)が提供され、クライアントはそのリンクを使用して次の結果セットを取得できます。「next link(次リンク)」には、クライアントが次のページを取得するために使用できるオフセットまたはページ番号が含まれています。このストラテジーを適用すると、レスポンスにnext link(次リンク)要素が含まれている場合にページネーションが停止します。
• [Location] (ロケーション): オフセットパラメーターと制限パラメーターの設定方法を指定します。[Query parameters] (クエリーパラメーター)と[In headers] (ヘッダー内)のいずれかとなります。
• [Name of the offset] (オフセットの名前): オフセットとして使われるパラメーターの名前を設定します。
• [Value of the offset] (オフセットの値): オフセットを設定するために使われます。最初のエレメントから開始する場合は、0に設定します。'{.input.last_page_info.offset}'というDSSL式を使えば、受信レコードからクエリーのオフセットを取得できます。
• [Name of the limit] (制限の名前): ページ内で許可されているエレメントの最大数を定義するパラメーターの名前を設定するために使われます。
• [Value of the limit] (制限の値): 制限値、つまりページ内で返されるエレメントの最大数を設定します。ページが返される時のエレメントが0個の場合、ページネーションは停止します。
• [Path to elements] (エレメントへのパス): 目的のエレメントが含まれているJSON配列へのパスを設定するために使われます。これはJSON配列であることが必要です。offset/limit方式が適用された場合、[Extract a sub-part of the response] (レスポンスのサブ部分を抽出)オプションの設定にかかわらず、このパラメーターで指定されたエレメントがルートになります。たとえば[Preset] (事前設定)フィールドでJIRAが選択された状態で[Path to elements] (エレメントへのパス)を.issueに設定した場合、問題に存在するエレメントの属性をkeyと仮定すると、[Extract a sub-part of the response] (レスポンスのサブ部分を抽出)が.keyに設定されていても問題が取得されます。
• [Preset] (事前設定): ページネーション方式をサポートする特定のサービスについて、該当するサービスを選択して事前設定を行います。サービスを選択するためには、このフィールドの横にある[...]ボタンをクリックしてサービスを選択します。選択できるサービスは次のとおりです。
  • BOX: 詳細は、Offset-based Paginationをご覧ください。
  • JIRA: 詳細は、JIRA Server platform REST API referenceをご覧ください。
  • OData: 詳細は、OData Version 4.01. Part 1: Protocolをご覧ください。
• [Load selected preset] (選択された事前設定をロード): このボタンをクリックすると、[Preset] (事前設定)フィールドで選択された事前設定がロードされます。

• [Normalize attributes] (属性を正規化): 期待されているデータ型に値を変換できます。
• [Normalize arrays] (配列を正規化): JSON配列の一部のエレメントでフィルタリングできます。

  例:

  このJSONドキュメントを取得するようコンポーネントを設定した場合、これらのJSONの不一致がジョブ実行コンソールに返されます:

  Some JSON inconsistencies has been identified:
                                      .users.*.addresses is not consistently present in all objects.
                                      .users.*.active is not consistently present in all objects.
                                      .users.*.email is not consistently present in all objects.
                                      .users.*.addresses is an array that contains items of several types: STRING, OBJECT.
                                      .users.*.addresses.*.country is not consistently present in all objects.
                                      .users.*.addresses.*.street is not consistently present in all objects.
                                      .users.*.addresses.*.zipcode is found with varying types: STRING, INT.
                                      Please, have a look to advanced settings JSON normalization to fix it.

  これを防ぐためには、たとえば[Normalize attributes] (属性を正規化)オプションを使い、たとえ返される値がString型であっても.、.users.*.addressesというパスを持つ属性をARRAY型に、users.*.addresses.*.zipcodeというパスを持つ属性をINT型にそれぞれキャストします。また、.users.*.activeのように、不足している属性も追加できます(ここでは'true'か'false'のいずれかを返すのでBOOLEANとしてキャスト可能）。

  さらに配列の正規化オプションを使い、アドレスにString型も含まれている場合でも、.users.*.addressesにOBJECTエレメントのみを保持させることもできます。

このオプションは、コンポーネントの[Basic settings] (基本設定)ビューの[Response body format] (レスポンスボディ形式)ドロップダウンリストでJSONが選択された場合に利用できます。