提供: Bright Pattern Documentation
• English
URLの取得
「URLの取得」シナリオブロックは、指定されたメソッドを使用してURLからWebコンテンツを取得し、それをシナリオ変数に解析します。
|
HTTP、HTTPS 基本認証、Bearer トークン、および OAuth 2.0 クライアント認証情報がサポートされています。Webクライアント認証情報 アカウントを作成し、URLの取得ブロック間で再利用できるよう認証情報を保存してください | |
条件付き終了
「URLの取得」ブロックでは、次の3つの条件付き終了のいずれかが実行されます：
- 失敗
- HTTPメソッドの実行中にエラーが発生した場合、またはHTTPレスポンス本文を解析できない場合、「失敗」の条件付き終了が実行されます。詳細については、以下の HTTP レスポンスコード を参照してください。
- データなし
- HTTPレスポンス本文にデータが返されない場合、「データなし」の条件付き終了が実行されます。
- タイムアウト
- 処理時間が「リクエストタイムアウト」フィールドに入力された値を超過した場合、「タイムアウト」の条件付き終了が実行されます。
設定
- タイトルテキスト
- フローチャートに表示される、このブロックのインスタンス名です。
- リクエストタイプ
- フェッチに使用される HTTP メソッドです。
リクエストタイプ（HTTPメソッド） コンテンツタイプ メモ GET - application/json
- application/x-www-form-urlencoded
- application/soap+xml; charset=utf-8
POST - application/json
- application/x-www-form-urlencoded
- application/soap+xml; charset=utf-8
- multipart/form-data
- <単一ファイルのアップロード；コンテンツタイプは以下で設定>
PUT - application/json
- application/x-www-form-urlencoded
PATCH - application/json
- application/x-www-form-urlencoded
DELETE - application/json
- application/x-www-form-urlencoded
- フェッチ先のURL
- このブロックがアクセスする Web リソースの HTTP/HTTPS URL です。クエリ文字列パラメータがある場合は、URLパラメータで指定してください。パラメータが定義されている場合、それらはURLに追加されます。「?」および「&」の区切り文字は自動的に挿入されます。
- 追加ヘッダー
- リクエストに追加するHTTPヘッダーです。通常は認証の目的で使用されます。関数は、値として挿入することで使用できます。「追加」をクリックしてヘッダーを定義し、名前と値を入力してください。
- 例えば、決済ゲートウェイには、「Authorization」ヘッダーと、時刻、ユーザー名、パスワードのSHA-256ハッシュによる認証を必須とするRESTfulインターフェースがある場合があります。認証を有効にするには、名前を
Authorization、値をbearer $(accessid)のような形式でリクエストヘッダーに指定します。ここで、「accessid」には=hmac('SHA-256', '<key>', '<user>:<secret>')のような値が設定されます。
- OAuth 2.0エンドポイントでの認証も、通常は同様のパターンに従います。アクセストークンを取得したら（例：別のFetch URLブロックがトークンエンドポイントを呼び出し、結果を'accessToken'に保存するなど）、そのトークンを
Authorizationヘッダーに、値bearer $(accessTokenVariable)として渡すことができます。
- シナリオビルダーの関数に関する詳細については、 組み込み関数を参照してください。
- URLパラメータ
- URLエンコードされてURLに追加されるパラメータです。シナリオ変数は、$(varname)の形式で挿入することで使用できます。「追加」をクリックしてURLパラメータを定義し、名前と値を入力してください。
- コンテンツタイプ
- リクエスト本文で送信される、またはレスポンス本文で受信されるデータのタイプです。
- コンテンツタイプのドロップダウンには、最も一般的な候補が表示されていますが、ドロップダウンボックスの候補欄に直接入力することで、独自のコンテンツタイプ値を手動で指定することも可能です。
- JSONデータ構造の場合はapplication/json、URIエンコードされたデータの場合はapplication/x-www-form-urlencoded、XMLフォーマットの本文の場合はapplication/soap+xml; charset=utf-8を選択してください。
コンテンツタイプ リクエストタイプ（HTTPメソッド） メモ application/json GET、POST、PUT、PATCH、DELETE application/x-www-form-urlencoded GET、POST、PUT、PATCH、DELETE application/soap+xml; charset=utf-8 GET、POST Multipart/form-data POST 複数の添付ファイルやテキストパーツの追加が可能です 単一ファイルのアップロード、コンテンツタイプは以下で設定 POST コンテンツタイプは任意です。指定されていない場合、システムは添付ファイルのコンテンツタイプを使用します。
- 本文
- このプロパティは、コンテンツタイプがapplication/jsonに設定されている場合に表示され、指定されたリクエストとともにJSONフォーマットで送信されるデータを指定します。シナリオ変数の置換が可能です。
- フォームパラメータ
- このプロパティは、コンテンツタイプがapplication/x-www-form-urlencodedに設定されている場合に表示され、指定されたリクエストとともに送信されるデータを、URLエンコードされたキー/値の文字列として指定するために使用されます。各パラメータを定義するには、「追加」をクリックし、パラメータ名を入力して、値を設定してください。シナリオ変数の置換が可能です。
- 認証
- 認証に使用するWebクライアント認証情報アカウントを選択してください。
- Webクライアント認証情報アカウントを選択した場合、その認証情報が認証に使用され、このブロック内の「ユーザー名」および「パスワード」フィールドは無視され、読み取り専用となります。
- 既定のオプションは「ブロックのプロパティにおけるユーザー名とパスワード」であり、これにより下位互換性が維持され、下の「ユーザー名」および「パスワード」フィールドに認証情報を直接入力することができます。
- ユーザー名
- リクエスト認証用のユーザー名です。変数の置換が可能です。
- パスワード
- リクエスト認証用のパスワードです。変数の置換が可能です。
- レスポンス本文のコンテンツは
- レスポンス本文の期待されるフォーマットです。「テキスト」、「XML」、「JSON」のオプションがあります。
- 結果のJSON内の初期パス
- レスポンス本文にJSONが含まれている場合、この設定を使用して、データの一部をシナリオ変数に保存できます。例：myobject.node.list[4]。パスは、返されたJSONのルートから始まります。
- JSONデータ用のシナリオ変数プレフィックス
- この文字列は、解析されたJSONデータを受け取る変数の名前として使用されます。なお、上記の初期パスが配列を指している場合、「GetNextブロックを使用してデータをループ処理する」オプションの値に応じて、この変数には配列全体、またはその最初のエレメント（およびそれ以降のエレメント）が格納されることにご注意ください。詳細は以下のレスポンスデータの処理を参照してください。
- 変数の抽出
- 「レスポンス本文のコンテンツは」の設定がXMLレスポンスを示している場合、この設定により、レスポンスからどの特定のデータをシナリオ変数に解析して格納するかを決定します。変数名が関連付けられたXPath式をいくつでも定義できます。
- 各XPath式はXMLレスポンスの解析に使用され、その結果は対応する変数に保存されます。式が複数の値、または子要素を持つノードを指している場合、「GetNextブロックを使用してデータをループ処理する」オプションの設定により、変数に値の配列が格納されるか、最初の値のみが格納されるかが決まります。詳細は以下のレスポンスデータの処理を参照してください。
- リクエストのタイムアウト
- このオプションは、外部WebサービスAPIの処理が予想以上に長くかかった場合のタイムアウトを設定するもので、設定された時間内にAPIの応答がない場合、システムが次のブロックに移動するようにします。このフィールドの範囲は2秒から100秒です。空白のままにすると、時間は100秒に設定されます。なお、このフィールドは、明示的な値が入力された場合にのみ表示されます。
- データのループ処理にGetNextブロックを使用
- JSONレスポンスデータ（初期パスにあるもの）が配列である場合は、このチェックボックスを選択してください。シナリオ変数は配列の最初のエレメントに設定され、Get Nextブロックを使用して配列のエレメントを順に処理し、シナリオ変数を次のエレメントに設定することができます。
|
|
「GetNext」が有効になっている場合、「URLの取得」ブロックの動作は、Bright Pattern Contact Center バージョン3.13以前と同じになります。 | |
レスポンスデータの取り扱い
レスポンスデータのサイズは、すべてのコンテンツタイプを通じて100 KBに制限されています。
レスポンスデータがJSONまたはXMLとしてエンコードされていない場合、以下のHTTPレスポンスコードで説明されているシナリオ変数$(integrationResultBody)を通じて、文字列としてアクセスできます。
JSONエンコードされたレスポンス
レスポンスデータがJSONの場合、以下の処理が行われます。
- データが解析されます。
- 「GetNextブロックを使用してデータをループ処理する」オプションが有効になっており、初期パスが指す項目が通常の（非連想）配列である場合：
- シナリオ変数は、配列の最初の項目に設定されます。
- Get Nextブロックを使用すると、変数を次以降の項目に初期化できます。
- それ以外の場合は、シナリオ変数には、初期パスが指している項目が設定されます。
初期パスの設定およびシナリオ変数に保存されたデータへのアクセスに使用できる構文は、以下の通りです。
- item.Subitem
- item[index]
- item[attr1=value].attr2
- 組み合わせ（例：item.subitem.array[index].value.array[attr=x].value）
XMLエンコードされたレスポンス
レスポンスデータがXMLフォーマットの場合（かつ「レスポンス本文のコンテンツは」がXMLであることを示している場合）、「変数の抽出」で定義された各XPath式が、レスポンスを解析し、関連する変数の値を次のように設定するために使用されます：
- XPathが特定の値を指している場合：その値が<variableName>に割り当てられます
- XPathが子要素を持つXMLノードを指している場合：
- ノードの各属性について、変数<variableName>.<attributeName>にその属性の値が割り当てられます
- 各子ノードについて、そのノードの値が<variableName>.<childNodeName>に割り当てられます。これは再帰的に適用されます。子ノードにさらに子ノードがある場合、その値は<variableName>.<childNodeName>.<childOfChild>に割り当てられ、以下同様に処理されます。
- 属性と子ノードの間で名前が重複する場合、子ノードの値が割り当てられ、属性の値は無視されます。
- XPathがレスポンスXML内のどの要素も指していない場合、対応する変数には空の文字列が割り当てられます。
- XPath式が配列を指している場合：
- 「GetNextブロックを使用してデータをループ処理する」が有効になっている場合、変数には最初に、XPath式で指定された配列の最初のエレメントが割り当てられます。Get Next Recordブロックを使用して、残りの値を順次処理できます。
- 「GetNextブロックを使用してデータをループ処理する」が無効になっている場合、変数には配列の全値が割り当てられます。この値は、シナリオ内の他の場所で
$(<variableName>[index])を使用して参照できます。
HTTPレスポンスコード
受信したHTTPレスポンスのステータスコードと本文は、それぞれローカル変数$(integrationResultCode)および$(integrationResultBody)に格納されます。トラブルシューティングの目的で、メールまたは内線メッセージブロックを使用して、失敗した試行を示すレスポンスのコンテンツを取得することができます。詳細については、変数$(integrationResultBody)の説明を参照してください。
下位互換性の理由により、受信したHTTPレスポンスのコードおよび本文は、ローカル変数$(fetchURLResultCode)および$(fetchURLResultBody)にも格納されます。
変数$(fetchURLResultCode)が取り得る値は以下の通りです：
- 0: 200 OKレスポンス（つまり、HTTPリクエストが成功したレスポンス）
- -1: 200 OKレスポンスですが、本文を変数として解析できません（JSONまたはXMLでエンコードされたレスポンス）
- -2: 200 OKレスポンスですが、本文の長さが50 KBを超えています
- -3: HTTPサーバーへの接続に失敗した、またはその他の接続エラーが発生しました
- -4: PUTまたはPOSTリクエストを使用する際、リクエスト本文のJSON構文が不正です
- その他: 400や500など、200以外の実際のHTTPレスポンスコード
注：500などのエラーコードで応答する場合、一部のサーバーは追加情報を提供しません。追加情報が提供された場合は、プレーン文字列としてシナリオに渡されます。この時点で、報告されたエラー（ある場合）について特定のWebサーバーを確認するか、正規表現を使用してレスポンス本文から詳細情報を抽出することができます。
HTTPリダイレクト応答の処理
「URLの取得」ブロックは、3xxハイパーテキスト転送プロトコル（HTTP）レスポンスコードを次のように処理します：
以下のコードを受信した場合、ブロックはGETリクエストメソッドを使用して、指定されたリダイレクトURLへリクエストを再試行します：
- 301 Moved Permanently（恒久的に移動）
- 302 Found（見つかりました）
- 303 See Other（HTTP/1.1以降）
以下のコードを受信した場合、ブロックは、当初指定されたリクエストメソッドを使用して、指定されたリダイレクトURLへのリクエストを再試行します：
- 307 Temporary Redirect（一時的なリダイレクト、HTTP/1.1以降）
- 308 Permanent Redirect（恒久的なリダイレクト、RFC 7538）
以下のステータスコードを受信した場合、条件付き終了「失敗」が選択されます：