現在のプランを確認
Suite、すべてのバージョン Team、Growth、Professional、EnterpriseまたはEnterprise Plus
Support Team、ProfessionalまたはEnterprise
この記事で説明する機能は、2026年5月11日から6月12日にかけて、すべてのSuiteプランおよびSupportプランを対象に順次利用可能になります。そのため、お客様のアカウントではこの機能がまだ表示されない場合があります。詳しくは、こちらの製品関連の告知をご覧ください。

インテグレーションビルダーでは、リクエストパラメータを使用して、AIエージェントとの会話からデータ（会話パラメータ）を取得し、外部エンドポイントに渡すことができます。場合によっては、このデータをAPIリクエストのURLクエリやリクエスト本文として送信する前に、変換や再フォーマットを行う必要があるかもしれません。これを行うには、強力なクエリおよび変換言語であるJSONataを利用できます。

この記事では、次のトピックについて説明します。

  • リクエストパラメータの値を再フォーマットする
  • 値の再フォーマットに関する一般的なユースケースの例

関連記事

  • インテグレーションビルダー関連のリソース

リクエストパラメータの値を再フォーマットする

JSONataを使用してリクエストパラメータの値を再フォーマットできます。

リクエストパラメータの値を再フォーマットするには

  1. AIエージェントワークスペースの画面右上の「AIエージェント」ドロップダウンフィールドで、AIエージェントを選択します。
  2. 左側のメインメニューで、「APIインテグレーション」をクリックします。
  3. インテグレーションを選択するか、作成します。
  4. 「リクエストパラメータ」ページで、値を再フォーマットするリクエストパラメータを選択するか、作成します。
  5. 「テスト値」フィールドで、値の再フォーマットアイコン（）を選択します。
  6. 「値の再フォーマット」ダイアログの「JSONataの再フォーマット」フィールドで、JSONataを使用して、選択したリクエストパラメータキーに関連付けられた値を変換または再フォーマットします。
    JSONataクエリでは、値を再フォーマットするキーとして'$'を使用してください。
    「テスト値のプレビュー」フィールドで、クエリの結果をリアルタイムで確認できます。
  7. 「完了」をクリックします。
  8. （オプション）APIリクエストの本文にリクエストパラメータを追加する場合：
    1. 左側の「環境」ヘッダーで、適切な環境を選択します。
    2. 「本文」タブを選択します。
    3. JSONオブジェクトを追加し、リクエストパラメータを値として二重中括弧で囲んで指定します。

値の再フォーマットに関する一般的なユースケースの例

インテグレーションビルダー内でリクエストパラメータを定義する際は、リクエストパラメータを特定のキーに割り当てます。これらの値はそのままでも機能する場合がありますが、外部システムの要件に合わせるために変換や再フォーマットが必要になるシナリオもあります。

たとえば、以下のような操作ができるようになります。

  • 日付形式を変更する：APIの要件に合わせて、日付の形式を「MM/DD/YYYY」から「YYYY-MM-DD」またはISO 8601の形式に変更します。
  • 文字列操作を行う：文字の追加や削除、複数のフィールドの結合、HTMLを含む文字列への変換などの文字列操作を行います。
  • 条件ロジックを適用する：フィールドが空かどうかを確認したり、必要に応じてデフォルト値を割り当てたりするなどの条件を適用します。

ここでは、次の例について説明します。

  • シナリオ：日付形式を変更する
  • シナリオ：URLの形式を変更してリンクをクリック可能にする
  • シナリオ：チャットの会話ログの形式を変更してログを読みやすくする

シナリオ：日付形式を変更する

このシナリオでは、エンドポイントで扱う日付は「YYYY-MM-DD」形式またはISO 8601形式である必要があります。ただし、会話内では、よりユーザーフレンドリーな「DD/MM/YYYY」形式で日付を表示したいとします。

このシナリオでは、以下のようなJSONataクエリを使用します。

$substring($, 6, 10) & "-" & $substring($, 3, 2) & "-" & $substring($, 0, 2)

シナリオ：URLの形式を変更してリンクをクリック可能にする

このシナリオでは、URLの先頭に「http://」または「https://」があり、その後に空白以外の文字がいくつか続くテキスト（部分文字列）を検索し、URLをクリック可能なリンクに変換します。その後、JSONataの$replace関数を使用して、その部分文字列を、一致したURLをHTMLの<a>タグで囲んだ文字列に置換し、クリック可能なリンクを作成します。

このシナリオでは、以下のようなJSONataクエリを使用します。

(
$text := "Chat transcript unavailable. Here is a link:https://www.zendesk.com. Here is another link: https://www.w3schools.com.";

$replace($text, /(https?:\/\/[^\s]+)/, '<a href="$1">$1</a>'
)

シナリオ：チャットの会話ログの形式を変更してログを読みやすくする

このシナリオでは、チケットにチャットの会話ログを追加したいと考えています。しかし、デフォルトの設定では、チャットの会話ログはあまり読みやすいものではありません。

  • チャットの会話ログ - 2024-10-12 (13:04:10) AIエージェント：インテグレーションAIエージェントへようこそ！(13:04:10) AIエージェント：テストするインテグレーションを選択してください：(13:04:10) 訪問者：test c.id: d501304d-da09-4485-a4c7-1c708ec0005d 時間はすべてUTCです

各メッセージを改行して、よりユーザーが読みやすいレイアウトに変換したいと考えています。各メッセージは開括弧 ( ( ) で始まるため、JSONata を使用して、( の出現箇所をすべて改行と続く (. に置き換えることができます。

形式を変更した会話は、次のようになります：

  • チャットの会話ログ - 2024-10-12
    (13:04:10) AIエージェント：インテグレーションAIエージェントへようこそ！
    (13:04:10) AIエージェント：テストするインテグレーションを選択してください：
    (13:04:10) 訪問者：test c.id: d501304d-da09-4485-a4c7-1c708ec0005d 時間はすべてUTCです

このシナリオでは、以下のようなJSONataクエリを使用します。

$replace($, “(“, “\n(“)

さらに、環境設定の本文セクションに以下のパラメータを追加して、リクエストと共に送信されるようにする必要があります。

{
"chatTranscript": "{{chatTranscript}}"
}

 

Powered by Zendesk