アクティビティ ハンドラーを使用したイベント ドリブンの会話

適用対象: SDK v4

アクティビティ ハンドラーは、ボットの会話ロジックを整理するためのイベントドリブンの方法です。 アクティビティの種類またはサブタイプはそれぞれ、異なる種類の会話イベントを表します。 ボットの ターン ハンドラー では、受信したアクティビティの種類に対して個々のアクティビティ ハンドラーが呼び出されます。

たとえば、ボットがメッセージ アクティビティを受信した場合、ターン ハンドラーはその受信アクティビティを確認し、それを on message アクティビティ アクティビティ ハンドラーに 送信します。 ボットを構築するときに、メッセージを処理および応答するためのボット ロジックは、 メッセージ アクティビティ ハンドラーで これに含まれます。 同様に、会話に追加されるメンバーを処理するためのロジックは、メンバーがスレッド に追加 されるたびに呼び出される、追加されたメンバーのハンドラーに入ります。

ボット ロジックを整理するその他の方法については、ボットの動作に関するセクションの ボット ロジック関するセクションを参照してください。

Note

Bot Framework Python と Java SDK は、2023 年 11 月に終了する最終的な長期サポートで廃止される予定です。 このリポジトリ内の重要なセキュリティとバグの修正のみが行われます。 これらの SDK で構築された既存のボットは引き続き機能します。

新しいボット開発の場合は、 Power Virtual Agents の使用を検討してください。 詳細については、「 ボット構築の未来」を参照してください。

これらのハンドラーのロジックを実装するには、以下の サンプル アクティビティ ハンドラー セクションのように、ボットでこれらのメソッドをオーバーライドします。 これらのハンドラーごとに、基本実装がないため、オーバーライドに必要なロジックを追加するだけです。

ターンの最後に 状態を保存 するなど、ベース ターン ハンドラーをオーバーライドする場合があります。 これを行う場合は、最初に必ず await base.OnTurnAsync(turnContext, cancellationToken); を呼び出して、OnTurnAsync の基本実装がご自身の追加コードの前に実行されていることを確認します。 この実装は特に、OnMessageActivityAsync などの残りのアクティビティ ハンドラーを呼び出す役割を果たします。

アクティビティの処理

ボット ロジックは 1 つ以上のチャネルからの受信アクティビティを処理し、応答の送信アクティビティを生成します。

メイン ボット ロジックは、ボット コードで定義されます。 ボットをアクティビティ ハンドラーとして実装するには、 から ActivityHandlerボット クラスを派生させます。これにより、 インターフェイスが IBot 実装されます。 ActivityHandler では、 や など OnMessageActivityAsync、さまざまな種類のアクティビティに対してさまざまなハンドラーが定義されます OnMembersAddedAsync。 これらのメソッドは保護されていますが、 から ActivityHandler派生しているため、オーバーライドできます。

ActivityHandler で定義されているハンドラーを次に示します。

Event Handler 説明
任意のアクティビティの種類を受信した OnTurnAsync 受信したアクティビティの種類に基づいて、他のハンドラーのいずれかを呼び出します。
メッセージ アクティビティを受信した OnMessageActivityAsync これをオーバーライドして message アクティビティを処理します。
会話の更新アクティビティを受信した OnConversationUpdateActivityAsync conversationUpdate アクティビティで、ボット以外のメンバーが会話に参加した場合、または会話から退出した場合にハンドラーを呼び出します。
ボットではないメンバーが会話に参加した OnMembersAddedAsync これをオーバーライドして、会話に参加するメンバーを処理します。
ボットではないメンバーが会話から退出した OnMembersRemovedAsync これをオーバーライドして、会話から退出メンバーを処理します。
イベント アクティビティを受信した OnEventActivityAsync event アクティビティで、イベントの種類に固有のハンドラーを呼び出します。
Token-response イベント アクティビティを受信した OnTokenResponseEventAsync これをオーバーライドして、トークン応答イベントを処理します。
Non-token-response イベント アクティビティを受信した OnEventAsync これをオーバーライドして、その他の種類のイベントを処理します。
メッセージの反応アクティビティを受信した OnMessageReactionActivityAsync messageReaction アクティビティで、メッセージに対して 1 つ以上の反応が追加または削除された場合にハンドラーを呼び出します。
メッセージの反応がメッセージに追加された OnReactionsAddedAsync これをオーバーライドして、メッセージに追加された反応を処理します。
メッセージの反応がメッセージから削除された OnReactionsRemovedAsync これをオーバーライドして、メッセージから削除された反応を処理します。
インストール更新アクティビティを受信しました OnInstallationUpdateActivityAsync アクティビティで installationUpdate 、ボットがインストールされたかアンインストールされたかに基づいてハンドラーを呼び出します。
ボットがインストールされた OnInstallationUpdateAddAsync これをオーバーライドして、ボットが組織単位内にインストールされたときのロジックを追加します。
ボットがアンインストールされました OnInstallationUpdateRemoveAsync これをオーバーライドして、ボットが組織単位内でアンインストールされたときのロジックを追加します。
他のアクティビティの種類を受信した OnUnrecognizedActivityTypeAsync これをオーバーライドして、他の方法では処理されない任意のアクティビティの種類を処理します。

このような各種ハンドラーにインバウンド アクティビティに関する情報を提供する turnContext があり、これはインバウンド HTTP 要求に対応しています。 アクティビティの種類もさまざまであるため、各ハンドラーが、そのターン コンテキスト パラメーターで厳密に型指定されたアクティビティを提供します。ほとんどの場合、OnMessageActivityAsync は常に処理され通常は最も一般的です。

このフレームワークの以前の 4.x バージョンと同様に、パブリック メソッド OnTurnAsyncを実装するオプションもあります。 現在、このメソッドの基本実装はエラー チェックを処理し、各受信アクティビティの種類に応じて、特定のハンドラー (たとえば、このサンプルでは定義する 2 つのハンドラー) をそれぞれ呼び出します。 ほとんどの場合、そのメソッドはそのままにして個々のハンドラーを使用できますが、状況で のカスタム実装 OnTurnAsyncが必要な場合は、まだオプションです。

重要

OnTurnAsync メソッドをオーバーライドする場合は、base.OnTurnAsync を呼び出して、他のすべての On<activity>Async ハンドラーを呼び出すための基本実装を取得するか、ご自身でこれらのハンドラーを呼び出す必要があります。 それ以外の場合、これらのハンドラーは呼び出されず、そのコードは実行されません。

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

たとえば、会話にユーザーを歓迎するために 追加されたメンバー を処理し、 メッセージを 処理してボットに送信するメッセージをエコーバックできます。

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);
            }
        }
    }
}

次のステップ

  • Microsoft Teams チャネルには、ボットが Teams と適切に連携するためにサポートする必要がある Teams 固有のアクティビティがいくつか紹介されています。 Microsoft Teams のボット開発の主要な概念を理解するには、「Microsoft Teams のボットのしくみ」を参照してください
  • アクティビティ ハンドラーは、ターン間の会話状態を追跡する必要のないボットを設計するのに適した方法です。 ダイアログ ライブラリには、ユーザーとの長時間の会話を管理する方法が用意されています。