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}

パラメーター名 = api_version

パラメーター値 = 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

クエリー = Main

• 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] (フォームデータ): 属性名と値のペアを持つマルチパートフォームを使ってボディを作成します。Data Shaping Selector Language構文を使ってプレースホルダーを定義すると、受信レコードから抽出された値で一部が動的に入力されます。
• X_WWW_FORM_URLENCODED: 属性名と値のペアでURLエンコードされた形式を使ってボディを作成します。Data Shaping Selector Language構文を使ってプレースホルダーを定義すると、受信レコードから抽出された値で一部が動的に入力されます。

• TEXT: プレーンテキストのメッセージを返す場合はこの形式を選択します。この場合、レスポンスペイロードは解析されず、そこからサブ部分を抽出することも、[Output key/value pair] (出力キー/値のペア)のパラメーターで{.response...}プレースホルダーを使用することもできなくなります。
• JSON: 受信したレスポンスがJSON形式の場合はこの形式を選択します。その場合、ペイロードは正しく解析されたJSONレコードに変換されます。

(回答ボディの形式がJSONまたはXMLの場合のみ利用可能)

ボディレスポンスがJSONまたはXMLとして解析される場合は、レスポンスペイロードのサブ部分のみ返すことができます。値の抽出にはData Shaping Selector Language構文が使われます。配列が検出されると、項目は次々に返されます。

• [Body] (ボディ): [Answer body format] (回答ボディの形式)がTEXTの場合は、bodyというString属性を持つレコードが生成され、その中にペイロードがすべてコピーされます。

  [Answer body format] (回答ボディの形式)がJSONの場合は、解析されたドキュメントの階層ストラクチャーを表すレコードが生成されます。

• [Status, headers and body] (ステータス、ヘッダー、ボディ): レコードの生成は、HTTPステータスコードが含まれているstatus属性(Int型)、すべてのレスポンスヘッダーがネスト済みレコードであるheaders属性、ペイロード全体がテキストとして含まれている単純文字列([Answer body format] (回答ボディの形式)はTEXT)または解析済みドキュメントを表す階層型オブジェクトであるbody属性で行われます。

• [Name] (名前): 出力する属性の名前を入力します。
• [Value] (値): 属性の値を入力します。静的値、受信レコードからの抽出値、現在のHTTPクエリーの結果のいずれかです。入力レコードの値や現在のHTTPCallのレスポンスは、次のようにそのプレフィックスで識別されます。
  • {.input}: 入力レコードでのセレクター
  • {.response}: レスポンスでのセレクター

例:

名前 = id

値 = {.response.user.id}

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

• [Preset] (事前設定): ページネーションをサポートしている一般的なサービスについては、定義済み設定を選択します。選択したら、[Load selected preset] (選択された事前設定をロード)をクリックし、選択された環境のページネーションフォームをアップデートします。

  詳細は、Box、JIRA、ODataのドキュメンテーションをお読みください。

• [Pagination strategy] (ページネーション方式): クエリー中のHTTPサービスに実装されているページネーション方式です。現在のところ、サポートされている方式はオフセット/制限のみです。
• [Location] (ロケーション): オフセットと制限のパラメータを設定する場所を選択します。クエリーパラメーターとヘッダーのいずれかです。
• [Name of the offset] (オフセットの名前): オフセットとして使われるパラメーターの名前を入力します。
• [Value of the offset] (オフセットの値): オフセットの初期値を設定します。0と入力すると、最初のセットから開始されます。

  Data Shaping Selector Language構文を使えば、受信レコードからこの値を取得できます。

  例: {.input.last_page_info.offset}

• [Name of the limit] (制限の名前): 返されるエレメントのページあたりの最大数を定義するために使われるパラメーターの名前を入力します。
• [Value of the limit] (制限の値): ページ内で返されるエレメントの最大数を設定します。ページが返される時のエレメントが0個の場合、ページネーションは停止します。
• [Path to elements] (エレメントへのパス): 返されるエレメントが含まれているJSON配列へのパスを定義します。これはJSON配列であることが必要です。[Offset/limit] (オフセット/制限)は、この配列にあるエレメントの数をカウントし、空になった時点でページネーションを継続または停止します。[Offset/limit] (オフセット/制限)ページネーションが有効であり、このパラメーターが設定されている場合は、これが[Main] (メイン)設定にある[Extract a sub-part of the response] (レスポンスのサブ部分を抽出)のルートとなります。

  例:

  [JIRA/search] (JIRA/検索)ページネーションを選択した場合、問題はデフォルトによって.issues 配列で返されるので、[Path to elements] (エレメントへのパス) にこの値を入力する必要があります。ただし、Jiraキーだけが返されるようにしたい場合、[Extract a sub-part of the response] (レスポンスのサブ部分を抽出)に.keyと設定すると、キーがissuesに存在するエレメントの属性であってもキーが返されます。

• [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が選択された場合に利用できます。