アクティビティ ハンドラーを使用したイベント駆動型の会話Event-driven conversations using an activity handler

適用対象: SDK v4APPLIES TO: SDK v4

アクティビティ ハンドラーは 、ボットの会話ロジックを整理するためのイベント駆動型の方法です。An activity handler is an event-driven way to organize the conversational logic for your bot. アクティビティの種類またはサブタイプは、それぞれ異なる種類の会話イベントを表します。Each different type or sub-type of activity represents a different type of conversational event. ボットのターン ハンドラーは、受信したアクティビティの種類に対して個々のアクティビティ ハンドラーを呼び出します。Under the covers, the bot's turn handler calls the individual activity handler for whatever type of activity it received.

たとえば、ボットがメッセージ アクティビティを受信した場合、ターン ハンドラーは受信アクティビティを確認し、それを on メッセージ アクティビティ アクティビティ ハンドラーに送信します。For example, if the bot receives a message activity, the turn handler would see that incoming activity and send it to the on message activity activity handler. ボットを構築するときに、メッセージを処理して応答するボット ロジックは、メッセージ アクティビティ ハンドラーで この中に入 ります。When building your bot, your bot logic for handling and responding to messages will go in this on message activity handler. 同様に、会話に追加されるメンバーを処理するロジックは、メンバーが会話に追加されるたびに呼び出される on members added handler に入されます。Likewise, your logic for handling members being added to the conversation will go in your on members added handler, which is called whenever a member is added to the conversation.

ボット ロジックを整理するその他の方法については 、ボットの動作に関するページのボット ロジック に関するセクションを参照してくださいFor other ways to organize your bot logic, see the bot logic section in how bots work.

これらのハンドラーのロジックを実装するには、以下のサンプル アクティビティ ハンドラー セクションのように、ボットでこれらのメソッド オーバーライドします。To implement your logic for these handlers, you will override these methods in your bot, such as in the sample activity handler section below. これらのハンドラーそれぞれに基本実装はありません。このため、必要なロジックをご自身のオーバーライドに追加するだけです。For each of these handlers, there is no base implementation, so just add the logic that you want in your override.

基本ターン ハンドラーのオーバーライドが必要になる場合もあります。たとえば、ターンの最後に状態を保存するような状況です。There are certain situations where you will want to override the base turn handler, such as saving state at the end of a turn. これを行う場合は、最初に必ず await base.OnTurnAsync(turnContext, cancellationToken); を呼び出して、OnTurnAsync の基本実装がご自身の追加コードの前に実行されていることを確認します。When doing so, be sure to first call await base.OnTurnAsync(turnContext, cancellationToken); to make sure the base implementation of OnTurnAsync is run before your additional code. この実装は特に、OnMessageActivityAsync などの残りのアクティビティ ハンドラーを呼び出す役割を果たします。That base implementation is, among other things, responsible for calling the rest of the activity handlers such as OnMessageActivityAsync.

アクティビティの処理Activity handling

ボット ロジックは 1 つ以上のチャネルからの受信アクティビティを処理し、応答の送信アクティビティを生成します。The bot logic processes incoming activities from one or more channels and generates outgoing activities in response.

メイン ボット ロジックは、ボット コードで定義されます。The main bot logic is defined in the bot code. Bot をアクティビティハンドラーとして実装するには、インターフェイスを実装するから bot クラスを派生させ ActivityHandler IBot ます。To implement a bot as an activity handler, derive your bot class from ActivityHandler, which implements the IBot interface. ActivityHandler さまざまな種類のアクティビティ (、など) のさまざまなハンドラーを定義し OnMessageActivityAsync OnMembersAddedAsync ます。ActivityHandler defines various handlers for different types of activities, such as OnMessageActivityAsync, and OnMembersAddedAsync. これらのメソッドは保護されていますが、から派生しているためオーバーライドでき ActivityHandler ます。These methods are protected, but can be overridden, since we're deriving from ActivityHandler.

ActivityHandler で定義されているハンドラーを次に示します。The handlers defined in ActivityHandler are:

