ダイアログ内のオブジェクトにアクセスするための式

Spring Expression Language (SpEL) を使用して、オブジェクトやオブジェクトのプロパティーにアクセスする式を作成できます。 詳細は Spring Expression Language(SpEL )を参照。

評価構文

変数値を他の変数内で展開したり、プロパティーおよびグローバル・オブジェクトに対してメソッドを呼び出したりするには、<? expression ?> 式構文を使用します。 以下に例を示します。

  • プロパティーの展開

    "output":{"text":"Your name is <? context.userName ?>"}

  • グローバル・オブジェクトのプロパティーに対するメソッドの呼び出し

    "context":{"email": "<? @email.literal ?>"}

省略表現構文

SpEL 省略表現構文を使用して以下のオブジェクトを素早く参照する方法について説明します。

コンテキスト変数の省略表現構文

条件式でコンテキスト変数を記述するために使用できる、省略表現構文の例を次の表に示します。

省略表現構文
省略表現構文 SpEL での完全構文
$card_type context['card_type']
$(card-type) context['card-type']
$card_type:VISA context['card_type'] == 'VISA'
$card_type:(MASTER CARD) context['card_type'] == 'MASTER CARD'

ハイフンやピリオドなどの特殊文字をコンテキスト変数名に含めることができます。 ただし、そうすると、SpEL 式が評価されるときに問題が発生する可能性があります。 例えば、ハイフンはマイナス記号と解釈されるかもしれない。 そうした問題を回避するには、完全式の構文または省略表現構文 $(variable-name) のいずれかを使用して、変数を参照してください。また、以下の特殊文字を名前に使用しないでください。

  • 括弧()
  • 複数のアポストロフィ ''
  • 引用符"

テキスト応答またはダイアログ・ノード条件でコンテキスト変数を参照する場合は、短い構文を使用できます。

例えば、Hello, $name です。 $name コンテキスト変数に Sam が含まれている場合、応答は Hello, Sam と示されます。

テキスト応答で完全な構文を使用してコンテキスト変数を参照する場合は、<? ?> 内でコンテキスト変数を必ず囲んでください。 例えば、Hello, <? context['name'] ?> です。

複数のフィールドを持つコンテキスト変数 ($context.integrations.chat.browser_info.page_url など) を参照する場合。 完全な構文を使用するには、 <? context['integrations']['chat']['browser_info']['page_url'] ?>.

エンティティーの省略表現構文

次の表に、エンティティを参照するときに使用できる省略記法の例を示す。

省略表現構文
省略表現構文 SpEL での完全構文
@year entities['year']?.value
@year == 2016 entities['year']?.value == 2016
@year != 2016 entities['year']?.value != 2016
@city == 'Boston' entities['city']?.value == 'Boston'
@city:Boston entities['city']?.contains('Boston')
@city:(New York) entities['city']?.contains('New York')

SpEL では、疑問符 (?) を使用することで、エンティティー・オブジェクトが NULL の場合に NULL ポインター例外がトリガーされないようにします。

検査するエンティティー値に ) 文字が含まれる場合、比較のための : 演算子を使用できません。 例えば、city エンティティーが Dublin (Ohio) かどうかを検査する場合、@city == 'Dublin (Ohio)' ではなく、@city:(Dublin (Ohio)) を使用する必要があります。

インテントの省略表現構文

次の表に、インテントを参照する際に使用できる省略記法の例を示します。

| 省略構文 | SpEL のすべての構文 | | #help | intent == 'help' | | ! #help | intent != 'help' | | NOT #help | intent != 'help' | | #help または #i_am_lost | (intent == 'help' \|\| intent == 'I_am_lost') |

組み込みグローバル変数

式言語を使用して、以下のグローバル変数に関するプロパティー情報を抽出できます。

グローバル変数
グローバル変数 定義
コンテキスト 処理される会話メッセージの JSON オブジェクト部分。
エンティティー[ ] 1st 要素へのデフォルトアクセスをサポートするエンティティのリスト。
入力 処理される会話メッセージの JSON オブジェクト部分。
インテント[ ] 最初の要素へのデフォルトアクセスをサポートするインテントのリスト。
出力 処理される会話メッセージの JSON オブジェクト部分。

