コンテキストを使用したダイアログのパーソナライズ

会話をパーソナライズするために、アシスタントは顧客から情報を収集し、後で会話でその情報を参照することができます。

ダイアログのターンをまたいで情報を保持する

ダイアログはステートレスです。つまり、ある対話でユーザーから取得した情報は次の対話まで保持されません。アシスタントにダイアログを追加してデプロイすると、アシスタントは、1 つのメッセージ呼び出しからコンテキストを保存し、現行セッション全体で次の要求時にそのコンテキストを再サブミットします。現行セッションは、ユーザーがアシスタントと対話し、さらに指定されたセッション非アクティブ時間フレームが経過するまで続きます。許可される最大セッション非アクティブ期間は、プラン・タイプに応じて、5 分から 7 日までの範囲です。ダイアログをアシスタントに追加しない場合、アプリケーションが必要とする継続的な情報を維持するのは、カスタム・アプリケーション開発者の責任です。

アプリケーションからダイアログに情報を渡すことができます。また、ダイアログでその情報を更新してアプリケーションに戻したり、後続のノードに渡したりすることもできます。そのために、ダイアログはコンテキスト変数 を使用します。

コンテキスト変数

コンテキスト変数は、ノード内で定義する変数です。これにはデフォルト値を指定できます。その後、他のノード、アプリケーション・ロジック、またはユーザー入力によって、コンテキスト変数の値を設定または変更できます。

ダイアログ・ノード条件でコンテキスト変数を参照してノードを実行するかどうかを決定することで、コンテキスト変数値を条件として使用できます。また、ダイアログ・ノードの応答条件からコンテキスト変数を参照して、外部サービスまたはユーザーによって提供される値に応じて異なる応答を表示することもできます。

詳細はこちら：

アプリケーションからコンテキストを渡す
ノードからノードへコンテキストを渡す
コンテキスト変数の定義
コンテキスト変数の一般的な作業
コンテキスト変数の削除
コンテキスト変数値の更新
コンテキスト変数の処理方法
操作の順序
スロットを含むノードへのコンテキスト変数の追加

アプリケーションからコンテキストを渡す

アプリケーションからダイアログに情報を渡すには、コンテキスト変数を設定し、コンテキスト変数をダイアログに渡します。

例えば、アプリケーションは、$time_of_day コンテキスト変数を設定し、それをダイアログに渡すことができます。ダイアログは、その情報を使用して、ユーザーに表示するあいさつを調整することができます。

アプリケーションからダイアログに渡される $time_of_day コンテキスト変数の値を検査するために応答条件を使用する Welcome ノードを示します。 — 時刻コンテキスト (Time of day context)

この例では、アプリケーションが変数を morning、afternoon、evening のどの値に設定したかを、ダイアログが認識します。ダイアログは各値をチェックし、設定された値に応じて適切なあいさつを返します。変数が渡されないか、変数値がどの期待値とも一致しない場合は、より一般的なあいさつがユーザーに表示されます。

ノードからノードへコンテキストを渡す

ダイアログではコンテキスト変数を追加して、あるノードから別のノードに情報を渡したり、コンテキスト変数の値を更新したりすることもできます。ダイアログは、ユーザーに情報を要求し、ユーザーから情報を取得すると、その情報を追跡し、後で会話でその情報を参照することができます。

例えば、あるノードでユーザーに名前を尋ね、後から別のノードでユーザーを名前で呼ぶことができます。

ユーザーに名前を要求し、それをコンテキスト変数として保管する導入ノードを表示します。次のノードは、$username コンテキスト変数を使用して、名前でユーザーを参照します。 — あるノードから別のノードへコンテキストを渡す

この例では、システム・エンティティー @name を使用して、入力からユーザーの名前を抽出します (ユーザーが入力した場合)。 JSON エディターで、ユーザー名のコンテキスト変数が定義され、@name 値に設定されます。それ以降のノードでは、$username コンテキスト変数を応答に指定して、ユーザーを名前で呼んでいます。

