Microsoft Teams のボットのしくみ

この記事の対象: SDK v4

この記事は、ボットのしくみイベントドリブンの会話で学習した内容に基づいています。続行する前に、これらの記事をよく理解しておく必要があります。

Microsoft Teams 向けに開発されたボットの主な違いは、アクティビティの処理方法です。 Teams アクティビティ ハンドラーは、アクティビティ ハンドラーから派生したもので、より一般的なアクティビティの種類を処理する前に、Teams 固有のアクティビティの種類を処理します。

Note

Bot Framework JavaScript SDK、C#、Python SDK は引き続きサポートされますが、Java SDK については、最終的な長期サポートは 2023 年 11 月に終了する予定です。 このリポジトリ内の重要なセキュリティとバグの修正のみが行われます。

Java SDK を使用して構築された既存のボットは引き続き機能します。

新しいボットの構築については、Power Virtual Agents の使用を検討し、適切なチャットボット ソリューションの選択についてお読みください。

詳細については、「The future of bot building」をご覧ください。

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

Teams 用のボットを作成するには、Teams アクティビティ ハンドラークラスからボットを派生させます。 このようなボットは、アクティビティを受信すると、さまざまな アクティビティ ハンドラーを介してアクティビティをルーティングします。 最初の基本ハンドラーは ターン ハンドラーであり、アクティビティの種類に基づいてアクティビティをハンドラーにルーティングします。 ターン ハンドラーは、受信した特定の種類のアクティビティを処理するように設計されたハンドラーを呼び出します。 Teams アクティビティ ハンドラー クラスは、アクティビティ ハンドラー クラスから派生します。 アクティビティ ハンドラーが処理できるアクティビティの種類に加えて、Teams アクティビティ ハンドラー クラスには、Teams 固有のアクティビティの追加ハンドラーも含まれています。

Teams アクティビティ ハンドラーから派生するボットは、アクティビティ ハンドラー クラスから直接派生するボットに似ています。 ただし、Teams はconversationUpdateアクティビティに追加情報を含め、Teams 固有のinvokeおよびeventアクティビティを送信します。

Teams アクティビティ ハンドラーボットがメッセージ アクティビティを受信すると、そのターン ハンドラーは、アクティビティ ハンドラーベースのボットと同様に、受信メッセージ アクティビティをOnMessageActivityAsyncハンドラーにルーティングします。 ただし、Teams ボットが会話更新アクティビティを受信すると、Teams バージョンのOnConversationUpdateActivityAsyncハンドラーによって、このアクティビティが処理されます。

この Teams 固有のアクティビティ ハンドラーのほとんどには、基本実装がありません。 これらのハンドラーをオーバーライドし、適切なロジックをボットに提供する必要があります。

アクティビティ ハンドラを使用したイベント ドリブンの会話に関する記事の「アクティビティの処理」セクションに記載されているすべてのアクティビティ ハンドラーは、追加されたメンバーと削除されたアクティビティの処理を除き、Teams 以外のボットと同様に機能します。これらのアクティビティはチームという点で異なり、新しいメンバーは、メッセージ スレッドではなくチームに追加されます。 詳細については、「Teams の会話更新アクティビティ」を参照してください。

これらの Teams 固有のアクティビティ ハンドラーのロジックを実装するには、メソッドをボット内でオーバーライドします。

Teams ボット ロジック

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

Teams のインストール更新アクティビティ

インストール更新イベントのハンドラーを追加して、ボットに許可します。

  • 会話スレッドにインストールされている場合は、紹介メッセージを送信します。
  • スレッドからアンインストールされたときに、ユーザーとスレッドのデータをクリーンアップします。

詳細については、Teams ドキュメントのインストール更新イベント を参照してください。

Teams の会話更新アクティビティ

次の表は、ボットで会話更新アクティビティを生成する Teams イベントの一覧です。 会話更新イベントに関する記事では、ボットでこれらのイベントを使用する方法について説明します。

次に示すのは、OnConversationUpdateActivityAsyncTeams アクティビティ ハンドラーのメソッドから呼び出されたすべての Teams アクティビティ ハンドラーの一覧です。

