「ウェブリクエストの送信」ステップを作成してください

Jira Service Management の仮想サービスエージェントでは、 会話フローは一連のステップで構成されています。Web リクエストを送信するステップ タイプでは、サーバーに自動的にリクエストを送信し、Web ページやリソースを取得できます。その他のステップ タイプに関する詳細をご確認ください。

「ウェブリクエストの送信」ステップを作成

1. Web リクエストを送信するステップを追加する会話フローに移動します。会話フローの構築方法をご確認ください。

2. この Web リクエストを送信するステップで利用できるフィールドと値を確認するには、パネルの下部にある [このステップで利用できるフィールドと値] を開きます。"Web リクエスト URL"、"ヘッダー"、"本文" の各フィールドでは、中括弧を使ってフィールドと値を参照できます (例: {{field}})。

3. タイトルを入力します。

4. HTTP メソッドを選択します。この設定は、Web リクエストで使用するように設定されている URL によって異なります。一般的に使用される設定は次のとおりです。

   • GET: 通常はデータを取得するために使用されます

   • POST: 通常はデータを追加するために使用されます

   • PUT: 通常はデータを設定するために使用されます

   • DELETE: 通常はデータを削除するために使用されます

5. [Access method (アクセス方法)] を選択します。選択するアクセス方法に応じて、以下の指示に従ってください。

   • OAuth 2.0 – クライアント認証情報を承認に使用する方法を確認してください。

   • 認証にBasic authを使用する方法を確認してください。

「OAuth 2.0 - クライアント認証情報」を承認に使用する

[Access method (アクセス方法)] で [OAuth 2.0 - Client credentials (OAuth 2.0 - クライアント認証情報)] を選択した後、次の手順を実行します。

1. クライアント ID とクライアント シークレットを入力します。

2. 必要に応じて、Client credentials grant スコープを入力します。

3. OAuth トークン URL を入力してください。

4. 必要に応じて、対象者を入力します。

5. Header auth キーを入力してください。

   • これは、OAuth トークン URL を使用して取得したアクセス トークンを含むヘッダーのキーとして機能します。

6. 必要に応じて、Header auth 値のプレフィックスを入力します。

   • これは、OAuth トークン URL を使用して取得したトークンを含むヘッダー値のプレフィックスになります。例: Bearer {{token}}

7. 必要に応じて、1 つまたは複数のヘッダーを入力してください。

   • ヘッダーの値を「非表示」にするには、「非表示」チェックボックスを選択してください。保存すると、非表示のヘッダー値は実際の値ではなくドット（····）として表示されます。つまり、他の人と共有してはいけない API トークンや秘密鍵に使用できるということです。

8. レスポンス変数に変数名を入力します。現在サポートされているレスポンス本文タイプは JSON とプレーンテキストです。レスポンス変数の詳細をご確認ください。

   • この変数は、この会話フローのあとのメッセージを送信するステップと Web リクエストを送信するステップで使用できます。

9. 希望する条件を追加します。さらに条件を追加するには、+ 条件を追加を選択します。

10. 「それ以外の場合」の条件が 1 つ必要です。

    • 各条件に応じて、この会話フローに新しいブランチが作成されます。

    • 条件に使用できる変数は、ステータス (200、403、500 など)、本文 (回答で返される内容)、ヘッダー (回答で返されるヘッダー) です。

認証には「Basic auth」を使用します。

[Access method (アクセス方法)] で [Basic auth] を選択した後、次の手順を実行します。

1. HTTP メソッドを選択します。この設定は、Web リクエストで使用するように設定されている URL によって異なります。一般的に使用される設定は次のとおりです。

   • GET: 通常はデータを取得するために使用されます

   • POST: 通常はデータを追加するために使用されます

   • PUT: 通常はデータを設定するために使用されます

   • DELETE: 通常はデータを削除するために使用されます

2. ウェブリクエストの URL を入力します。

3. リクエスト タイムアウト (秒) を入力します。タイムアウトが発生すると、会話は「それ以外の場合」ブランチに続きます。