コンテキスト変数の定義

ノードの編集ビューで、**「変数 (Variable)」フィールドに変数名を追加して、「値 (Value)」**フィールドにそのデフォルト値を追加することによって、コンテキスト変数を定義します。

コンテキスト変数を追加するダイアログ・ノードをクリックして開きます。
アシスタントの応答 セクションに移動し、メニュー・アイコン「」をクリックします。
**「コンテキスト・エディターを開く (Open context editor)」**をクリックします。
変数の名前と値のペアを**「変数 (Variable)」フィールドおよび「値 (Value)」**フィールドに追加します。
- name には、大文字と小文字の英字、数字 (0 から 9)、および下線を含めることができます。
- value には、単純な文字列変数、数値、JSON 配列、JSON オブジェクトなど、サポートされている任意の JSON 型を使用できます。

以下の表は、さまざまな値のタイプの名前と値のペアを定義する方法のいくつかの例を示しています。

名前と値のペアの定義
変数	値	値のタイプ
dessert	"cake"	ストリング
age	18	数値
toppings_array	`["onions","olives"]`	JSON 配列
full_name	`{"first":"John","last":"Doe"}`	JSON オブジェクト

次に、これらのコンテキスト変数を参照するには、構文 $name を使用します。ここで、 name は、定義したコンテキスト変数の名前です。

例えば、ダイアログの応答として次の式を指定できます。

The customer, $age-year-old <? $full_name.first ?>, wants a pizza with <? $toppings_array.join(' and ') ?>, and then $dessert.

結果の出力は以下のように表示されます。

The customer, 18-year-old John, wants a pizza with onions and olives, and then cake.

JSON エディターを使用してコンテキスト変数を定義することもできます。複合式を変数値として追加する場合は JSON エディターを使用することをお勧めします。詳しくは、JSON エディターでのコンテキスト変数を参照してください。

コンテキスト変数の一般的な作業

ユーザーから入力として提供された文字列全体を保管するには、input.text を使用します。

ユーザー入力の取り込み
変数	値
repeat	`<?input.text?>`

例えば、ユーザー入力は次のようになります。 I want to order a device. ノード応答が You said: $repeat の場合、応答は次のように表示されます。 You said: I want to order a device.

エンティティーの値をコンテキスト変数に格納するには、次の構文を使用します。

エンティティー言及の取り込み
変数	値
プレース	`@place`

例えば、ユーザー入力が I want to go to Paris. 「 @place エンティティーが Paris を認識した場合、アシスタントは $place コンテキスト変数に Paris を保存します。

ユーザー入力から抽出した文字列の値を格納するには、ユーザー入力に正規表現を適用するextractメソッドを使用する SpEL 式を含めることができます。以下の式は、ユーザー入力から数値を抽出し、$number コンテキスト変数に保存します。

文字列メソッドの使用
変数	値
number	`<?input.text.extract('[\d]+',0)?>`

パターン・エンティティーの値を保管するには、エンティティー名に .literal を付加します。この構文を使用して、指定されたパターンに一致するユーザー入力からのテキストの正確なスパンが変数に保管されていることを確認してください。

パターン・エンティティー値の取り込み
変数	値
E メール	`<? @email.literal ?>`

例えば、ユーザー入力は Contact me at joe@example.com. Your entity that is named @email となり、 name@domain.com E メール・フォーマットを認識します。 @email.literal を保管するようにコンテキスト変数を構成して、パターンに一致した入力の一部を保管することを指定します。値式から .literal プロパティーを省略すると、パターンに一致したユーザー入力のセグメントではなく、パターンに指定したエンティティー値名が返されます。

コンテキスト変数の削除

コンテキスト変数を削除するには、変数を NULL に設定します。

コンテキスト変数の NULL 化
変数	値
order_form	`null`

コンテキスト変数値の更新

