アダプティブ ダイアログのイベントとトリガーEvents and triggers in adaptive dialogs

適用対象: 対象 SDK v4 対象外 SDK v3 APPLIES TO: yesSDK v4 no SDK v3

アダプティブ ダイアログでは、モデルの会話に、新しいイベント ベースのアプローチが導入されています。Adaptive dialogs introduce a new event based approach to model conversations. ボット内のすべてのサブシステムがイベントを出力でき、すべてのアダプティブ ダイアログには、これらのイベントに対応できるようにする_トリガー_と呼ばれるイベント ハンドラーが 1 つ以上含まれています。Any sub-system in your bot can emit events and all adaptive dialogs contain one or more event handlers called triggers that enable you to react to these events. イベントが発生するときはいつでも、アクティブなアダプティブ ダイアログのトリガーが評価され、現在のイベントに一致するトリガーがあると、そのトリガーに関連付けられているアクションが実行されます。Any time an event fires, the active adaptive dialog's triggers are evaluated and if any trigger matches the current event, the actions associated with that trigger execute. アクティブなダイアログでイベントが処理されない場合、イベントは親ダイアログに渡されて評価されます。If an event is not handled in the active dialog, it will be passed up to its parent dialog to be evaluated. このプロセスは、処理済みになるか、ボットのルート ダイアログに到達するまで続行されます。This process continues until it is either handled or reaches the bots root dialog. イベント ハンドラー (トリガー) が見つからない場合、そのイベントは無視され、アクションは実行されません。If no event handler (trigger) is found, the event will be ignored and no action will be taken.

前提条件Prerequisites

トリガーの構造Anatomy of a trigger

トリガーは、条件と 1 つ以上のアクションで構成されます。A trigger is made up of a condition and one or more actions. Bot Framework SDK には複数のトリガーが用意されており、それぞれに、eventName または eventValue のいずれかを調べる一連の定義済み条件があります。Bot Framework SDK offers several triggers, each with a set of predefined conditions that examine either the eventName or eventValue. トリガーに別の条件を追加すると、トリガーの実行時に追加の制御を行うことができます。You can add additional conditions to a trigger, giving you additional control when the trigger executes.

Bot Framework SDK には、一般的な種類のイベントを処理するために設計された、さまざまな定義済みのトリガーが用意されています。The Bot Framework SDK provides various pre-defined triggers designed to handle common event types. たとえば、OnIntent トリガーは、認識エンジン意図を検出するたびに起動されます。For example the OnIntent trigger fires anytime the recognizer detects an intent. LUIS 認識エンジンを使用している場合は、予測結果についての LUIS での信頼度を測定する予測スコアも返されます。If you are using a LUIS recognizer it will also return a prediction score that measures the degree of confidence LUIS has for its prediction results. ボットの信頼性と正確性を高めるために、信頼度の評価が 80% 以上の場合のみ、OnIntent トリガーを実行することが推奨されます。In order to increase the reliability and accuracy of your bot, you may only want to execute the OnIntent trigger if the confidence rating is 80% or higher. これは、_条件_を追加することによって実現できます。You can accomplish this by adding a condition. すべてのトリガーには、省略可能な Condition プロパティが含まれています。このプロパティは、定義されていると、トリガーを実行するためには true に評価される必要があります。Triggers all contain an optional Condition property that when defined, must evaluate to true in order for the trigger to execute. Condition プロパティは文字列ですが、有効なアダプティブ式が含まれている必要があります。The Condition property is a string, but must contain a valid adaptive expression to work. 上の例の Condition プロパティは、Condition = "#<IntentName>.Score >= 0.8" のようになります。The above examples Condition property would look something like: Condition = "#<IntentName>.Score >= 0.8". アダプティブ式を使用すると、起きる可能性のあるどのようなシナリオでもほぼ処理することができる高度な条件を実現できます。Adaptive expressions enable sophisticated conditions that can handle virtually any scenario that you might have.