4. 必要に応じて、1 つまたは複数のヘッダーを入力してください。

   • 例として、承認を受ける必要がある場合は、"名前" フィールドに Authorization を、"値" フィールドに Bearer API_token_here を使用できます。

   • ヘッダーの値を「非表示」にするには、「非表示」チェックボックスを選択してください。保存すると、非表示のヘッダー値は実際の値ではなくドット（····）として表示されます。つまり、他の人と共有してはいけない API トークンや秘密鍵に使用できるということです。

5. 本文のコンテンツ タイプを選択します。

   • text/plainは、本文フィールドにプレーンテキストが含まれていることを意味します（特別なマークアップ/テキスト形式はない）。

   • application/json は、本文フィールドに JSON が含まれていることを意味します。

   • application/xml は、本文フィールドに XML が含まれていることを意味します。

6. 必要に応じて、本文を入力してください。

   • このフィールドのデータは、ユースケースに該当する場合、ウェブリクエストの本文として送信されます。

7. レスポンス変数に変数名を入力します。現在サポートされているレスポンス本文タイプは JSON とプレーンテキストです。レスポンス変数の詳細をご確認ください。

   • この変数は、この会話フローのあとのメッセージを送信するステップと Web リクエストを送信するステップで使用できます。

8. 希望する条件を追加します。さらに条件を追加するには、+ 条件を追加を選択します。

   • 「それ以外の場合」の条件が 1 つ必要です。

   • 各条件に応じて、この会話フローに新しいブランチが作成されます。

   • 条件に使用できる変数は、ステータス (200、403、500 など)、本文 (回答で返される内容)、ヘッダー (回答で返されるヘッダー) です。

条件の例

条件の構文を理解するために、いくつかの例を作成しました。

• status == 200 はステータス 200 の応答と一致しますが、他のステータスは一致しません。

• status ~ 2?? は、2 で始まるすべてのステータス（200、201 など。300、400 などは除く）の応答と一致します。

• not status ~ 2?? は、ステータスが 200 から 299 の間にない場合は応答と一致します。

• body ~ "success" は、応答本文に "success" という文字列を含む応答と一致します

• status == 200 and body ~ "success" は、ステータス 200 の応答と "success" という文字列を含む本文と一致します

• headers.Content-Type == "application/json" は、応答を application/json に設定されたコンテンツタイプのヘッダーと一致します

• not (status != 200 and body ~ "*ERROR*") は、ステータスが 200 の場合、または本文に「ERROR」が含まれていない場合に一致します

• body ~ /^$/ は本文が空白の場合に一致します

• body ~ /^[A-Za-z]+$/ は、本文にアルファベットのみが含まれている場合に一致します。

• not body ~ /"remaining": 0/は、本文に“remaining”: 0” という文字列が含まれていない場合に一致します

注：本文とヘッダーでは正規表現はサポートされされていますが、ステータスには対応していません。したがって、これは無効です:status ~ /4[0-9]{2}/

JSON と不等式

仮想サービスエージェントは、条件内の不等式や JSON をサポートしていないことに注意してください。

たとえば、次のような応答本文があったとします。{ "remaining": 2 }

つまり、次の条件は無効です。body.remaining > 0

JSON で適切な値を見つけるには、正規表現を使用することをお勧めします。有効な条件（上記の条件と同じ）は、次のようになります。body ~ /^"remaining": ([0-9]+(?:[\.][0-9]*)?|\.[0-9]+)$/

これは、本文に "remaining": $ という文字列（$ はゼロ以外の正の整数または 10 進値）が含まれている場合と一致します。

レスポンス変数の例

レスポンス変数を使用してウェブリクエストのレスポンスをキャプチャすると、次のコンポーネントに直接アクセスできます。

• ステータス コード: {{responseVariableName.status}} を使用して、200、403、500 などの HTTP ステータス コードにアクセスします。

• ヘッダー: {{responseVariableName.headers.Header-Name}} を使用して特定のヘッダーにアクセスします。

• 本文: JSON レスポンスの場合は、{{responseVariableName.body}} を使用して JSON オブジェクトにアクセスします。{{responseVariableName.body.propertyName}} などのパス表記を使用して、特定のプロパティに移動できます。プレーン テキストのレスポンスでは、{{responseVariableName.body}} を使用してレスポンス本文全体に文字列としてアクセスします。

