ボットのアクティビティ ハンドラー

  • [アーティクル]

このドキュメントは、主要な Bot Framework のドキュメントの「ボットのしくみ」に基づいています。 Microsoft Teams 用に開発されたボットと主要な Bot Framework の主な違いは、Teams で提供される機能にあります。

アクティビティ ハンドラーは、ボットの会話ロジックを整理するために使用されます。 アクティビティは、Teams アクティビティ ハンドラーとボット ロジックを使用して 2 つの方法で処理されます。 Teams アクティビティ ハンドラーは、Teams 固有のイベントと相互作用のサポートを追加します。 ボット オブジェクトには、会話の推論またはターンのロジックが含まれ、ターン ハンドラーを公開します。これは、ボット アダプターからの受信アクティビティを承諾できるメソッドです。

Teams のアクティビティ ハンドラー

Teams のアクティビティ ハンドラーは、Microsoft Bot Framework のアクティビティ ハンドラーから派生したものです。 すべての Teams アクティビティをルーティングしてから、Teams 以外の特定のアクティビティを処理できるようにします。

Teams 用のボットがアクティビティを受け取ると、アクティビティ ハンドラーにルーティングされます。 すべてのアクティビティは、ターン ハンドラーと呼ばれる 1 つのベース ハンドラーを経由してルーティングされます。 ターン ハンドラーは、受信したアクティビティを管理するために必要なアクティビティ ハンドラーを呼び出します。 Teams ボットは、Bot Framework の ActivityHandler クラスから派生した TeamsActivityHandler クラスから派生したものです。

注:

ボット アクティビティの処理に 15 秒以上かかる場合、Teams はボット エンドポイントに再試行要求を送信します。 そのため、ボットに重複する要求が表示されます。

ボットは Bot Framework を使用して作成されます。 ボットがメッセージ アクティビティを受信した場合、ターン ハンドラーは受信したアクティビティの通知を受け取ります。 その後、ターン ハンドラーは受信したアクティビティを OnMessageActivityAsync アクティビティ ハンドラーに送信します。 Teams では、この機能は変わりません。 ボットが会話更新アクティビティを受信した場合、ターン ハンドラーは受信したアクティビティの通知を受け取り、受信したアクティビティを OnConversationUpdateActivityAsync に送信します。 Teams アクティビティ ハンドラーは、最初に特定の Teams イベントがないかチェックします。 イベントが見つからなかった場合、それらを Bot Framework のアクティビティ ハンドラーに渡します。

Teams アクティビティ ハンドラー クラスには、主に OnConversationUpdateActivityAsync と OnInvokeActivityAsync の 2 つの Teams アクティビティ ハンドラーがあります。 OnConversationUpdateActivityAsync はすべての会話更新アクティビティをルーティングし、OnInvokeActivityAsync は Teams によって呼び出されたすべてのアクティビティをルーティングします。

特定の Teams のアクティビティ ハンドラーのロジックを実装するには、「ボット ロジック」セクションに示すように、ボット内のメソッドをオーバーライドする必要があります。 これらのハンドラーの基本実装はありません。 したがって、オーバーライドに必要なロジックを追加します。

Teams のアクティビティ ハンドラーのコード スニペット:

OnTeamsChannelCreatedAsync


protected override Task OnTeamsChannelCreatedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
        {
            // Code logic here
        }

OnTeamsChannelDeletedAsync


protected override Task OnTeamsChannelDeletedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
        {
            // Code logic here
        }

OnTeamsChannelRenamedAsync