EventType ハンドラー 条件 Teams のドキュメント
channelCreated OnTeamsChannelCreatedAsync ボットがインストールされているチームで新しいチャンネルが作成されるたびに送信されます。 チャンネルが作成されました
channelDeleted OnTeamsChannelDeletedAsync ボットがインストールされているチームでチャンネルが削除されるたびに送信されます。 チャンネルが削除されました
channelRenamed OnTeamsChannelRenamedAsync ボットがインストールされているチームでチャンネルの名前が変更されるたびに送信されます。 チャンネルの名前が変更されました
channelRestored OnTeamsChannelRestoredAsync 以前に削除されたチャンネルが、ボットが既にインストールされているチームに復元されるたびに送信されます。 チャンネルが復元されました
membersAdded OnTeamsMembersAddedAsync 既定では、ActivityHandler.OnMembersAddedAsyncメソッドを呼び出します。 ボットが会話に初めて追加されるとき、およびボットがインストールされているチームまたはグループ チャットに新しいユーザーが追加されるたびに送信されます。 チーム メンバーが追加されました
membersRemoved OnTeamsMembersRemovedAsync 既定では、ActivityHandler.OnMembersRemovedAsyncメソッドを呼び出します。 ボットがチームから削除され、ボットがメンバーになっているチームからユーザーが削除されるたびに送信されます。 チーム メンバーが削除されました
teamArchived OnTeamsTeamArchivedAsync ボットがインストールされているチームがアーカイブされたときに送信されます。 チームがアーカイブされました
teamDeleted OnTeamsTeamDeletedAsync ボットが参加しているチームが削除されたときに送信されます。 チームが削除されました
teamRenamed OnTeamsTeamRenamedAsync ボットが参加しているチームの名前が変更されたときに送信されます。 チームの名前が変更されました
teamRestored OnTeamsTeamRestoredAsync 参加しているボットが既に削除されたチームが復元されたときに送信されます。 チームが復元されました
teamUnarchived OnTeamsTeamUnarchivedAsync ボットがインストールされているチームがアーカイブされていないときに送信されます。 チームがアーカイブ解除されました

Teams イベント アクティビティ

次の表は、Teams がボットに送信する Teams 固有のイベント アクティビティの一覧です。 上記のイベント アクティビティは、Teams の会話ボット用です。

これらは、OnEventActivityAsyncTeamsアクティビティ ハンドラーから呼び出される Teams 固有のイベント アクティビティ ハンドラーです。

イベントの種類 ハンドラー 説明
application/vnd.microsoft.meetingEnd OnTeamsMeetingEndAsync ボットは、終了直後の会議に関連付けられています。
application/vnd.microsoft.meetingStart OnTeamsMeetingStartAsync ボットは、開始直後の会議に関連付けられています。

チームが呼び出したアクティビティ

次の表は、Teams がボットに送信する Teams 固有の呼び出しアクティビティの一覧です。 上記の呼び出しアクティビティは、Teams の会話ボット用です。 また、Bot Framework SDK もメッセージングの拡張機能固有の呼び出しをサポートします。 詳細については、Teams の「メッセージングの拡張機能とは」の記事を参照してください。

Note

Microsoft Teams プラットフォームのドキュメントと Teams JavaScript クライアント ライブラリ (TeamsJS) は、タスク モジュールをモーダル ダイアログとして参照します。 詳細については、ダイアログを参照してください。

次に示すのは、OnInvokeActivityAsyncTeams アクティビティ ハンドラーから呼び出されたすべての Teams アクティビティ ハンドラーの一覧です。

呼び出しの種類 ハンドラー 説明
actionableMessage/executeAction OnTeamsO365ConnectorCardActionAsync Teams O365 コネクタ カード アクションです。
CardAction.Invoke OnTeamsCardActionInvokeAsync Teams のカード アクションの呼び出しです。
fileConsent/invoke OnTeamsFileConsentAcceptAsync Teams のファイルの同意の許可です。
fileConsent/invoke OnTeamsFileConsentAsync Teams のファイルの同意です。
fileConsent/invoke OnTeamsFileConsentDeclineAsync Teams のファイルの同意です。
signin/verifyState OnTeamsSigninVerifyStateAsync Teams のサインイン確認の状態です。
task/fetch OnTeamsTaskModuleFetchAsync Teams のタスク モジュールのフェッチです。
task/submit OnTeamsTaskModuleSubmitAsync Teams のタスク モジュールの送信です。

次のステップ

Teams のボットをビルドするには、Microsoft Teams 開発者ドキュメントを参照してください。