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

この記事では、現在展開している機能について説明します。これらの機能がサイト上で公開される時期は、リリースノートまたは Atlassian コミュニティでご確認ください。

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

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

Web リクエストを送信するステップで使用されるコンテンツは、カスタマーに表示される場合があります。

Web リクエストを送信するステップを設定することで、接続して引用するコンテンツに対して権限を有していることを表します。

ウェブリクエストの送信ステップを追加する会話フローに移動します。会話フローの構築方法をご確認ください。
このウェブリクエストの送信ステップで利用できるフィールドと値を確認するには、パネルの下部にある [このステップで利用できるフィールドと値] を開いてください。ウェブリクエスト URL、ヘッダー、本文フィールドでは、中括弧を使ってフィールドと値を参照できます（例：{{field}}）。
タイトルを入力します。
HTTP メソッドを選択します。この設定は、ウェブリクエストで使用するように設定されている URL によって異なります。一般的に使用される設定は次のとおりです。
- GET: 通常はデータを取得するために使用されます
- POST: 通常はデータを追加するために使用されます
- PUT: 通常はデータを設定するために使用されます
- DELETE: 通常はデータを削除するために使用されます
ウェブリクエストの URL を入力します。
リクエストのタイムアウト（秒単位）を入力します。タイムアウトが発生すると、会話は「それ以外の場合」ブランチに続きます。
必要に応じて、1 つまたは複数のヘッダーを入力してください。
- 例として、承認を受ける必要がある場合は、名前フィールドに Authorization を、値フィールドに Bearer API_token_here を使用できます。
- ヘッダーの値を「非表示」にするには、「非表示」チェックボックスを選択してください。保存すると、非表示のヘッダー値は実際の値ではなくドット（····）として表示されます。つまり、他の人と共有してはいけない API トークンや秘密鍵に使用できるということです。
本文のコンテンツタイプを選択します。
- text/plainは、本文フィールドにプレーンテキストが含まれていることを意味します（特別なマークアップ/テキスト形式はない）。
- application/json は、本文フィールドに JSON が含まれていることを意味します。
- application/xml は、本文フィールドに XML が含まれていることを意味します。
必要に応じて、本文を入力してください。
- このフィールドのデータは、ユースケースに該当する場合、ウェブリクエストの本文として送信されます。
レスポンス変数に変数名を入力します。現在サポートされているレスポンス本文タイプは JSON とプレーンテキストです。
- この変数は、この会話フローの後のメッセージ送信とウェブリクエストの送信ステップで使用できます。
- レスポンス変数を使用してウェブリクエストのレスポンスをキャプチャすると、次のコンポーネントに直接アクセスできます。
  - ステータスコード:{{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}} を使用します。
希望する条件を追加します。さらに条件を追加するには、+ 条件を追加を選択します。
- 「それ以外の場合」の条件が 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 進値）が含まれている場合と一致します。

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

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

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

{
  "office": "{{customfield_10081.id}}",
  "reporter": "{{reporter.emailAddress}}"
}

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

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

{
  "status": "success",
  "bookingId": "12345",
  "message": "Desk booked successfully at the Sydney office."
}

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

レスポンス変数を定義する:bookingResponse ウェブリクエストの送信ステップ、API レスポンスを保存するというレスポンス変数を定義します。
特定のデータへのアクセス：回答を保存すると、それを使用して特定の情報にアクセスできます。たとえば、bookingResponse.body.bookingId を使って予約 ID を抽出できます。
- リスト要素へのアクセス: 応答に使用可能なデスクのリストが含まれている場合、特定のデスクにアクセスするか、順に処理することができます。
  - {{bookingResponse.body.availableDesks.first}} を使用すると、使用可能な最初のデスク (つまり、"Desk 2") を取得できます。
  - 使用可能なすべてのデスクについてカスタマーに知らせる必要がある場合は、簡単なテンプレート構文を使用してリストを順に処理することで、各デスクを表示できます。
    1 2 3{{#bookingResponse.body.availableDesks}} - {{.}} {{/bookingResponse.body.availableDesks}}
    これは、各デスクを順に処理して、リスト形式で出力します。
へのメッセージをカスタマイズする ：次のメッセージ送信ステップでは、予約 ID を参照して、ユーザーにパーソナライズされたメッセージを提供することができます。例:" あなたのデスクはシドニーのオフィスで正常に予約されました。予約 ID は {{bookingResponse.body.bookingID}} です。"
さまざまな結果への対応:bookingResponse.status をチェックすることで、予約が成功したかどうかに応じて会話フローを調整できます。たとえば、ステータスが " failed " の場合は、カスタマーに伝えてから、他のオプション（エスカレーションや再度予約を試すなど）を提供できます。
レスポンスヘッダーを利用する：レスポンスに次のヘッダーが含まれているとします。
- 1 2X-RateLimit-Remaining: 150 X-Request-ID: abc123
- X-Request-ID ヘッダーは、後続のウェブリクエストで追跡に使用できます。たとえば、トランザクションを別のシステムに記録または検証する場合は、ヘッダーに X-Request-IDを含む別のウェブリクエストの送信ステップを設定して、チームがこれらのアクションをさまざまなシステムで追跡できるようにすることができます。以下は、後続のウェブリクエストのリクエストの例です。
  1 2 3 4{ "action": "logTransaction", "requestId": "{{bookingResponse.headers.X-Request-ID}}" }

この内容はお役に立ちましたか?

正確ではなかった

明確ではなかった

関係なかった

さらにヘルプが必要ですか?

アトラシアンコミュニティをご利用ください。

コミュニティに質問