パラメータ

パラメータは、セッション中にエンドユーザーが指定した値を取得して参照するために使用されます。各パラメータには名前とエンティティ タイプがあります。未加工のエンドユーザー入力とは異なり、パラメータは、ロジックの実行やレスポンスの生成に簡単に使用できる構造化データです。

CX パラメータは、ES パラメータと似ていますが、ユーティリティとスコープが拡張され、パラメータを参照する構文が異なります。

パラメータの定義、参照、設定、取得

パラメータを使用する一般的な方法は 4 つあります。

  • 設計時の定義: 設計時に、コンソールまたは API を使用してパラメータを定義します。たとえば、インテント パラメータを定義してトレーニング フレーズで使用し、抽出するエンドユーザー入力を指定できます。
  • 設計時の参照: パラメータ参照は、実行時に抽出されるパラメータ値を保持する変数です。設計時には、コンソールまたは API を使用してさまざまなデータ型のパラメータを参照できます。たとえば、ルートの静的フルフィルメント レスポンスでセッション パラメータを参照できます。
  • 実行時の設定: パラメータ値を、Dialogflow サービス、API を呼び出すサービス、Webhook サービスのすべてでランタイムに設定できます。たとえば、Dialogflow サービスは、エンドユーザー入力がインテントと一致し、入力にパラメータ データが含まれている場合に、インテント パラメータの値を設定します。
  • 実行時に取得: 実行時に、パラメータ参照には設定されたパラメータ値が含まれます。このパラメータ値は、API または Webhook を使用して取得できます。たとえば、インテントが一致し、Webhook が呼び出されると、Webhook サービスはインテントのパラメータ値を受け取ります。

インテント パラメータ

インテントは、パラメータを使用して、インテントが一致したときにエンドユーザーから提供されたデータを抽出します。インテント パラメータを定義するには、次のデータを使用します。

  • NameID または Display Name とも呼ばれます): パラメータを識別する名前。
  • Entity Type: パラメータに関連付けられたエンティティ タイプ
  • Is List: true の場合、パラメータは値のリストとして扱われます。

インテント パラメータを定義する

インテント パラメータは、インテント データを作成する、またはトレーニング フレーズにアノテーションを付ける場合に、設計時に定義されます。

参照インテント パラメータ

インテント パラメータ参照は、インテント ルートの静的フルフィルメント レスポンス メッセージで使用できます。

実行時にテキストが特定のエンティティに一致すると、処理に便利な値に変換されることがよくあります。たとえば、エンドユーザーの入力に含まれる単語「apples」は、果物のエンティティについては「apple」として抽出されることがあります。エンドユーザーが書いた(または話した)original 値、あるいはエンティティによって抽出された resolved 値を参照できます。

現在一致しているインテントのパラメータを参照するには、次のいずれかの形式を使用します。

$intent.params.parameter-id.original
$intent.params.parameter-id.resolved

たとえば、パラメータ ID が date の場合は、解決された値を $intent.params.date.resolved として参照できます。

また、次のパラメータのエンティティ タイプ名にアクセスすることもできます。

$intent.params.parameter-id.type

インテント パラメータを設定する

エンドユーザー入力が実行時にインテントと一致すると、関連付けられたトレーニング フレーズのアノテーションによって使用されるパラメータが Dialogflow によって設定されます。

インテント ルートのフルフィルメントでは、フルフィルメント パラメータ プリセットを使用して、実行時にインテント パラメータ値を設定できます。

インテント パラメータを取得する

インテントが一致する会話のターンでは、コードでインテント パラメータ値にアクセスできます。

API を操作すると、インテント パラメータ値が返されます。detectIntent メソッドの queryResult.parameters レスポンス フィールドについては、をご覧ください。

セッション リファレンスのプロトコルとバージョンを選択:

プロトコル V3beta1
REST セッション リソース
RPC セッション インターフェース

Webhook の受信インテント パラメータの値。Webhook リクエストintentInfo.parameters フィールドをご覧ください。

フォーム パラメータ

ページごとにフォームを定義できます。これは、ページのエンドユーザーから収集する必要があるパラメータのリストです。エージェントは、必要なすべてのフォーム パラメータ(ページ パラメータとも呼ばれます)を収集するまで、複数の会話ターンでエンドユーザーとやり取りします。フォーム パラメータごとに、エージェントがエンドユーザーからの情報をリクエストするために使用するプロンプトも表示します。このプロセスをフォーム入力と呼びます。

たとえば、Collect Customer Info ページのエンドユーザーの名前と電話番号を収集するフォームを作成できます。

CX フォームの入力は、ES スロットの入力に似ています。

フォーム パラメータを定義するには、次のデータを使用します。

  • NameID または Display Name とも呼ばれます): パラメータを識別する名前。
  • Entity Type: パラメータに関連付けられたエンティティ タイプ
  • Is List: true の場合、パラメータは値のリストとして扱われます。
  • Required: パラメータが必須かどうかを示します。オプションのパラメータはプロンプトをトリガーしません。ただし、ユーザーが指定した場合には入力されます。フォーム入力が完了する前に、必須パラメータを入力する必要があります。
  • Default Value:オプション パラメータのデフォルト値。パラメータが必須の場合、デフォルト値は無視されます。
  • Initial Prompt Fulfillment: エージェントが最初にエンドユーザーにパラメータの入力を促す必要があるときに使用されるフルフィルメントで構成されます。
  • Reprompt Handlers: 一度失敗した後にエージェントがエンドユーザーに再びパラメータの入力を促す必要がある場合に使用します。フォーム入力のリプロンプト ハンドラをご覧ください。