すべてのトリガーには、_アクション_のリストも含まれています。All triggers also contain a list of Actions. アクションは、トリガーに応答してボットが実行することを表します。Actions represent what your bot does in response to a trigger. これがトリガーの核心です。This is the heart of the trigger. アダプティブ ダイアログのアクション」という記事では、アクションの詳細と、Bot Framework SDK でどのような組み込みアクションが提供されているかを確認できます。You can learn more about actions and what built in actions are provided in the Bot Framework SDK in the article Actions in adaptive dialogs.

トリガーの種類Trigger types

_トリガー_を使用すると、イベントのキャッチと応答が可能になります。Triggers enable you to catch and respond to events. 他のすべてのトリガーの派生元である、最も適用範囲の広いトリガーは OnCondition トリガーであり、いずれかのボット サブシステムによって特定のイベントが出力されたときに実行するアクションのリストをキャッチし、アタッチすることができます。The broadest trigger from which all other triggers are derived is the OnCondition trigger that allows you to catch and attach a list of actions to execute when a specific event is emitted by any of the bots sub-systems.

以降のセクションでは、トリガーの種類別に分類し、グループ化して、トリガーのリストを示します。Triggers are listed in the following sections, categorized and grouped by trigger type.

以降のセクションの各表では、現在 SDK に含まれているアダプティブ ダイアログでサポートされているすべてのトリガーと、それらの基になっているイベントを一覧で示しています。Each table in the following sections list all of the triggers supported by adaptive dialogs that are currently in the SDK as well as the events they are based on.

基本トリガーBase trigger

OnCondition トリガーは、すべてのトリガーの派生元である基本トリガーです。The OnCondition trigger is the base trigger that all triggers derive from. アダプティブダイアログでトリガーを定義する場合は、オブジェクトのリストとして定義され OnCondition ます。When defining triggers in an adaptive dialog they are defined as a list of OnCondition objects.

詳細と例については、アダプティブダイアログの事前に構築されたトリガーに関する記事のベーストリガーに関するセクションを参照してください。For more information and an example, see the Base trigger section in the Adaptive dialogs prebuilt triggers article.

認識エンジンのイベント トリガーRecognizer event triggers

認識エンジンは、ユーザーの入力から、意味のある情報を_意図_や_エンティティ_の形式で抽出し、それらが実行されるとイベントを出力します。Recognizers extract meaningful pieces of information from a user's input in the form of intents and entities and when they do, they emit events. たとえば、認識エンジンが特定のユーザーの発話から意図を取得する (またはエンティティを抽出する) と、recognizedIntent イベントが発生します。For example the recognizedIntent event fires when the recognizer picks up an intent (or extracts entities) from a given user utterance. このイベントは、トリガーを使用して処理し OnIntent ます。You handle this events using the OnIntent trigger.

Bot Framework SDK で使用できる_レコグナイザーイベントトリガー_の一部を次に示します。The following list shows some of the recognizer event triggers available in the Bot Framework SDK:

  • インテントを選択します。Choose Intent. この OnChooseIntent トリガーは、クロスセット内の複数のレコグナイザーからのインテントの間にあいまいさがある場合に実行されます。The OnChooseIntent trigger executes when there is ambiguity between intents from multiple recognizers in a CrossTrainedRecognizerSet.
  • インテントが認識されています。Intent recognized. 指定した OnIntent インテントが認識されると、トリガーが実行されます。The OnIntent trigger executes when the specified intent is recognized.
  • Qna と一致します。QnA Match. この OnQnAMatch トリガーは、 Qnamakerrecognizerがインテントを返したときに実行され QnAMatch ます。The OnQnAMatch trigger executes when the QnAMakerRecognizer has returned a QnAMatch intent.
  • インテントが認識されませんでしたNo intent was recognized. トリガーは、 OnUnknownIntent ユーザー入力が認識されない場合、またはいずれかのトリガーで一致が検出されなかった場合に実行され OnIntent ます。The OnUnknownIntent trigger executes when user input is unrecognized or no match is found in any of the OnIntent triggers. これを OnBeginDialog の代わりにルート ダイアログの最初のトリガーとして使用し、ダイアログが最初に開始されたときに、必要な任意のタスクを実行することもできます。You can also use this as your first trigger in your root dialog in place of the OnBeginDialog to preform any needed tasks when the dialog first starts.

