Microsoft Teams のボットのしくみ

適用対象: SDK v4

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

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

Note

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

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

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 イベントの一覧です。 Microsoft Teams 会話の更新イベント に関する記事では、これらの各イベントの使用方法について説明します。

以下は、Teams アクティビティ ハンドラーの メソッドから OnConversationUpdateActivityAsync 呼び出されるすべての Teams アクティビティ ハンドラーの一覧です。

EventType Handler 条件 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 の会話ボット用です。

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

イベントの種類 Handler 説明
application/vnd.microsoft.meetingEnd OnTeamsMeetingEndAsync ボットは、終了したばかりの会議に関連付けられています。
application/vnd.microsoft.meetingStart OnTeamsMeetingStartAsync ボットは、開始したばかりの会議に関連付けられています。

Teams でアクティビティを呼び出す

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

Teams アクティビティ ハンドラーから呼び出されるすべての Teams アクティビティ ハンドラーの一覧を次OnInvokeActivityAsync示します。

呼び出しの種類 Handler 説明
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 開発者ドキュメントを参照してください。