フォーム パラメータを定義する

フォーム パラメータは、ページを作成する場合に設計時に定義されます。

参照フォーム パラメータ

フォーム パラメータのリファレンスは直接使用されません。個々のフォーム パラメータまたはフォーム全体の入力ステータスのみを確認できます。フォーム ステータスのリファレンスは、条件ルート条件要件で使用できます。

現在のページのすべてのフォームが入力されているかどうかを確認するには、次の条件を使用します。

$page.params.status = "FINAL"

最後のターンで特定のフォーム パラメータが入力されたかどうかを確認するには、次の条件を使用します。

$page.params.parameter-id.status = "UPDATED"

フォーム パラメータを設定する

ルート、イベント ハンドラ、フォーム リプロンプトのフルフィルメントでは、フルフィルメント パラメータ プリセットを使用して、実行時にフォーム パラメータ値を設定できます。

Webhook では、実行時にフォーム パラメータの値を設定できます。Webhook レスポンスpageInfo.formInfo.parameterInfo フィールドをご覧ください。

フォーム パラメータを取得する

API を操作すると、フォーム パラメータの値が返されます。detectIntent メソッドの queryResult.parameters レスポンス フィールドについては、をご覧ください。

セッション リファレンスのプロトコルとバージョンを選択:

プロトコル V3beta1
REST セッション リソース
RPC セッション インターフェース

Webhook の受信フォーム パラメータの値。Webhook リクエストpageInfo.formInfo.parameterInfo フィールドをご覧ください。

フォーム入力のリプロンプト ハンドラ

フォームの入力中に、エージェントは、エンドユーザーにパラメータ値を指定するよう求めます。エンドユーザーが予期しない入力で応答すると、sys.no-match-* イベントまたは sys.no-input-* イベントが呼び出されます。リプロンプト ハンドラ(パラメータ レベル イベント ハンドラとも呼ばれます)を定義して、エンドユーザーにパラメータ値の再入力を求めることができます。

他のイベント ハンドラと同様に、リプロンプト ハンドラは次のいずれかまたは両方で構成できるタイプのステート ハンドラです。

  • エンドユーザーのリプロンプト メッセージやパラメータ プリセットを指定するためのフルフィルメント。
  • 現在のページを変更するための遷移ターゲット。

セッション パラメータ

実行時に任意のタイプのパラメータが設定されると、パラメータがセッションに書き込まれ、セッション パラメータになります。これらのパラメータは、設計時には明示的に定義されません。これらのセッション パラメータを、セッション中の任意の時点で参照できます。

参照セッション パラメータ

セッション パラメータ参照は、次のタイプのフルフィルメントの静的レスポンス メッセージで使用できます。

  • ページ エントリのフルフィルメント
  • ルートのフルフィルメント
  • イベント ハンドラのフルフィルメント
  • フォーム プロンプトのフルフィルメント
  • フォーム リプロンプトのフルフィルメント

セッション パラメータを参照するには、次の形式を使用します。

スカラー

スカラー エンティティ型のパラメータにアクセスするには、次のコマンドを実行します。

$session.params.parameter-id

たとえば、パラメータ ID が date の場合は、その値を $session.params.date として参照できます。

複合

複合エンティティ タイプのパラメータ メンバーにアクセスするには、次のコマンドを実行します。

$session.params.parameter-id.member-name

たとえば、パラメータ ID が location の場合、zip-code メンバー値を $session.params.location.zip-code として参照できます。

定価

リスト パラメータの ith 要素にアクセスするには次のコマンドを実行します。

$session.params.parameter-id[i]

たとえば、リスト パラメータ ID が colors の場合、最初の値を $session.params.colors[0] として参照できます。

セッション パラメータを設定する

フォームの入力が完了すると、入力したパラメータが Dialogflow によってセッションに書き込まれます。

ルート、イベント ハンドラ、フォーム リプロンプトのフルフィルメントでは、フルフィルメント パラメータ プリセットを使用して、実行時にセッション パラメータ値を設定できます。

Webhook では、実行時にセッション パラメータの値を設定できます。Webhook レスポンスsessionInfo.parameters フィールドをご覧ください。

API を操作すると、セッション パラメータ値を設定できます。detectIntent メソッドの queryParams.parameters リクエスト フィールドについては、をご覧ください。

セッション リファレンスのプロトコルとバージョンを選択:

プロトコル V3beta1
REST セッション リソース
RPC セッション インターフェース

セッション パラメータを取得する

API を操作すると、セッション パラメータ値が返されます。detectIntent メソッドの queryResult.parameters レスポンス フィールドについては、をご覧ください。

セッション リファレンスのプロトコルとバージョンを選択:

プロトコル V3beta1
REST セッション リソース
RPC セッション インターフェース

Webhook の受信セッション パラメータの値。Webhook リクエストsessionInfo.parameters フィールドをご覧ください。

パラメータの伝播

エンドユーザーがパラメータ値を入力すると、パラメータは他のレベルに伝播されます。

  • インテント マッチによってインテント パラメータが設定されると、アクティブなページの類似の名前のフォーム パラメータが同じ値に設定されます。パラメータのエンティティ タイプはインテント パラメータ定義によって規定されます。
  • インテント マッチによってインテント パラメータが設定されている場合や、フォームへの入力中にフォーム パラメータが設定されている場合、パラメータはセッション パラメータになります。