URLの取得
「URLを取得」シナリオブロックは、指定されたメソッドを使用してURLからWebコンテンツを取得し、それをシナリオ変数に解析します。
|
HTTP、HTTPS 基本認証、Bearer トークン、および OAuth 2.0 クライアント認証情報がサポートされています。作成 Webクライアント認証情報 アカウントを作成し、URL取得ブロック間で再利用できるよう認証情報を保存します | |
条件付き終了
「URLの取得」ブロックでは、次の3つの条件付き終了のいずれかが実行されます：
- 失敗
：HTTPメソッドの実行中にエラーが発生した場合、またはHTTPレスポンス本文を解析できない場合、「失敗」の条件付き終了が実行されます。詳細については、 HTTP レスポンスコード 」を参照してください。
- データなし
- HTTPレスポンス本文にデータが返されない場合、「データなし」の条件付き終了が実行されます。
- タイムアウト
- 処理時間が「リクエストタイムアウト」フィールドに入力された値を超過した場合、「タイムアウト」の条件付き終了が実行されます。
設定
- タイトルテキスト
- フローチャートに表示される、このブロックのインスタンス名です。
- リクエストタイプ
- フェッチに使用される HTTP メソッドです。
-
|-
|-
|GET
|
- application/json
- application/x-www-form-urlencoded
- application/soap+xml; charset=utf-8
- application/json
- application/x-www-form-urlencoded
- application/soap+xml; charset=utf-8
- multipart/form-data
- <単一ファイルのアップロード；コンテンツタイプは以下で設定>
- application/json
- application/x-www-form-urlencoded
- application/json
- application/x-www-form-urlencoded
- application/json
- application/x-www-form-urlencoded
- このブロックがアクセスする Web リソースの HTTP/HTTPS URL です。 クエリ文字列パラメータがある場合は、URLパラメータで指定してください。パラメータが定義されている場合、それらはURLに追加されます。「?」および「&」の区切り文字は自動的に挿入されます。
- 追加ヘッダー
- リクエストに追加するHTTPヘッダーです。通常は認証の目的で使用されます。 関数は、値として挿入することで使用できます。「追加」をクリックしてヘッダーを定義し、名前と値を入力してください。
- 例えば、決済ゲートウェイには、「Authorization」ヘッダーと、時刻、ユーザー名、パスワードの SHA-256 ハッシュによる認証を必須とする RESTful インターフェースがある場合があります。 認証を有効にするには、名前を
Authorization、値をbearer $(accessid)のような形式でリクエストヘッダーに指定します。ここで、「accessid」には=hmac('SHA-256', '<KEY>', '<ユーザー>:<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、削除 | |- |application/x-www-form-urlencoded |GET、POST、PUT、PATCH、削除 | |- |application/soap+xml; charset=utf-8 |GET、POST | |- |Multipart/form-data |POST |複数の添付ファイルやテキストパーツの追加が可能です |- |単一のファイルのアップロード、コンテンツタイプは以下で設定されます |POST |コンテンツタイプは任意です。特定されていません。この場合、システムは添付ファイルのコンテンツタイプを使用します。 |}; 本文
- このプロパティは、コンテンツタイプがapplication/json に設定されている場合に表示され、指定されたリクエストとともに JSON フォーマットで送信されるデータを指定します。シナリオ変数の置換が可能です。
- フォームパラメータ
- このプロパティは、コンテンツタイプが `application/x-www-form-urlencoded` に設定されている場合に表示され、指定されたリクエストとともに送信されるデータを、URLエンコードされたキー/値の文字列として指定するために使用されます。各パラメータを定義するには、[追加] をクリックし、パラメータ名を入力して、値を設定してください。 シナリオ変数の置換が可能です。
- 認証
- 以下のいずれかを選択してください。 アカウントを選択してください。
- 「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 レスポンスデータ（初期パスにあるもの）が配列である場合は、このチェックボックスを選択してください。シナリオ変数は配列の最初のエレメントに設定され、 ブロックを使用して配列のエレメントを順に処理し、シナリオ変数を次のエレメントに設定することができます。
Webクライアント認証情報Get 次へコンテンツタイプ リクエストタイプ（HTTPメソッド） メモ 
「GetNext」が有効になっている場合、「Fetch URL」ブロックの動作は、Bright Pattern Contact Center バージョン 3.13 以前と同じになります。
レスポンスデータの取り扱い
レスポンスデータのサイズは、すべてのコンテンツタイプを通じて 100 KB に制限されています。
レスポンスデータが JSON または XML としてエンコードされていない場合、シナリオ変数 $(integrationResultBody) 経由でアクセスできます。 HTML [レスポンスコード で説明されているシナリオ変数 $(integrationResultBody) を通じて、文字列としてアクセスできます。
JSON エンコードされたレスポンス
応答データが JSON の場合、以下の処理が行われます。
- データが解析されます。
- [GetNext ブロックを使用してデータをループ処理する] オプションが有効になっており、初期パスが指す項目が通常の（非連想）配列である場合：
- シナリオ変数は、配列の最初の項目に設定されます。
- Get 次へ ブロックを使用すると、変数を次へおよびそれ以降の項目に初期化できます。
- それ以外の場合は、シナリオ変数には、初期パスが指している項目が設定されます。
初期パスの設定およびシナリオ変数に保存されたデータへのアクセスに使用できる構文は、以下の通りです。- item.Subitem
- item[index]
- 項目[attr1=値].attr2
- 組み合わせ（例：項目.subitem.array[index].値.array[attr=x].値）
XML エンコードされたレスポンス
応答データが XML フォーマットの場合（かつ「応答本文のコンテンツ」が XML であることを示している場合）、「変数の抽出」で定義された各 XPath 式が、応答を解析し、関連する変数の値を次のように設定するために使用されます：
- XPath が特定の値を指している場合：その値が <VARIABLENAME> に割り当てられます
- XPathが子要素を持つXMLノードを指している場合：
- ノードの各属性について、変数 <VARIABLENAME>.<ATTRIBUTENAME> にその属性の値が割り当てられます
- 各子ノードについて、そのノードの値が <VARIABLENAME>.<CHILDNODENAME> に割り当てられます これは再帰的に適用されます。子ノードにさらに子ノードがある場合、その値は <VARIABLENAME>.<CHILDNODENAME>.<CHILDOFCHILD> に割り当てられ、以下同様に処理されます。
- 属性と子ノードの間で名前が重複する場合、子ノードの値が割り当てられ、属性の値は無視されます。
- XPathがレスポンスXML内のどのエレメントも指していない場合、対応する変数には空の文字列が割り当てられます。
- XPath式が配列を指している場合：
- 「GetNextブロックを使用してデータをループ処理する」が有効になっている場合、変数には最初に、XPath式で指定された配列の最初のエレメントが割り当てられます。 「次へ」 ブロックを使用して、残りの値を順次処理できます。
- 「GetNextブロックを使用してデータをループ処理する」が無効になっている場合、変数には配列の全値が割り当てられます。この値は、シナリオ内の他の場所で
$(<変数名>[インデックス])を使用して参照できます。
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リダイレクト応答の処理
「Fetch URL」ブロックは、3xx ハイパーテキスト転送プロトコル（HTTP）レスポンスコードを次のように処理します：
以下のコードを受信した場合、ブロックは GET リクエストメソッドを使用して、指定されたリダイレクト URL へリクエストを再試行します：
- 301 永久移動
- 302 見つかりました
- 303 その他ページを参照（HTTP/1.1 以降）
以下のコードを受信した場合、ブロックは、当初指定されたリクエストメソッドを使用して、指定されたリダイレクト URL へのリクエストを再試行します：
- 307 一時的なリダイレクト（HTTP/1.1 以降）
- 308 恒久的なリダイレクト（RFC 7538）
以下のステータスコードを受信した場合、条件付き終了「失敗」が選択されます：