パラメータ

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

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

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

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

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

パラメータを命名する

パラメータの命名には次のルールが適用されます。

  • 使用する文字は [A-Z][a-z][0-9].-_ です。
  • パラメータ名では、大文字と小文字は区別されません。つまり、Dialogflow では Appleapple は同じパラメータとして扱われます。Webhook と API クライアント コードでも、大文字と小文字は区別されません。これは、Dialogflow から返されるパラメータ名に大文字と小文字の区別がないためです。

インテント パラメータ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

プロトコル V3 V3beta1
REST セッション リソース セッション リソース
RPC セッション インターフェース セッション インターフェース
C# 提供なし 利用できません
Go 提供なし 利用できません
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP 提供なし 利用できません
Python SessionsClient SessionsClient
Ruby 提供なし 利用できません

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

フォーム パラメータ

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

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

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

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

コンソールのオプション名 API フィールド チェーン 説明
表示名 Page.form.parameters[].displayName パラメータを識別する名前。
エンティティ タイプ Page.form.parameters[].entityType パラメータに関連付けられているエンティティ タイプ
必須 Page.form.parameters[].required パラメータが必須かどうかを示します。フォーム入力が完了する前に必須パラメータを入力し、エージェントがエンドユーザーに値の入力を求めます。詳しくは、後述のフォーム パラメータを設定するをご覧ください。
デフォルト値(必須チェックボックスがオフになっている場合にのみ表示) Page.form.parameters[].defaultValue 省略可能なパラメータのデフォルト値。詳しくは、後述のフォーム パラメータを設定するをご覧ください。
Is list Page.form.parameters[].isList true の場合、パラメータは値のリストとして扱われます。
ログ内での秘匿化 Page.form.parameters[].redact true の場合、エンドユーザーが指定したパラメータ データが秘匿化されます。
最初のプロンプトのフルフィルメント Page.form.parameters[].fillBehavior.initialPromptFulfillment フルフィルメント形式の初期プロンプトで、エンドユーザーから必須パラメータ値をリクエストします。詳しくは、後述のフォーム パラメータを設定するをご覧ください。
リプロンプト イベント ハンドラ Page.form.parameters[].fillBehavior.repromptEventHandlers 一度失敗した後にエージェントがエンドユーザーに再びパラメータの入力を促す必要がある場合に使用します。フォーム入力のリプロンプト ハンドラをご覧ください。
DTMF 利用不可 下記の DTMF のセクションをご覧ください。

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

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

コンソールでパラメータの順序を変更するには、ページの [パラメータ] セクション タイトルをクリックし、左側に表示されるパラメータ テーブルでパラメータ行をドラッグ&ドロップします。

参照フォーム パラメータ

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

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

$page.params.status = "FINAL"

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

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

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

フォーム パラメータ値はさまざまな方法で設定できます。以下のサブセクションでは、フォーム パラメータ値を設定するための各メカニズムについて説明します。

デフォルトのパラメータ値

任意のフォーム パラメータにデフォルト値を指定できます。 フォーム入力が開始されると、未設定のフォーム パラメータがすべてデフォルト値に設定されます。これらの値は、以下に示すメカニズムの一部で初期化またはオーバーライドできます。

パラメータが必須の場合、デフォルト値は無視されます。

フォーム入力

Dialogflow では、フォームの入力中にエンドユーザーから提供されたパラメータ値が自動的に設定されます。 エージェントは、ページで定義された順序で必須パラメータを収集します。エージェントは、エンドユーザーに、各必須パラメータに指定した初期プロンプト フルフィルメントを使用して必要な値を要求します。オプションのパラメータはプロンプトをトリガーしません。

エージェント プロンプトの後にエンドユーザーが必須パラメータ値を指定しない場合は、リプロンプト ハンドラで別の動作が定義されていない限り、初期プロンプトが繰り返されます。 複数の初期テキスト プロンプトが定義されている場合、エージェントの動作はフルフィルメント テキスト レスポンスの動作と同じです。

インテントとセッション パラメータの伝搬

実行時に任意のタイプのパラメータが設定されると、パラメータがセッションに書き込まれ、セッション パラメータになります。

ページが最初にアクティブになると、アクティブ期間中に、セッション パラメータと同じ名前のフォーム パラメータが自動的にセッション パラメータ値に設定されます。

これは、インテント ルートまたはパラメータの伝搬でマッチングされるインテント パラメータで発生することがあります。

インテントとセッション パラメータの伝搬は、オプションのフォーム パラメータをエンドユーザー入力の値に設定する唯一のメカニズムですが、必須フォーム パラメータ値を設定またはオーバーライドすることもできます。

フルフィルメント パラメータのプリセット

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

Webhook パラメータの設定

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

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

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

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

プロトコル V3 V3beta1
REST セッション リソース セッション リソース
RPC セッション インターフェース セッション インターフェース
C# 提供なし 利用できません
Go 提供なし 利用できません
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP 提供なし 利用できません
Python SessionsClient SessionsClient
Ruby 提供なし 利用できません

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

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

リプロンプト ハンドラ(パラメータ レベル イベント ハンドラとも呼ばれます)は、必須パラメータの複雑なパラメータ プロンプト動作を定義するために使用されます。たとえば、リプロンプト ハンドラを使用すると、エンドユーザーが最初のプロンプトで値を提供できなかった場合にプロンプトを変更し、N 回の失敗後に別のページに遷移することができます。