コンテキスト変数の値を更新するには、前のコンテキスト変数と同じ名前のコンテキスト変数を定義して、異なる値を指定します。

複数のノードで同じコンテキスト変数の値が設定されている場合、ユーザーとの会話の最中にコンテキスト変数の値が変わる場合があります。適用される値は、会話中にユーザーによってトリガーされるノードによって異なります。処理される最後のノードのコンテキスト変数に指定された値によって、以前に処理されたノードによって変数に設定された値が上書きされます。

値が JSON オブジェクトまたは JSON 配列データ・タイプであるときに、コンテキスト変数の値を更新する方法について詳しくは、JSON のコンテキスト変数値の更新を参照してください。

コンテキスト変数の処理方法

コンテキスト変数を定義する場所が重要です。アシスタントによって、コンテキスト変数を定義したダイアログ・ノードの部分が処理されるまで、コンテキスト変数が作成されることも、指定した値に設定されることもありません。多くの場合、ノード応答の一部としてコンテキスト変数を定義します。このようにする場合、アシスタントからノード応答が返されたときに、コンテキスト変数が作成されて、指定した値が付与されます。

ノードで条件付き応答を使用する場合、特定の応答の条件が満たされて、その応答が処理されるときに、コンテキスト変数が作成されて設定されます。例えば、条件付き応答 #1 のコンテキスト変数を定義し、アシスタントが応答 #2を処理する場合、条件付き応答 #1 に対して定義した変数は設定されません。

ユーザーがスロット付きのノードと対話するときにアシスタントで設定するコンテキスト変数の追加については、スロット付きのノードへのコンテキスト変数の追加を参照してください。

操作の順序

まとめて処理される複数の変数を定義した場合、それらは、定義した順序どおりにアシスタントで評価されるわけではありません。アシスタントではランダムな順序で変数が評価されます。最初のコンテキスト変数に値を設定しないでください。最初のコンテキスト変数が 2 番目のコンテキスト変数の前に実行されない可能性があるため、2 番目のコンテキスト変数で値を使用します。例えば、2 つのコンテキスト変数を使用して、ユーザー入力に Yes という語が含まれるかどうかをチェックするロジックを実装しないでください。

2 つのコンテキスト変数を使用してユーザー入力内の値を検査する
変数	値
user_input	`<? input.text ?>`
contains_yes	`<? $user_input.contains('Yes') ?>`

代わりに、リスト内の最初の変数の値 (user_input) が 2 番目の変数 (contains_yes) より先に評価されることに依存する必要がないように、少し複雑な式を使用します。

単一のコンテキスト変数の使用
変数	値
contains_yes	`<? input.text.contains('Yes') ?>`

スロットを含むノードへのコンテキスト変数の追加

スロットについて詳しくは、スロットを使用した情報の収集を参照してください。

スロットの応答条件が満たされた後に処理されるコンテキスト変数を追加するには、以下のようにします。

編集ビューでスロットを含むノードを開きます。
「スロットのカスタマイズ」 アイコンをクリックします。
「オプション」 アイコンをクリックし、 「条件を有効にする」 を選択します。
コンテキスト変数を関連付ける応答の横にある 「ハンドラーのカスタマイズ」 アイコンをクリックします。
アシスタントの応答セクションで 「オプション」 アイコンをクリックし、 「コンテキスト・エディターを開く」 をクリックします。
変数の名前と値のペアを**「変数 (Variable)」フィールドおよび「値 (Value)」**フィールドに追加します。

スロット条件が満たされた後に設定または更新されるコンテキスト変数を追加するには、次の手順を実行します。

編集ビューでスロットを含むノードを開きます。
「スロットのカスタマイズ」 アイコンをクリックします。
「オプション」 アイコンをクリックし、 「条件を有効にする」 を選択します。
JSON フォーマットで変数の名前と値のペアを追加します。

{
"time_of_day": "morning"
}

