パラメータ

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

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

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

パラメータを命名する

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

• 使用する文字は [A-Z]、[a-z]、[0-9]、.、-、_ です。
• パラメータ名では、大文字と小文字は区別されません。つまり、Dialogflow CX では Apple と apple は同じパラメータとして扱われます。Webhook と API クライアント コードでも、大文字と小文字は区別されません。これは、Dialogflow CX から返されるパラメータ名に大文字と小文字の区別がないためです。
• 異なるインテントやフォームで同じ ID または表示名のパラメータを定義する場合は、エンティティ タイプとその他の設定がすべての定義に対して同じであることを確認してください。エンティティ タイプや他のパラメータ設定が異なる場合は、定義ごとに一意のパラメータ ID または表示名を使用します。

パラメータ値の種類

パラメータ値は、複数の値の種類をサポートしています。各パラメータ値の種類を参照する方法については、後述のセッションをご覧ください。次の型がサポートされています。

パラメータの空の文字列と null 値

文字列パラメータ値を "" に設定して、パラメータを空の文字列に設定できます。

任意のパラメータ値を null に設定して、パラメータがまだ設定されていないことを示せます。

パラメータの元の値

実行時にテキストが特定のエンティティに一致すると、処理に便利な値に解決されることがよくあります。たとえば、エンドユーザーの入力に含まれる単語「apples」は、果物のエンティティについては「apple」として解決されることがあります。

インテント パラメータ参照のすべての値タイプは、元の値または解決値のいずれかを参照できます。

元の値を参照できるのは、セッション パラメータ参照の複合値タイプのみです。

インテント パラメータ

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

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

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

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

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

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

元の値または解決された値のいずれかを参照できます。

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

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

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

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

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

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

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

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

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

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

フォーム パラメータ

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

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

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

フォーム パラメータの定義と管理

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

コンソールでフォーム パラメータの順序を変更するには、そのページの [パラメータ] セクション タイトルをクリックし、パラメータ テーブルでパラメータ行をドラッグします。

フォーム パラメータを削除するには、ページの [パラメータ] セクション タイトルをクリックし、パラメータにマウスでカーソルを合わせて、[削除] delete ボタンをクリックします。

参照フォーム パラメータ

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

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

$page.params.status = "FINAL"

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

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

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

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

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

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

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

フォーム入力

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

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

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

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

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

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

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

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

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

Webhook パラメータの設定

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

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

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

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

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

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

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

エンドユーザーが予期しない入力で応答すると、sys.no-match-* イベントまたは sys.no-input-* イベントが起動し、これらのイベントに定義されたリプロンプト ハンドラが呼び出されます。

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

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

セッション パラメータ

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

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

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

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

この参照は以下でも使用できます。

• 認証用の Webhook ヘッダー値。
• Webhook にパラメータ値を送信するためのフレキシブル Webhook リクエスト。

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

$session.params.parameter-id

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

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

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

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

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

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

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

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

パラメータの伝播

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

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

テレフォニー統合用の DTMF

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

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

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

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

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

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

エージェントを作成する際、シミュレータで DTMF 入力をテストできます。

スマート エンドポイント

エージェントでスマート エンドポイントが有効になっている場合は、数値パラメータのスマート エンドポイントの動作をカスタマイズできます。

1. [最小桁数] を設定すると、すべての数字が収集されるまで待機するようにスマート エンドポインターに指示できます。
2. [音声文字変換の修正] を設定すると、一般的な音声文字変換の数字のエラーを修正して数字の音声認識を改善できます。これは、en または en-* の言語コードを指定するリクエストでのみサポートされます。
3. [Waiting timeout] を設定して、ユーザーが追加の入力を提供するまでの待機時間を指定します。

フロースコープのパラメータ

フロースコープのパラメータは、フルフィルメント パラメータ プリセットまたはフォーム パラメータとして定義できます。これらのパラメータは、定義されているフローがアクティブである間のみ参照でき、セッション パラメータには永続化されません。

フロースコープのパラメータを定義または参照するには、次の構文を使用します。

$flow.parameter-name

たとえば、パラメータ名が date の場合、パラメータを $flow.date として定義または参照できます。

パラメータを定義するときに接頭辞 $ を使用することは、パラメータ定義に $ を使用しない他のパラメータ タイプとは異なることに注意してください。

フロースコープのパラメータ定義の例:

フロースコープのパラメータ値の有効期間

まれですが、特定の高度なケースでは、フローが非アクティブになってから再度アクティブになったときに、フロースコープのパラメータ値が保持（または破棄）される方法を理解することが必要になる場合があります。

フローが非アクティブになったときにフロースコープのパラメータ値が保持されるかどうかは、フロースタックとスタック上のフロー インスタンスによって変わります。

• フロー A が特定の遷移ターゲットを使用してフロー B に遷移すると、フロー A（親フロー）がスタックに残り、フロー A はそのフロースコープのパラメータ値を保持し、フロー B（子フロー）の新しいインスタンスがスタックに追加されます。
• 子フローがシンボリック遷移ターゲット（END_FLOW など）を使用して親フローに戻ると、子フローはスタックから削除され、子フロースコープのパラメータ値はすべて破棄され、親フロースコープのパラメータ値はすべて保持されます。
• 特定の遷移ターゲットを持つ一連の遷移を使用して、フロースタックに 1 つのフロータイプの複数のインスタンスを含めることができます。フロータイプの各インスタンスには、一意のフロースコープのパラメータ値があります。たとえば、A1 -> B1 -> C1 -> B2。ここで、A、B、C はフロータイプで、数字はフロータイプのインスタンスを表します。 この例では、B1 と B2 はフロー B のインスタンスであり、固有のフロースコープのパラメータがあります。

例:

リクエスト スコープのパラメータ

リクエスト スコープのパラメータは、Dialogflow CX によって作成された有効期間が短いパラメータです。最新のリクエストのライフサイクル中にのみ参照でき、セッション パラメータには永続化されません。

リクエスト スコープのパラメータは、次の機能のために Dialogflow CX によって生成されます。

組み込みパラメータ

以下を使用すると、リクエストに関連付けられたさまざまなデータにアクセスできます。

カスタム ペイロード

QueryParameters.payload が設定されている場合、対応するパラメータには $request.payload.param-id を介してアクセスできます。

感情分析

感情分析が有効になっている場合は、次の感情参照を使用できます。

パラメータの秘匿化

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

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

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

代わりに、特定のエンティティ タイプのすべてのパラメータを秘匿化することもできます。