エンティティーへのアクセス

エンティティー配列には、ユーザー入力内で認識された 1 つ以上のエンティティーが含まれます。

ダイアログをテストしている間、ダイアログ・ノードのレスポンスでこの式を指定することで、ユーザー入力で認識されたエンティティの詳細を見ることができます：

<? entities ?>

ユーザー入力 今日の場合、アシスタントは @sys日付システム・エンティティーを認識するため、応答には以下のエンティティー・オブジェクトが含まれます。

 [
   {
     "entity":"sys-date",
     "location":[0,5],
     "value":"2020-12-30",
     "confidence":1.0,
     "metadata":
     {
       "calendar_type":"GREGORIAN",
       "timezone":"America/New_York"
     },
     "interpretation":
     {
       "timezone":"America/New_York",
       "relative_day":0,
       "granularity":"day",
       "calendar_type":"GREGORIAN"
      }
    }
  ]

応答にテキストを含める場合は、式で toJson() メソッドを使用して、返されたエンティティー・リストを JSON オブジェクトにキャストします。 以下に例を示します。

Recognized entities are: <? entities.toJson() ?>

入力でエンティティーの配置が重要な場合

条件式で省略記法 @city.contains('Boston') を使用すると、ダイアログ・ノードは、 Boston がユーザー入力で検出された最初のエンティティの場合のみ、 true を返します。 この構文は、入力中のエンティティの配置が重要で、最初の言及だけをチェックしたい場合にのみ使用する。

エンティティが言及される順序に関係なく、ユーザー入力で用語が言及されるたびに条件が真を返すようにしたい場合は、完全な SpEL 式を使用します。 条件 entities['city']?.contains('Boston') は、配置に関係なく、すべての@cityエンティティの中に少なくとも1つの「ボストン」都市エンティティのある場合に真を返す。

例えば、ユーザーが "I want to go from Toronto to Boston." を実行依頼すると、@city:Toronto エンティティーと @city:Boston エンティティーが検出され、以下のように返される配列で表されます。

  • entities.city[0].value = 'Toronto'
  • entities.city[1].value = 'Boston'

返される配列のエンティティーの順序は、ユーザー入力で言及された順序と一致します。

エンティティー・プロパティー

各エンティティは、それに関連付けられているプロパティのセットを持っています。 エンティティーに関する情報は、そのプロパティーから取得できます。

エンティティー・プロパティー
プロパティー (Property) 定義 使用方法のヒント
信頼性 認識されたエンティティーの、アシスタントの信頼度を表す小数で示す割合。 エンティティの信頼度は、エンティティのファジーマッチングを有効にしない限り、0 または 1 のいずれかです。 ファジー・マッチングが有効な場合、信頼度レベルのデフォルトしきい値は 0.3 です。 ファジーマッチングが有効かどうかにかかわらず、システム・エンティティの信頼レベルは常に 1.0 である。 このプロパティーを条件に使用すると、信頼度レベルが指定したパーセント以下の場合に false が戻されるようにすることができます。
所在地 入力テキストで検出されたエンティティー値の先頭と末尾を示す、ゼロを基準にした文字オフセット。 .literal を使用すると、location プロパティーに格納された開始インデックス値と終了インデックス値の間の、テキストのスパンを抽出できます。
価値 入力で識別されたエンティティー値。 このプロパティーによって、トレーニング・データで定義されているようにエンティティー値が戻されます。関連付けられた同義語のいずれかとマッチングした場合もそうなります。 .values を使用すると、ユーザー入力に存在するエンティティーの、複数のオカレンスを収集できます。

エンティティー・プロパティーの使用例

以下の例では、スキルに airport エンティティーが存在し、その値として JFK と、同義語「Kennedy Airport」が含まれます。 ケネディ空港に行きたい。

  • ユーザー入力に「JFK」エンティティが認識された場合に特定のレスポンスを返すには、レスポンス条件に次の式を追加する： entities.airport[0].value == 'JFK' または @airport = "JFK"

  • ユーザーがダイアログ応答で指定したとおりのエンティティ名を返すには、 .literal プロパティを使用します： So you want to go to <?entities.airport[0].literal?>... または So you want to go to @airport.literal ...