詳細と例については、アダプティブダイアログの事前に構築されたトリガーに関する記事の「レコグナイザーイベントトリガー 」セクションを参照してください。For detailed information and examples, see the Recognizer event triggers section in the Adaptive dialogs prebuilt triggers article.

ダイアログ イベント トリガーDialog event triggers

ダイアログトリガーは、ダイアログの "ライフサイクル" に関連するダイアログ固有のイベントを処理します。Dialog triggers handle dialog specific events that are related to the "lifecycle" of the dialog. Bot Framework SDK には現在 6 つのダイアログ トリガーがあり、これらはすべて OnDialogEvent クラスから派生しています。There are currently 6 dialog triggers in the Bot Framework SDK and they all derive from the OnDialogEvent class.

ヒント

これらは、ハンドラー アクションの完了後に子のアクションが引き続き実行される通常の中断イベント ハンドラーとは似ていません。These aren't like normal interruption event handlers where the a child's actions will continue running after the handlers actions complete. 以下のすべてのイベントについて、ボットは新しい一連のアクションを実行し、いったんそれらのアクションが完了すると実行を終了します。For all of the events below the bot will be running a new set of actions and will end the turn once those actions have finished.

_ダイアログトリガー_の場合は、次のようになります。For the dialog trigger to:

  • ダイアログが開始されたらすぐにアクションを実行します。レコグナイザーが呼び出される前であっても、トリガーを使用し OnBeginDialog ます。Take action immediately when the dialog starts, even before the recognizer is called, use the OnBeginDialog trigger.
  • いずれかの子ダイアログがアクションを実行したときにダイアログがキャンセルされないようにする CancelAllDialogs には、トリガーを使用し OnCancelDialog ます。Prevent a dialog from being canceled when any of its child dialogs execute a CancelAllDialogs action, use the OnCancelDialog trigger.
  • すべてのアクションとあいまいなイベントが処理されたときにアクションを実行するには、トリガーを使用し OnEndOfActions ます。Take action when all actions and ambiguity events have been processed, use the OnEndOfActions trigger.
  • エラー状態を処理し OnError ます。トリガーを使用します。Handle an error condition, use the OnError trigger.

詳細と例については、アダプティブダイアログの事前に構築されたトリガーに関する記事の「ダイアログイベント」セクションを参照してください。For detailed information and examples, see the Dialog events section in the Adaptive dialogs prebuilt triggers article.

アクティビティ イベント トリガーActivity event triggers

アクティビティ トリガーを使用すると、新しいユーザーが参加し、ボットが新しい会話を開始するときなど、クライアントからのすべての受信アクティビティにアクションを関連付けることができます。Activity triggers let you associate actions to any incoming activity from the client such as when a new user joins and the bot begins a new conversation. アクティビティに関する追加情報については、Bot Framework アクティビティ スキーマに関するページを参照してください。Additional information on activities can be found in Bot Framework Activity schema.

すべてのアクティビティ イベントには基本イベント ActivityReceived があり、_アクティビティの種類_によってさらに細分化されます。All activity events have a base event of ActivityReceived and are further refined by their activity type. すべてのアクティビティ トリガーの派生元になっている基底クラスは OnActivity です。The Base class that all activity triggers derive from is OnActivity.

  • メッセージ交換の更新Conversation update. ユーザーが bot との新しいメッセージ交換を開始したときに発生するイベントを処理するために使用します。Use this to handle events fired when a user begins a new conversation with the bot.
  • メッセージ交換が終了しました。Conversation ended. EndOfConversation 型のアクティビティの受信時に実行するアクション。Actions to perform on receipt of an activity with type EndOfConversation.
  • イベントを受信しましたEvent received. Event 型のアクティビティの受信時に実行するアクション。Actions to perform on receipt of an activity with type Event.
  • 人間に引き渡します。Handover to human. HandOff 型のアクティビティの受信時に実行するアクション。Actions to perform on receipt of an activity with type HandOff.
  • メッセージ交換が呼び出されました。Conversation invoked. Invoke 型のアクティビティの受信時に実行するアクション。Actions to perform on receipt of an activity with type Invoke.
  • ユーザーが入力しています。User is typing. Typing 型のアクティビティの受信時に実行するアクション。Actions to perform on receipt of an activity with type Typing.

