「ウェブリクエストの送信」ステップを作成してください
この記事では、現在展開している機能について説明します。これらの機能がサイト上で公開される時期は、リリース ノートまたはアトラシアン コミュニティでご確認ください。
Jira Service Management の仮想サービス エージェントでは、 会話フローは一連のステップで構成されています。Web リクエストを送信するステップ タイプでは、サーバーに自動的にリクエストを送信し、Web ページやリソースを取得できます。その他のステップ タイプに関する詳細をご確認ください。
「ウェブリクエストの送信」ステップを作成
Web リクエストを送信するステップで使用されるコンテンツは、カスタマーに表示される場合があります。
Web リクエストを送信するステップを構成することで、接続してプルするコンテンツに対して権限を有していることを表します。
Web リクエストを送信するステップを追加する会話フローに移動します。会話フローの構築方法をご確認ください。
この Web リクエストを送信するステップで利用できるフィールドと値を確認するには、パネルの下部にある [このステップで利用できるフィールドと値] を開きます。"Web リクエスト URL"、"ヘッダー"、"本文" の各フィールドでは、中括弧を使ってフィールドと値を参照できます (例:
{{field}})。タイトルを入力します。
HTTP メソッドを選択します。この設定は、Web リクエストで使用するように設定されている URL によって異なります。一般的に使用される設定は次のとおりです。
GET: 通常はデータを取得するために使用されます
POST: 通常はデータを追加するために使用されます
PUT: 通常はデータを設定するために使用されます
DELETE: 通常はデータを削除するために使用されます
Select an Access method. Follow the instructions below depending on the access method you select.
Use 'OAuth 2.0 - Client credentials' for authorization
After selecting OAuth 2.0 - Client credentials under Access method:
Enter a Client ID and Client secret.
If desired, enter a Client credentials grant scope.
Enter an OAuth token URL.
If desired, enter an Audience.
Enter a Header auth key.
This will act as the key for the header containing the access token fetched using the OAuth token URL.
If desired, enter a Header auth value prefix.
This will be the prefix for the header value containing the token fetched using the OAuth token URL, for example
Bearer {{token}}
必要に応じて、1 つまたは複数のヘッダーを入力してください。
ヘッダーの値を「非表示」にするには、「非表示」チェックボックスを選択してください。保存すると、非表示のヘッダー値は実際の値ではなくドット（····）として表示されます。つまり、他の人と共有してはいけない API トークンや秘密鍵に使用できるということです。
Enter a variable name in Response variable. The response body types currently supported are JSON and plain text. Read more about response variables.
この変数は、この会話フローのあとのメッセージを送信するステップと Web リクエストを送信するステップで使用できます。
希望する条件を追加します。さらに条件を追加するには、+ 条件を追加を選択します。
「それ以外の場合」の条件が 1 つ必要です。
各条件に応じて、この会話フローに新しいブランチが作成されます。
条件に使用できる変数は、ステータス (200、403、500 など)、本文 (回答で返される内容)、ヘッダー (回答で返されるヘッダー) です。
Use 'Basic auth' for authentication
After selecting Basic auth under Access method:
HTTP メソッドを選択します。この設定は、Web リクエストで使用するように設定されている URL によって異なります。一般的に使用される設定は次のとおりです。
GET: 通常はデータを取得するために使用されます
POST: 通常はデータを追加するために使用されます
PUT: 通常はデータを設定するために使用されます
DELETE: 通常はデータを削除するために使用されます
ウェブリクエストの URL を入力します。
リクエスト タイムアウト (秒) を入力します。タイムアウトが発生すると、会話は「それ以外の場合」ブランチに続きます。
必要に応じて、1 つまたは複数のヘッダーを入力してください。
例として、承認を受ける必要がある場合は、"名前" フィールドに
Authorizationを、"値" フィールドにBearer API_token_hereを使用できます。ヘッダーの値を「非表示」にするには、「非表示」チェックボックスを選択してください。保存すると、非表示のヘッダー値は実際の値ではなくドット（····）として表示されます。つまり、他の人と共有してはいけない API トークンや秘密鍵に使用できるということです。
本文のコンテンツ タイプを選択します。
text/plainは、本文フィールドにプレーンテキストが含まれていることを意味します（特別なマークアップ/テキスト形式はない）。
application/json は、本文フィールドに JSON が含まれていることを意味します。
application/xml は、本文フィールドに XML が含まれていることを意味します。
必要に応じて、本文を入力してください。
このフィールドのデータは、ユースケースに該当する場合、ウェブリクエストの本文として送信されます。
Enter a variable name in Response variable. The response body types currently supported are JSON and plain text. Read more about response variables.
この変数は、この会話フローのあとのメッセージを送信するステップと Web リクエストを送信するステップで使用できます。
希望する条件を追加します。さらに条件を追加するには、+ 条件を追加を選択します。
「それ以外の場合」の条件が 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 進値）が含まれている場合と一致します。
Example response variables
When you use a response variable to capture a web request's response, you could directly access the following components:
ステータス コード:
{{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 リクエストを送信するステップを設定し、情報を求めるステップで、「シドニー」という応答を受け取ったときに提供された構文を使用して次のようにそれを参照できます。
{
"office": "{{customfield_10081.id}}",
"reporter": "{{reporter.emailAddress}}"
}Web リクエストからの応答が成功条件の 1 つ (status ~ 2?? など) と一致する場合、 仮想サービス エージェントに、デスクが予約されたことを (メッセージを送信するステップ タイプを使用して) 通知させることができます。
デスクを予約するための API が、予約が成功すると、次の構造の JSON 応答を返すとします
{
"status": "success",
"bookingId": "12345",
"message": "Desk booked successfully at the Sydney office."
}この場合、レスポンス変数を使用して次のことができます。
レスポンス変数を定義する: 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: abc123X-Request-IDヘッダーは、後続の Web リクエストで追跡に使用できます。たとえば、トランザクションを別のシステムに記録または検証する場合は、ヘッダーにX-Request-IDを含む別の Web リクエストを送信するステップを設定して、チームがこれらのアクションをさまざまなシステムで追跡できるようにします。以下は、後続の Web リクエストのリクエスト例です。{ "action": "logTransaction", "requestId": "{{bookingResponse.headers.X-Request-ID}}" }
この内容はお役に立ちましたか?