リプロンプト ハンドラが定義されていない場合、必要に応じてエンドユーザーに再プロンプトを求める最初のプロンプトが使用されます。

エンドユーザーが予期しない入力で応答すると、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 として参照できます。

定価

  • 要素の完全なリストにアクセスするには次のコマンドを実行します。

    $session.params.parameter-id

    たとえば、リスト パラメータ ID が colors で、ユーザークエリから抽出された値が ["red", "blue", "yellow"] の場合、すべての値を $session.params.colors として参照できます。

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

    $session.params.parameter-id[i]

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

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

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

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

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

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

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

プロトコル V3 V3beta1
REST セッション リソース セッション リソース
RPC セッション インターフェース セッション インターフェース
C# 提供なし 利用できません
Go 提供なし 利用できません
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP 提供なし 利用できません
Python SessionsClient SessionsClient
Ruby 提供なし 利用できません

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

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

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

プロトコル V3 V3beta1
REST セッション リソース セッション リソース
RPC セッション インターフェース セッション インターフェース
C# 提供なし 利用できません
Go 提供なし 利用できません
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP 提供なし 利用できません
Python SessionsClient SessionsClient
Ruby 提供なし 利用できません

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

パラメータの伝播

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

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

テレフォニー パートナー統合用の DTMF

パラメータに対して DTMF(デュアルトーン マルチ周波数信号)を有効にして構成できます。有効にすると、テレフォニー パートナー 統合を使用するエージェントのエンドユーザーは、電話キーパッドを使用してパラメータ値を指定できます。

あいまいさを軽減するために、DTMF 入力は、通常の形式と DTMF 固有の形式(推奨)の両方で解釈できます。

  • 通常の形式は、エンドユーザーが入力したキーパッド値にすぎません。例:123#
  • DTMF 固有の形式は、入力を dtmf_digits_[digits] に変換します。ここで、[digits]*star に置き換え、#pound に置き換えた元の DTMF 数字です。たとえば、123#dtmf_digits_123pound として解釈されます。

パラメータのエンティティ タイプを一致させる場合、Dialogflow は通常の形式と DTMF 固有の形式の両方を一致させようとします。DTMF 入力にエンティティ タイプを使用する場合、NLU マッチングを改善するために dtmf_digits_123 などの類義語を定義することをおすすめします。

DTMF 入力が終了条件を満たさない場合(最大桁数に達していないか、終了桁によって終了されていない場合)、Dialogflow エージェントはさらに入力を待機します。この期間中に、音声なしタイムアウトがトリガーされると、エージェントによって入力なしイベントが起動されます。 発話のみが検出された場合、エージェントは音声入力と照合されます。音声と DTMF 入力の両方が検出されると、音声入力は破棄され、DTMF 入力のみが考慮されます。

パラメータ用の DTMF を有効にしてカスタマイズするには:

コンソール

  1. エージェントの音声と IVR の設定で [Advanced settings] が有効になっていない場合は、有効にします。
  2. ページ パラメータを作成します。
  3. パラメータ ペインで、[Max digits] をオンにします。
  4. [Max digits] に、エンドユーザーがこのパラメータに入力できる最大数を設定します。
  5. [Finishdigit] を、パラメータの DTMF 入力を終了するキーパッド値に設定します。通常、この設定には # を使用します。 終了ディジットはエージェントの Dialogflow クエリには追加されません。つまり、終了ディジットが # で、入力が 123# の場合、実際のクエリ入力は「123」になります。

パラメータの秘匿化

インテント パラメータまたはフォーム パラメータの場合、パラメータの秘匿化を有効にできます。これにより、ログと Dialogflow の内部ストレージからエンドユーザーのランタイム パラメータ データが秘匿化されます。秘匿化されたパラメータは、ログで $parameter-name_redacted として表示されます。

たとえば、エンドユーザーが「My address is 1600 Amphitheatre Parkway」と入力した場合、「1600 Amphitheatre Parkway」に address パラメータが送信されることになります。ログテキストは「My address is $address_redacted」になります。

パラメータの秘匿化を有効にするには:

コンソール

パラメータの作成時または更新時に [Redact in log] チェックボックスをオンにします。

API

Intent タイプで parameters[].redact フィールドを true に設定します。

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

プロトコル V3 V3beta1
REST インテント リソース インテント リソース
RPC インテント インターフェース インテント インターフェース
C# 提供なし 利用できません
Go 提供なし 利用できません
Java IntentsClient IntentsClient
Node.js IntentsClient IntentsClient
PHP 提供なし 利用できません
Python IntentsClient IntentsClient
Ruby 提供なし 利用できません

Page タイプで form.parameters[].redact フィールドを true に設定します。

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

プロトコル V3 V3beta1
REST ページリソース ページリソース
RPC ページ インターフェース ページ インターフェース
C# 提供なし 利用できません
Go 提供なし 利用できません
Java PagesClient PagesClient
Node.js PagesClient PagesClient
PHP 提供なし 利用できません
Python PagesClient PagesClient
Ruby 提供なし 利用できません