詳細と例については、アダプティブダイアログの事前に構築されたトリガーに関する記事の「アクティビティイベントトリガー 」セクションを参照してください。For detailed information and examples, see the Activity event triggers section in the Adaptive dialogs prebuilt triggers article.

メッセージ イベント トリガーMessage event triggers

メッセージ イベントのトリガーを使用すると、メッセージが更新されたとき (MessageUpdate) や削除されたとき (MessageDeletion)、または他のユーザーがメッセージに応答したとき (MessageReaction) など、どのようなメッセージ イベントにも対応できます (たとえば、よくあるメッセージの反応には、いいね!、ハート、笑い、驚いた、悲しい、怒った、といった反応が含まれます)。Message event triggers allow you to react to any message event such as when a message is updated (MessageUpdate) or deleted (MessageDeletion) or when someone reacts (MessageReaction) to a message (for example, some of the common message reactions include a Like, Heart, Laugh, Surprised, Sad and Angry reactions).

メッセージ イベントは一種のアクティビティ イベントであり、そのためすべてのメッセージ イベントには基本イベント ActivityReceived があり、"アクティビティの種類" によってさらに細分化されます。Message events are a type of activity event and, as such, all message events have a base event of ActivityReceived and are further refined by activity type. すべてのメッセージ トリガーの派生元になっている基底クラスは OnActivity です。The Base class that all message triggers derive from is OnActivity.

  • メッセージを受信しましたMessage received. MessageReceived 型のアクティビティの受信時に実行するアクション。Actions to perform on receipt of an activity with type MessageReceived.
  • メッセージが削除されましたMessage deleted. MessageDelete 型のアクティビティの受信時に実行するアクション。Actions to perform on receipt of an activity with type MessageDelete.
  • メッセージの反応Message reaction. MessageReaction 型のアクティビティの受信時に実行するアクション。Actions to perform on receipt of an activity with type MessageReaction.
  • メッセージが更新されましたMessage updated. MessageUpdate 型のアクティビティの受信時に実行するアクション。Actions to perform on receipt of an activity with type MessageUpdate.

詳細と例については、アダプティブダイアログの事前に構築されたトリガーに関する記事の「メッセージイベントトリガー 」セクションを参照してください。For detailed information and examples, see the Message event triggers section in the Adaptive dialogs prebuilt triggers article.

カスタムイベントトリガーCustom event trigger

任意のトリガーに EmitEvent アクションを追加することによって、独自のイベントを出力できます。その後、ボットの任意のダイアログで、任意のトリガー内に_カスタム イベント_ トリガーを定義することで、そのカスタム イベントを処理できます。You can emit your own events by adding the EmitEvent action to any trigger, then you can handle that custom event in any trigger in any dialog in your bot by defining a custom event trigger. カスタム イベント トリガーは、Event プロパティを EmitEvent の EventName プロパティと同じ値に設定したときに実際にカスタム トリガーになる OnDialogEvent トリガーです。A custom event trigger is the OnDialogEvent trigger that in effect becomes a custom trigger when you set the Event property to the same value as the EmitEvent's EventName property.

ヒント

EmitEvent の BubbleEvent プロパティを true に設定することによって、ボット内の他のダイアログでカスタム イベントを処理することができます。You can allow other dialogs in your bot to handle your custom event by setting the EmitEvent's BubbleEvent property to true. 詳細と例については、アダプティブダイアログの作成済みトリガーに関する記事の [カスタムイベント] [カスタムイベント] セクションを参照してください。For more information and an example, see the [Custom events][custom-events] section in the Adaptive dialogs prebuilt triggers article.

詳細と例については、アダプティブダイアログの作成済みトリガーに関する記事の [カスタムイベントトリガー] [カスタムイベントトリガー] セクションを参照してください。For detailed information and an example, see the [Custom event triggers][custom-event-triggers] section in the Adaptive dialogs prebuilt triggers article.

追加情報Additional Information