protected override Task OnTeamsChannelRenamedAsync(ChannelInfo channelInfo, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
  {
   // Code logic here
  }

OnTeamsTeamRenamedAsync


protected override Task OnTeamsTeamRenamedAsync(TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
  {
   // Code logic here
  }

OnTeamsMembersAddedAsync


protected override Task OnTeamsMembersAddedAsync(IList<TeamsChannelAccount> teamsMembersAdded, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
  {
   // Code logic here
  }

OnTeamsMembersRemovedAsync


protected override Task OnTeamsMembersRemovedAsync(IList<TeamsChannelAccount> teamsMembersRemoved, TeamInfo teamInfo, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken);
  {
   // Code logic here
  }

OnTeamsMessageEditAsync

protected override async Task OnTeamsMessageEditAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken)
  { 
   // Code logic here 
  }

OnTeamsMessageUndeleteAsync

protected override async Task OnTeamsMessageUndeleteAsync(ITurnContext<IMessageUpdateActivity> turnContext, CancellationToken cancellationToken)
  { 
   // Code logic here 
  }

OnTeamsMessageSoftDeleteAsync

 protected override async Task OnTeamsMessageSoftDeleteAsync(ITurnContext<IMessageDeleteActivity> turnContext, CancellationToken cancellationToken)
  { 
   // Code logic here 
  }

ボット ロジック

ボット ロジックは、1 つ以上のボット チャネルから受信したアクティビティを処理し、それに応じて送信アクティビティを生成します。 これは、Teams アクティビティ ハンドラー クラスから派生したボットに当てはまります。これは、最初に Teams アクティビティをチェックします。 Teams アクティビティがないか確認したら、他のすべてのアクティビティが Bot Framework のアクティビティ ハンドラーに渡されます。

主要な Bot Framework ハンドラー

注:

  • 追加および削除されたメンバーのアクティビティを除き、このセクションで説明するすべてのアクティビティ ハンドラーは Teams 以外のボットと同様に動作し続けます。
  • onInstallationUpdateActivityAsync() メソッドは、ボットを Teams に追加するときに Teams ロケールを取得するために使用されます。

アクティビティ ハンドラーは、メッセージ スレッドの代わりに新しいメンバーがチームに追加されるチームのコンテキストで異なります。

で ActivityHandler 定義されているハンドラーの一覧には、次のイベントが含まれます。

イベント ハンドラー 説明
任意のアクティビティの種類を受信しました OnTurnAsync このメソッドは、受信したアクティビティの種類に基づいて、他のハンドラーのいずれかを呼び出します。
メッセージ アクティビティを受信しました OnMessageActivityAsync このメソッドをオーバーライドしてアクティビティを Message 処理できます。
受信したメッセージ更新アクティビティ OnMessageUpdateActivityAsync このメソッドをオーバーライドして、メッセージ更新アクティビティを処理できます。
受信したメッセージ削除アクティビティ OnMessageDeleteActivityAsync このメソッドをオーバーライドして、メッセージ削除アクティビティを処理できます。
会話更新アクティビティを受信しました OnConversationUpdateActivityAsync このメソッドは、ConversationUpdate アクティビティで、ボット以外のメンバーが会話に参加または退出した場合にハンドラーを呼び出します。
ボット以外のメンバーが会話に参加しました OnMembersAddedAsync このメソッドは、会話に参加するメンバーを処理するためにオーバーライドできます。
ボット以外のメンバーが会話を退出しました OnMembersRemovedAsync このメソッドは、会話を退出するメンバーを処理するためにオーバーライドできます。
イベント アクティビティを受信しました OnEventActivityAsync このメソッドは、Event アクティビティで、イベントの種類に固有のハンドラーを呼び出します。
トークン応答イベント アクティビティを受信しました OnTokenResponseEventAsync このメソッドは、トークン応答イベントを処理するためにオーバーライドできます。
トークン応答以外のイベント アクティビティを受信しました OnEventAsync このメソッドは、他の種類のイベントを処理するためにオーバーライドできます。
その他のアクティビティの種類を受信しました OnUnrecognizedActivityTypeAsync このメソッドは、それ以外の場合は処理されないアクティビティの種類を処理するためにオーバーライドできます。

Teams に固有のアクティビティ ハンドラー

では TeamsActivityHandler 、コア Bot Framework ハンドラー セクションのハンドラーの一覧が拡張され、次のイベントが含まれます。

イベント ハンドラー 説明
channelCreated OnTeamsChannelCreatedAsync このメソッドは、作成される Teams チャネルを処理するためにオーバーライドできます。 詳細については、「会話更新イベントで作成されたチャネル」を参照してください。
channelDeleted OnTeamsChannelDeletedAsync このメソッドは、削除される Teams チャネルを処理するためにオーバーライドできます。 詳細については、「会話更新イベントで削除されたチャネル」を参照してください。
channelRenamed OnTeamsChannelRenamedAsync このメソッドは、名前が変更される Teams チャネルを処理するためにオーバーライドできます。 詳細については、「会話更新イベントでチャネルの名前が変更されました」を参照してください。
teamRenamed OnTeamsTeamRenamedAsync return Task.CompletedTask; このメソッドは、名前が変更される Teams チームを処理するためにオーバーライドできます。 詳細については、「会話の更新イベントでチーム名が変更されました」を参照してください。
MembersAdded OnTeamsMembersAddedAsync このメソッドは ActivityHandler の OnMembersAddedAsync メソッドを呼び出します。 このメソッドは、チームに参加するメンバーを処理するためにオーバーライドできます。 詳細については、会話更新イベントに追加されたチーム メンバーに関するページを参照してください。
MembersRemoved OnTeamsMembersRemovedAsync このメソッドは ActivityHandler の OnMembersRemovedAsync メソッドを呼び出します。 このメソッドは、チームを離れるメンバーを処理するためにオーバーライドできます。 詳細については、会話更新イベントで削除されたチーム メンバーに関するページを参照してください。
messageEdit OnTeamsMessageEditAsync このメソッドをオーバーライドして、Teams メッセージ編集イベントを処理できます。
messageUndelete OnTeamsMessageUndeleteAsync このメソッドをオーバーライドして、Teams メッセージの削除を取り消すイベントを処理できます。
messageSoftDelete OnTeamsMessageSoftDeleteAsync このメソッドをオーバーライドして、Teams メッセージの論理的な削除イベントを処理できます。

Teams の呼び出しアクティビティ

Teams アクティビティ ハンドラーから呼び出される Teams アクティビティ ハンドラーの OnInvokeActivityAsync 一覧には、次の呼び出しの種類が含まれています。

呼び出しの種類 ハンドラー 説明
CardAction.Invoke OnTeamsCardActionInvokeAsync コネクタがカード アクション呼び出しアクティビティを受け取ると、このメソッドが呼び出されます。
fileConsent/invoke OnTeamsFileConsentAcceptAsync ユーザーがファイル同意カード受け入れると、このメソッドが呼び出されます。
fileConsent/invoke OnTeamsFileConsentAsync コネクタがアクティビティカードファイルの同意を受け取ると、このメソッドが呼び出されます。
fileConsent/invoke OnTeamsFileConsentDeclineAsync ユーザーがカードファイルの同意を拒否すると、このメソッドが呼び出されます。
actionableMessage/executeAction OnTeamsO365ConnectorCardActionAsync コネクタがアクション アクティビティのコネクタ カードMicrosoft 365 グループ受け取ると、このメソッドが呼び出されます。
signin/verifyState OnTeamsSigninVerifyStateAsync コネクタが検証状態アクティビティを signIn 受け取ると、このメソッドが呼び出されます。
task/fetch OnTeamsTaskModuleFetchAsync ダイアログ (TeamsJS v1.x のタスク モジュールと呼ばれます) がフェッチされたときにロジックを提供するには、派生クラスでこのメソッドをオーバーライドできます。
task/submit OnTeamsTaskModuleSubmitAsync ダイアログが送信されたときにロジックを提供するために、派生クラスでこのメソッドをオーバーライドできます。

このセクションに記載されている Invoke アクティビティは、Teams の会話ボット用です。 Bot Framework SDK は、メッセージ拡張機能に固有の呼び出しアクティビティもサポートしています。 詳細については、「メッセージ拡張機能とは」を参照してください。

ボット アクティビティ ハンドラーについて理解したので、会話と、ボットが受信または送信するメッセージに応じてボットがどのように動作するかを確認しましょう。

コード サンプル

サンプルの名前 説明 .NET Node.js Python
Teams 会話ボット このサンプル アプリでは、Bot Framework v4 で使用できるさまざまなボット会話イベントを使用する方法を示します。 表示 表示 表示
ボット サンプル Bot Framework v4 サンプルのセット。 表示 表示 表示

次の手順

会話の基本

関連項目