コンテキスト・エディターを使用して、ダイアログ・ノード評価のこのフェーズで設定されるコンテキスト変数を定義することはできません。代わりに JSON エディターを使用してください。 JSON エディターの使用について詳しくは、JSON エディターでのコンテキスト変数を参照してください。

JSON エディターでのコンテキスト変数

JSON エディターでコンテキスト変数を定義することもできます。複合コンテキスト変数を定義していて、追加または変更する際に完全な SpEL 式を表示できるようにする場合は、JSON エディターを使用します。

名前と値のペアは、以下の要件を満たしている必要があります。

name には、大文字と小文字の英字、数字 (0 から 9)、および下線を含めることができます。

名前にはピリオドやハイフンなど、その他の文字も使用できます。ただし、これを行う場合は、変数を参照するたびに省略表現構文 $(variable-name) を指定する必要があります。詳しくは、オブジェクトにアクセスするための式を参照してください。
value には、単純な文字列変数、数値、JSON 配列、JSON オブジェクトなど、サポートされている任意の JSON 型を使用できます。

次の JSON のサンプルでは、$dessert ストリング、$toppings_array 配列、$age 数値、および $full_name オブジェクトのコンテキスト変数の値を定義しています。

{
  "context": {
    "dessert": "cake",
    "toppings_array": [
      "onions",
      "olives"
    ],
    "age": 18,
    "full_name": {
      "first": "Jane",
      "last": "Doe"
    }
  },
  "output":{}
}

JSON フォーマットでコンテキスト変数を定義するには、以下の手順を実行します。

コンテキスト変数を追加するダイアログ・ノードをクリックして開きます。

このノードに定義されている既存のコンテキスト変数値が、対応する**「変数 (Variable)」フィールドと「値 (Value)」**フィールドのセットに表示されます。それらをノードの編集ビューに表示する必要がない場合は、コンテキスト・エディターを閉じる必要があります。 JSON エディターを開いたときに使用したのと同じメニューからエディターを閉じることができます。以下の手順で、メニューにアクセスする方法を説明します。
アシスタント応答の 「オプション」 アイコンをクリックし、 「JSON エディターを開く」 をクリックします。

ノードに対して 「複数の条件付き応答」 設定が有効になっている場合は、まず、コンテキスト変数を関連付ける応答の 「応答のカスタマイズ」 アイコンをクリックする必要があります。
"context":{} ブロックがない場合は追加します。
```
{
  "context":{},
  "output":{}
}
```
コンテキスト・ブロックに、定義する各コンテキスト変数の "name" と "value" のペアを追加します。
```
{
  "context":{
    "name": "value"
},
  "output": {}
}
```
この例では、 new_variable という名前の変数が、既に変数が含まれているコンテキスト・ブロックに追加されます。
```
{
  "context":{
    "existing_variable": "value",
    "new_variable":"value"
  }
}
```
コンテキスト変数を参照するには、構文 $name を使用します。ここで、 name は、定義したコンテキスト変数の名前です。例えば、$new_variableなどです。

詳細はこちら：

JSON のコンテキスト変数の削除
JSON のコンテキスト変数値の更新
別のコンテキスト変数と等しいコンテキスト変数の設定

JSON のコンテキスト変数の削除

コンテキスト変数を削除するには、変数を NULL に設定します。

{
  "context": {
    "order_form": null
  }
}

コンテキスト変数のすべてのトレースを削除する場合は、JSONObject.remove(string) メソッドを使用してコンテキスト・オブジェクトから削除することができます。ただし、削除を実行するには変数を使用する必要があります。メッセージ出力に新しい変数を定義して、現在の呼び出しの後で保存されないようにします。

{
  "output": {
    "text" : {},
    "deleted_variable" : "<? context.remove('order_form') ?>"
  }
}

また、アプリケーション・ロジックでコンテキスト変数を削除することもできます。

JSON のコンテキスト変数値の更新

通常、既に設定されていたコンテキスト変数の値をノードで設定すると、前の値が新しい値によって上書きされます。