応答の本文にリストが含まれているか、JSON 配列としてフォーマットされている場合は、次のアクセサー プロパティを使用して個々の要素にアクセスできます。

• first: 最初の要素を取得するには、配列がプロパティの場合は {{responseVariableName.body.arrayPropertyName.first}}、レスポンス全体が配列の場合は {{responseVariableName.body.first}} を使用します。

  • last: 最後の要素にアクセスするには、配列プロパティには {{responseVariableName.body.arrayPropertyName.last}}、レスポンス自体が配列の場合は {{responseVariableName.body.last}} を使用します。

  • indexed: 特定の要素については、それがプロパティの場合は {{responseVariableName.body.arrayPropertyName.indexed.N}}、レスポンス全体の場合は {{responseVariableName.body.indexed.N}} を使用します。ここで、N は 0 ベースのインデックスです。

  • size: 要素の数を確認するには、プロパティの場合は {{responseVariableName.body.arrayPropertyName.size}}、配列がレスポンス全体である場合は {{responseVariableName.body.size}} を使用します。

レスポンス変数を使用して会話のフローを改善してください

たとえば、カスタマーが地元のオフィスでデスクを予約できるような会話フローを作成していて、情報を求めるステップに対して、シドニーのオフィスで作業していると回答があったとします。

その会社の世界中にあるオフィスのデスク予約用に作成された URL に Web リクエストを送信するステップを設定し、情報を求めるステップで、「シドニー」という応答を受け取ったときに提供された構文を使用して次のようにそれを参照できます。

Web リクエストからの応答が成功条件の 1 つ (status ~ 2?? など) と一致する場合、 仮想サービス エージェントに、デスクが予約されたことを (メッセージを送信するステップ タイプを使用して) 通知させることができます。

デスクを予約するための API が、予約が成功すると、次の構造の JSON 応答を返すとします

この場合、レスポンス変数を使用して次のことができます。

• レスポンス変数を定義する: Web リクエストを送信するステップで、API レスポンスを保存する bookingResponse というレスポンス変数を定義します。

• 特定のデータへのアクセス: 回答を保存すると、それを使用して特定の情報にアクセスできます。たとえば、bookingResponse.body.bookingId を使用して予約 ID を抽出できます。

  • リスト要素へのアクセス: 応答に使用可能なデスクのリストが含まれている場合、特定のデスクにアクセスするか、順に処理することができます。

    • {{bookingResponse.body.availableDesks.first}} を使用すると、使用可能な最初のデスク (つまり、"Desk 2") を取得できます。

    • 使用可能なすべてのデスクについてカスタマーに知らせる必要がある場合は、簡単なテンプレート構文を使用してリストを順に処理することで、各デスクを表示できます。

      {{#bookingResponse.body.availableDesks}} - {{.}} {{/bookingResponse.body.availableDesks}}

      これは、各デスクを順に処理して、リスト形式で出力します。

• 顧客へのメッセージをカスタマイズする: 次のメッセージ送信ステップでは、予約 ID を参照して、ユーザーにパーソナライズされたメッセージを提供することができます。例:「あなたのデスクはシドニーのオフィスで正常に予約されました。予約 ID は {{bookingResponse.body.bookingID}} です。」

• さまざまな結果への対応: bookingResponse.status をチェックすることで、予約が成功したかどうかに応じて会話フローを調整できます。たとえば、ステータスが「失敗」の場合は、カスタマーに伝えてから、その他のオプション (エスカレーションや再度予約を試すなど) を提供できます。

• レスポンスヘッダーを利用する：レスポンスに次のヘッダーが含まれているとします。

  • X-RateLimit-Remaining: 150 X-Request-ID: abc123

  • X-Request-ID ヘッダーは、後続の Web リクエストで追跡に使用できます。たとえば、トランザクションを別のシステムに記録または検証する場合は、ヘッダーに X-Request-ID を含む別の Web リクエストを送信するステップを設定して、チームがこれらのアクションをさまざまなシステムで追跡できるようにします。以下は、後続の Web リクエストのリクエスト例です。

    { "action": "logTransaction", "requestId": "{{bookingResponse.headers.X-Request-ID}}" }