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

In Jira Service Management’s virtual service agent, conversation flows are made up of a series of steps. The send web request step type allows you to automatically send a request to a server, and get web pages or resources in return. Read about the other step types.

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

1. Go to the conversation flow you want to add a send web request step to. Find out how to build a conversation flow.

2. To see which fields and values are available for this send web request step, open the Fields and values available for this step expand at the bottom of the panel. Fields and values can be referenced in the Web request URL, Headers, and Body fields using curly braces, for example, {{field}}.

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

4. Select an HTTP method. The setting for this depends on the URL your web request is set up to use. Commonly used settings include:

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

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

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

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

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

6. Enter a Request timeout (in seconds). In the event of a timeout, the conversation will continue down the ELSE branch.

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

   • As an example, if you needed to get authorization, you could use Authorization in the Name field, and Bearer API_token_here in the Value field.

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

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

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

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

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

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

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

10. Enter a variable name in Response variable. The response body types currently supported are JSON and plain text.

    • This variable can be used in send message and send web request steps later in this conversation flow.

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

      • Status code: Use {{responseVariableName.status}} to access the HTTP status code, such as 200, 403, or 500.

      • Headers: Access specific headers using {{responseVariableName.headers.Header-Name}}.

      • Body: For JSON responses, use {{responseVariableName.body}} to access the JSON object. Navigate to specific properties using path notation, such as {{responseVariableName.body.propertyName}}. For plain text responses, use {{responseVariableName.body}} to access the entire response body as a string.

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

      • first: To retrieve the first element, use {{responseVariableName.body.arrayPropertyName.first}} if the array is a property, or {{responseVariableName.body.first}} if the entire response is an array.

      • last: To access the last element, use {{responseVariableName.body.arrayPropertyName.last}} for an array property, or {{responseVariableName.body.last}} if the response itself is an array.

      • indexed: For specific elements, use {{responseVariableName.body.arrayPropertyName.indexed.N}} if it's a property, or {{responseVariableName.body.indexed.N}} for the entire response, where N is the 0-based index.

      • size: To find out the number of elements, use {{responseVariableName.body.arrayPropertyName.size}} for a property, or {{responseVariableName.body.size}} if the array is the entire response.

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

    • 「それ以外の場合」の条件が 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 進値）が含まれている場合と一致します。

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

Let’s say you’re creating a conversation flow that allows customers to book a desk at their local office, and they respond to an ask for information step by saying that they work in the Sydney office.

You could set up a send web request step that sends a web request to a URL created for booking desks at your company’s offices around the world, and reference it using the syntax provided when you got the “Sydney” response in the ask for information step:

If the response from the web request matches one of your success conditions (for example, status ~ 2??), you could then have the virtual service agent inform the customer (using the send message step type) that their desk has been booked.

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

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

• Define a response variable: In the send web request step, define a response variable called bookingResponse to store the API response.

• Access specific data: After storing the response, you can use it to access specific pieces of information. For example, you could use bookingResponse.body.bookingId to extract the booking ID.

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

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

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

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

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

• Customize messages for the customer: In a subsequent send message step, you could reference the booking ID to provide a personalized message to the user. For example: "Your desk has been successfully booked at the Sydney office. Your booking ID is {{bookingResponse.body.bookingId}}."

• Handle different outcomes: By checking bookingResponse.status, you could adapt the conversation flow based on whether the booking was a success or not. For example, if the status is "failed", you could let the customer know and then provide other options (like escalation or another attempt to book).

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

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

  • You could use the X-Request-ID header in a subsequent web request for tracking purposes. For example, if you wanted to log or verify the transaction in another system, you could set up another send web request step that includes the X-Request-ID in its headers to allow your team to track these actions across different systems. Below is a request example for subsequent web request:

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