どちらのフォーマットも、 So you want to go to Kennedy Airport...。

  • @airport:(JFK) または @airport.contains('JFK') といった式は、エンティティーの value (この例では JFK) を常に参照します。

  • ファジー・マッチングが有効な場合に、入力で airport として識別する語句を制限するには、例えば次の式をノード条件に指定します。@airport && @airport.confidence > 0.7。 このノードは、アシスタントが入力テキストに空港リファレンスが含まれていることを70%確信した場合にのみ実行されます。

この例では、ユーザー入力は JFK、Logan、O'Hare に両替所はありますか? です。

  • ユーザー入力に含まれる、あるエンティティー・タイプの複数のオカレンスを収集するには、次のような構文を使用します。

    "context":{
  "airports":"@airport.values"
}

    取り込まれたリストを後でダイアログ応答で参照するには、次の構文を使用します。 You asked about these airports: <? $airports.join(', ') ?>. これは以下のように表示されます。 You asked about these airports: JFK, Logan, O'Hare.

  • 複数のエンティティー言及のリテラル値をキャプチャーするには、以下の構文を使用します。

    entities['myEntityName'].![literal]

インテントへのアクセス

intents 配列には、ユーザー入力で認識された 1 つ以上の intents が含まれ、信頼度の高い順にソートされる。

各インテントにはプロパティーが 1 つだけあります。それは confidence プロパティーです。 confidence プロパティーは、認識されたインテントの、アシスタントの信頼度を表す、小数で示す割合です。

ダイアログをテストしている間、ダイアログ・ノードのレスポンスでこの式を指定することで、ユーザー入力で認識されるインテントの詳細を見ることができます：

<? intents ?>

「こんにちは (Hello now)」というユーザー入力の場合、アシスタントは #greeting インテントとの完全一致を検索します。 したがって、#greeting インテント・オブジェクトの詳細を最初にリストします。 また信頼度スコアにかかわらず、スキルに定義されているその他のインテントの上位 10 件も応答に含められます。 (この例では、最初のインテントが完全一致なので、他のインテントの信頼度は 0 に設定されます。) 上位 10 件のインテントが返されるのは、「試行する (Try it out)」ペインで要求と共に alternate_intents:true パラメーターが送信されているためです。 直接 API を使用している場合に上位 10 件の結果を表示するには、呼び出し内でこのパラメーターを指定していることを確認してください。 デフォルト値である alternate_intents が false の場合、信頼度が 0.2 より高いインテントのみが配列に返される。

[{"intent":"greeting","confidence":1},
{"intent":"yes","confidence":0},
{"intent":"pizza-order","confidence":0}]

応答にテキストを含める場合は、式で toJson() メソッドを使用して、返されたインテント・リストを JSON オブジェクトにキャストします。 以下に例を示します。

Recognized intents are: <? intents.toJson() ?>

以下の例では、インテント値の検査方法を示します。

  • intents[0] == 'Help'
  • intent == 'Help'

intent == 'help' は intents[0] == 'help' と異なります。なぜなら、intent == 'help' は、インテントが検出されない場合でも例外をスローしないためです。 インテントの信頼度がしきい値を上回る場合にのみ、true に評価されます。 必要であれば、例えば intents.size() > 0 && intents[0] == 'help' && intents[0].confidence > 0.1 のように、条件にカスタム信頼レベルを指定することができます。

入力へのアクセス

入力 JSON オブジェクトに含まれるプロパティーは 1 つだけで、それは text プロパティーです。 text プロパティーはユーザー入力のテキストを表します。

入力プロパティーの使用例

次の例は、入力へのアクセス方法を示しています。

  • ユーザー入力が「Yes」の場合にノードを実行するには、次の式をノード条件に追加します。 input.text == 'Yes'

いずれかのストリング・メソッドを使用して、ユーザー入力のテキストを評価または操作することができます。 以下に例を示します。

  • ユーザー入力に「Yes」が含まれるかどうかを検査するには、次を使用します。input.text.contains( 'Yes' )。
  • 次を使用すると、ユーザー入力が数値の場合に true を返します。input.text.matches( '[0-9]+' )。
  • 入力ストリングに 10 文字含まれるかどうかを検査するには、次を使用します。input.text.length() == 10。