複雑な JSON オブジェクトの更新

JSON オブジェクト以外の JSON タイプでは、前の値が上書きされます。コンテキスト変数が JSON オブジェクトなどの複合タイプである場合は、JSON のマージ処理を使用して変数が更新されます。マージ処理によって、新しく定義したプロパティーが追加され、オブジェクトの既存のプロパティーが上書きされます。

次の例では、名前のコンテキスト変数が複合オブジェクトとして定義されています。

{
  "context": {
    "complex_object": {
      "user_firstname" : "Paul",
      "user_lastname" : "Pan",
      "has_card" : false
    }
  }
}

このコンテキスト変数の JSON オブジェクトを、ダイアログ・ノードで次の値に更新します。

{
  "complex_object": {
    "user_firstname": "Peter",
    "has_card": true
  }
}

結果のコンテキストは次のようになります。

{
  "complex_object": {
    "user_firstname": "Peter",
    "user_lastname": "Pan",
    "has_card": true
  }
}

配列の更新

ダイアログのコンテキスト・データに値の配列が含まれている場合は、値を追加したり、削除したり、すべての値を置換したりして配列を更新できます。

以下のいずれかのアクションを選択して配列を更新できます。いずれの場合も、アクションの前に配列、アクション、およびアクションの適用後に配列が表示されます。

追加: 配列の最後に値を追加するには、append メソッドを使用します。

このダイアログ実行時のコンテキスト:

{
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

適用する更新:

{
  "context": {
    "toppings_array": "<? $toppings_array.append('ketchup', 'tomatoes') ?>"
  }
}

結果:

{
  "context": {
    "toppings_array": ["onion", "olives", "ketchup", "tomatoes"]
  }
}

削除: 要素を削除するには、remove メソッドを使用し、配列内の値または位置を指定します。

値で削除: 要素の値を指定して、配列から要素を削除します。

このダイアログ実行時のコンテキスト:

{
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

適用する更新:

{
  "context": {
    "toppings_array": "<? $toppings_array.removeValue('onion') ?>"
  }
}

結果:

{
  "context": {
    "toppings_array": ["olives"]
  }
}

位置で削除: 要素のインデックス位置を指定して、配列から要素を削除します。

このダイアログ実行時のコンテキスト:

{
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

適用する更新:

{
  "context": {
    "toppings_array": "<? $toppings_array.remove(0) ?>"
  }
}

結果:

{
  "context": {
    "toppings_array": ["olives"]
  }
}

上書き: 配列内の値を上書きするには、配列を新しい値に設定します。

このダイアログ実行時のコンテキスト:

{
  "context": {
    "toppings_array": ["onion", "olives"]
  }
}

適用する更新:

{
  "context": {
    "toppings_array": ["ketchup", "tomatoes"]
  }
}

結果:

{
  "context": {
    "toppings_array": ["ketchup", "tomatoes"]
  }
}

別のコンテキスト変数と等しいコンテキスト変数の設定

あるコンテキスト変数を別のコンテキスト変数と等しくなるように設定するときは、一方からもう一方までのポインターを定義します。後で、一方の変数の値が変更されると、もう一方の変数の値も変更されます。

例えば、次のようにコンテキスト変数を指定した場合、 $var1 または $var2 のいずれかの値が後で変更されると、その他の値も変更されます。

別のコンテキスト変数と等しいコンテキスト変数の設定
変数	値
var2	var1

ポイント・イン・タイム値を取り込む場合は、別の変数と等しくなるように変数を設定しないでください。配列を使用して、コンテキスト変数に保管されている配列値を取り込み、後でそれを使用する場合は、代わりに変数の現行値に基づいて新しい変数を作成します。

例えば、特定の時点における配列の値のコピーを作成するには、既存の配列の値が取り込まれた配列を追加します。これを行うには、以下の構文を使用できます。

{
"context": {
   "var2": "<? output.var2?:new JsonArray().append($var1) ?>"
 }
 }