EventEvent HandlerHandler 説明Description
任意のアクティビティの種類を受信したAny activity type received OnTurnAsync 受信したアクティビティの種類に基づいて、他のハンドラーのいずれかを呼び出します。Calls one of the other handlers, based on the type of activity received.
メッセージ アクティビティを受信したMessage activity received OnMessageActivityAsync これをオーバーライドして message アクティビティを処理します。Override this to handle a message activity.
会話の更新アクティビティを受信したConversation update activity received OnConversationUpdateActivityAsync conversationUpdate アクティビティで、ボット以外のメンバーが会話に参加した場合、または会話から退出した場合にハンドラーを呼び出します。On a conversationUpdate activity, calls a handler if members other than the bot joined or left the conversation.
ボットではないメンバーが会話に参加したNon-bot members joined the conversation OnMembersAddedAsync これをオーバーライドして、会話に参加するメンバーを処理します。Override this to handle members joining a conversation.
ボットではないメンバーが会話から退出したNon-bot members left the conversation OnMembersRemovedAsync これをオーバーライドして、会話から退出メンバーを処理します。Override this to handle members leaving a conversation.
イベント アクティビティを受信したEvent activity received OnEventActivityAsync event アクティビティで、イベントの種類に固有のハンドラーを呼び出します。On an event activity, calls a handler specific to the event type.
Token-response イベント アクティビティを受信したToken-response event activity received OnTokenResponseEventAsync これをオーバーライドして、トークン応答イベントを処理します。Override this to handle token response events.
Non-token-response イベント アクティビティを受信したNon-token-response event activity received OnEventAsync これをオーバーライドして、その他の種類のイベントを処理します。Override this to handle other types of events.
メッセージの反応アクティビティを受信したMessage reaction activity received OnMessageReactionActivityAsync messageReaction アクティビティで、メッセージに対して 1 つ以上の反応が追加または削除された場合にハンドラーを呼び出します。On a messageReaction activity, calls a handler if one or more reactions were added or removed from a message.
メッセージの反応がメッセージに追加されたMessage reactions added to a message OnReactionsAddedAsync これをオーバーライドして、メッセージに追加された反応を処理します。Override this to handle reactions added to a message.
メッセージの反応がメッセージから削除されたMessage reactions removed from a message OnReactionsRemovedAsync これをオーバーライドして、メッセージから削除された反応を処理します。Override this to handle reactions removed from a message.
インストールの更新活動を受信しましたInstallation update activity received OnInstallationUpdateActivityAsync アクティビティでは installationUpdate 、は bot がインストールまたはアンインストールされたかどうかに基づいてハンドラーを呼び出します。On an installationUpdate activity, calls a handler based on whether the bot was installed or uninstalled.
ボットがインストールされたBot installed OnInstallationUpdateAddAsync 組織単位内に bot をインストールする場合のロジックを追加するには、これをオーバーライドします。Override this to add logic for when the bot is installed within an organizational unit.
アンインストールされた BotBot uninstalled OnInstallationUpdateRemoveAsync 組織単位内でボットがアンインストールされたときのロジックを追加するには、これをオーバーライドします。Override this to add logic for when the bot is uninstalled within an organizational unit.
他のアクティビティの種類を受信したOther activity type received OnUnrecognizedActivityTypeAsync これをオーバーライドして、他の方法では処理されない任意のアクティビティの種類を処理します。Override this to handle any activity type otherwise unhandled.

このような各種ハンドラーにインバウンド アクティビティに関する情報を提供する turnContext があり、これはインバウンド HTTP 要求に対応しています。These different handlers have a turnContext that provides information about the incoming activity, which corresponds to the inbound HTTP request. アクティビティの種類もさまざまであるため、各ハンドラーが、そのターン コンテキスト パラメーターで厳密に型指定されたアクティビティを提供します。ほとんどの場合、OnMessageActivityAsync は常に処理され通常は最も一般的です。Activities can be of various types, so each handler provides a strongly-typed activity in its turn context parameter; in most cases, OnMessageActivityAsync will always be handled, and is generally the most common.

このフレームワークの以前の 4.x バージョンでは、パブリック メソッド OnTurnAsync を実装するオプションもあります。As in previous 4.x versions of this framework, there is also the option to implement the public method OnTurnAsync. 現在、このメソッドの基本実装はエラー チェックを処理し、各受信アクティビティの種類に応じて、特定のハンドラー (たとえば、このサンプルでは定義する 2 つのハンドラー) をそれぞれ呼び出します。Currently, the base implementation of this method handles error checking and then calls each of the specific handlers (like the two we define in this sample) depending on the type of incoming activity. ほとんどの場合、このメソッドはそのままにして、個別のハンドラーを使用できますが、OnTurnAsync のカスタム実装が必要な場合でも、これは引き続き使用できます。In most cases, you can leave that method alone and use the individual handlers, but if your situation requires a custom implementation of OnTurnAsync, it is still an option.

重要

OnTurnAsync メソッドをオーバーライドする場合は、base.OnTurnAsync を呼び出して、他のすべての On<activity>Async ハンドラーを呼び出すための基本実装を取得するか、ご自身でこれらのハンドラーを呼び出す必要があります。If you do override the OnTurnAsync method, you'll need to call base.OnTurnAsync to get the base implementation to call all the other On<activity>Async handlers or call those handlers yourself. それ以外の場合、これらのハンドラーは呼び出されず、そのコードは実行されません。Otherwise, those handlers won't be called and that code won't be run.

サンプル アクティビティ ハンドラーSample activity handler

たとえば、会話にユーザーを歓迎するために追加されたメンバーを処理し、メッセージを処理してボットに送信するメッセージをエコーバックすることができます。For example, you can handle on members added to welcome users to a conversation, and handle on message to echo back messages they send to the bot.

public class EchoBot : ActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        var replyText = $"Echo: {turnContext.Activity.Text}";
        await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
    }

    protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
    {
        var welcomeText = "Hello and welcome!";
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text(welcomeText, welcomeText), cancellationToken);
            }
        }
    }
}

次のステップNext steps

  • Microsoft Teams チャネルでは、Teams と適切に動作するためにボットがサポートする必要がある Teams 固有のアクティビティがいくつか導入されています。The Microsoft Teams channel introduces some Teams-specific activities that your bot will need to support to work properly with Teams. Microsoft Teams のボット開発の主要な概念を理解するには、「Microsoft Teams のボットのしくみ」を参照してくださいTo understand key concepts of developing bots for Microsoft Teams, see How Microsoft Teams bots work
  • アクティビティ ハンドラーは、ターン間の会話状態を追跡する必要はないボットを設計するための優れた方法です。An activity handler is a good way to design a bot that does not need to track conversational state between turns. ダイアログ ライブラリには、 ユーザーとの長時間の会話を管理する方法が用意されています。The dialogs library provides ways to manage a long-running conversation with the user.