使用活動處理程式的事件驅動交談

適用於： SDK v4

活動處理程式是組織 Bot 交談邏輯的事件驅動方式。 活動的每個不同類型或子類型都代表不同類型的交談事件。 實際上，Bot 的 回合處理程式 會針對所接收的任何活動類型呼叫個別活動處理程式。

例如，如果 Bot 收到訊息活動，回合處理程式就會看到傳入活動，並將它傳送至 訊息活動 活動處理程式。 當您建置 Bot 時，處理和回應訊息的 Bot 邏輯將會放在此訊息活動處理程式中。 同樣地，您用來處理成員加入至交談的邏輯，將會在 加入成員 的處理程式中執行，每當成員加入至交談時，就會呼叫該處理程式。

如需組織 Bot 邏輯的其他方式，請參閱 Bot 運作方式中的 Bot 邏輯一節。

注意

Bot Framework JavaScript、C# 和 Python SDK 將會繼續受到支援，不過，Java SDK 即將淘汰，最終長期支援將於 2023 年 11 月結束。

使用 Java SDK 建置的現有 Bot 將繼續運作。

針對新的 Bot 建置，請考慮使用 Microsoft Copilot Studio ，並閱讀 選擇正確的 Copilot 解決方案。

如需詳細資訊，請參閱 Bot 建置的未來。

C#

若要實作這些處理程式的邏輯，您會在 Bot 中覆寫這些方法，例如下面的 範例活動處理程式 一節。 針對每個處理程式，沒有基底實作，因此只要在覆寫中新增您想要的邏輯即可。

在某些情況下，您會想要覆寫基底回合處理程式，例如 在回合結束時儲存狀態 。 這樣做時，請務必先呼叫 await base.OnTurnAsync(turnContext, cancellationToken); ，確定的基底實作 OnTurnAsync 會在您的其他程式碼之前執行。 該基底實作除了其他責任外，還負責呼叫其他活動處理程式，例如 OnMessageActivityAsync。

JavaScript

JavaScript ActivityHandler 使用事件發射器和監聽器模式。 例如，使用 onMessage 方法來註冊訊息活動的事件監聽器。 您可以註冊多個監聽器。 當 Bot 收到訊息活動時，活動處理程式會注意到該傳入的活動，並按照註冊的順序將其發送給每個 onMessage 活動監聽器。

建置您的機器人時，處理和回應訊息的邏輯將被放置在onMessage接聽器中。 同樣地，處理要新增至交談之成員的邏輯將會出現在您的 onMembersAdded 監聽器中，每當成員新增至交談時，就會呼叫該監聽器。 若要新增這些監聽器，您會在 Bot 中註冊它們，如下列 Bot 邏輯 一節所示。 針對每個監聽器，請包含 Bot 邏輯，然後請務必在結尾呼叫next()。 藉由呼叫 next()，您可以確定下一個接聽程式正在執行。

請務必在 回合結束前儲存狀態 。 您可以覆寫活動處理常式 run 方法，待父方法 run 完成後儲存狀態來執行此動作。

一般來說，您不會想要覆寫基底回合處理程式，所以如果您嘗試這樣做，請務必小心。 有一個名為 onDialog 的特殊處理程式。 處理程式 onDialog 會在結尾執行，在其餘處理程式執行之後執行，而且不會系結至特定活動類型。 如同上述所有處理程式，請務必呼叫 next() 以確保其餘的進程會結束。

Java

若要為這些處理程式實作邏輯，您需要在您的 Bot 中覆寫這些方法，例如在下面的 活動範例處理程式 一節中。 這些處理程式沒有基底實作，因此請在覆寫中新增您想要的邏輯。

在某些情況下，您會想要覆寫基底回合處理程式，例如 在回合結束時儲存狀態 。 這樣做時，請務必先呼叫 super.onTurn(turnContext);，以確保在您的額外程式碼之前先執行 onTurn 的基底實作。 該基底實作除了其他功能之外，還負責呼叫其他活動處理程式，例如 onMessageActivity。

Python

當您建置 Bot 時，Bot 的邏輯會在此處理程序 on_message_activity 中負責處理和回應訊息。 同樣地，處理要新增至交談之成員的邏輯將會進入您的 on_members_added 處理程式，每當成員新增至交談時，就會呼叫該處理程式。

例如，如果 Bot 收到訊息活動，回合處理程式就會看到該傳入活動，並將它傳送至 on_message_activity 活動處理程式。

若要實作這些處理程序的邏輯，您會在 bot 中覆寫這些方法，例如在下面的 範例活動處理程式 一節中。 針對每個處理程式，沒有基底實作，因此只要在覆寫中新增您想要的邏輯即可。

在某些情況下，您會想要覆寫基底回合處理程式，例如 在回合結束時儲存狀態 。 這樣做時，請務必先呼叫 await super().on_turn(turnContext); ，確定的基底實作 on_turn 會在您的其他程式碼之前執行。 該基底實作除了承擔其他職責外，還負責呼叫其他活動處理程式，例如 on_message_activity。

活動處理

Bot 邏輯會處理來自一或多個通道的連入活動，併產生傳出活動以回應。

C#

主要 Bot 邏輯定義於 Bot 程式代碼中。 若要實作 Bot 作為活動處理程式，請從 ActivityHandler衍生 Bot 類別，以實作 IBot 介面。 ActivityHandler 針對不同類型的活動定義各種處理程式，例如 OnMessageActivityAsync、 和 OnMembersAddedAsync。 這些方法受到保護，但可以覆寫，因為我們衍生自 ActivityHandler。

中 ActivityHandler 定義的處理程式如下：

活動	處理器	描述
收到的任何活動類型	OnTurnAsync	根據收到的活動類型，呼叫其他處理程式之一。
已接收的訊息活動	OnMessageActivityAsync	覆寫此項目以處理 message 活動。
已收到對話更新活動	OnConversationUpdateActivityAsync	conversationUpdate在活動中，如果成員（非 Bot）加入或離開交談，則會呼叫處理程式。
非 Bot 成員已加入交談	OnMembersAddedAsync	覆寫此項目以處理加入交談的成員。
非 Bot 成員離開交談	OnMembersRemovedAsync	要覆蓋此功能以處理成員退出交談。
已接收的事件活動	OnEventActivityAsync	在event活動中，呼叫與事件類型相關的處理程式。
已接收令牌回應事件活動	OnTokenResponseEventAsync	覆寫這個函式以處理令牌回應事件。
收到不涉及令牌的回應事件	OnEventAsync	覆寫此選項以處理其他類型的事件。
已接收訊息反應動作	OnMessageReactionActivityAsync	在messageReaction活動中，當訊息中的一個或多個回應被新增或移除時，則呼叫處理程式。
新增至訊息的訊息反應	OnReactionsAddedAsync	覆寫此選項以處理新增至訊息的回應。
訊息回應已從該訊息中移除	OnReactionsRemovedAsync	覆寫此選項以處理從訊息中移除的反應。
收到安裝更新事件通知	OnInstallationUpdateActivityAsync	在installationUpdate活動中，根據 Bot 的安裝或卸載狀態，調用處理程序。
已安裝機器人	OnInstallationUpdateAddAsync	覆蓋此設定，以便在將 Bot 安裝到組織單位時新增邏輯。
已卸載 Bot	OnInstallationUpdateRemoveAsync	覆寫此選項，以在組織單位內卸載 Bot 時新增邏輯。
收到的其他活動類型	OnUnrecognizedActivityTypeAsync	覆寫此選項以處理任何未處理的活動類型。

這些不同的處理程式具有 turnContext ，提供傳入活動的相關資訊，其對應至輸入 HTTP 請求。 活動可以是各種類型，因此每個處理程序都會在其上下文參數中提供強類型的活動；在大部分情況下，OnMessageActivityAsync 都會被處理，而且通常是最常見的。

如同此框架的過去 4.x 版本一樣，也有可以實作公用方法 OnTurnAsync 的選項。 目前，此方法的基底實作會處理錯誤檢查，然後根據傳入活動的類型呼叫每個特定處理程式（例如我們在此範例中定義的兩個處理程式）。 在大部分情況下，您可以保持該方法不變，並使用各自的處理器，但如果您的情況需要自訂的 OnTurnAsync 實作，這仍然是個選擇。

重要

如果您覆寫 OnTurnAsync 方法，您必須呼叫 base.OnTurnAsync 以取得基礎實作來呼叫所有其他 On<activity>Async 處理程式，或自行呼叫這些處理程式。 否則，不會呼叫這些處理程式，而且不會執行該程序代碼。

JavaScript

主要 Bot 邏輯定義於 Bot 程式代碼中。 若要將 Bot 實作為活動處理程式，請擴充 ActivityHandler。 ActivityHandler 針對不同類型的活動定義各種事件，您可以註冊事件接聽程式來修改 Bot 的行為，例如 使用 onMessage 和 onConversationUpdate。

使用這些方法來註冊每類型事件的監聽器：

活動	註冊方法	描述
任何收到的活動類型	onTurn	在收到任何活動時註冊接聽程式。
已接收的訊息活動	onMessage	註冊一個監聽器以便在收到 message 活動時使用。
已接收交談更新活動	onConversationUpdate	註冊一個監聽器，以在收到任何 conversationUpdate 活動時使用。
成員加入了對話	onMembersAdded	註冊一個監聽器，以便在成員（包括機械人）加入對話時觸發。
成員離開對話	onMembersRemoved	註冊一個監聽器，用於當成員（包括 Bot）離開交談時。
已接收訊息反應活動	onMessageReaction	註冊一個監聽器以接收任何 messageReaction 活動。
新增至訊息的訊息反應	onReactionsAdded	註冊一個監聽器，以監測何時有反應新增到訊息中。
訊息回應已從訊息中移除	onReactionsRemoved	註冊一個事件監聽器，用於監控從訊息中移除反應的情況。
已接收的事件活動	onEvent	當收到任何 event 活動時註冊監聽器。
已接收令牌回應的事件活動	onTokenResponseEvent	註冊一個接聽程式以在收到 tokens/response 事件時啟用。
已接收安裝更新活動	onInstallationUpdate	當接收到任何 installationUpdate 活動時註冊監聽器。
機器人已安裝	onInstallationUpdateAdd	註冊監聽器，以便在組織單位中安裝 Bot 時使用。
已卸載 Bot	onInstallationUpdateRemove	在組織單位內卸載 Bot 時，註冊的接聽程式。
收到的其他活動類型	onUnrecognizedActivityType	註冊接聽程式，以備在未定義特定類型活動的處理程式時使用。
活動處理程式已完成	onDialog	在所有相關的處理程式完成後進行呼叫。

next從每個處理程式呼叫接續函式，以允許繼續處理。 如果未調用next，則活動處理會結束。

Java

主要 Bot 邏輯定義於 Bot 程式代碼中。 若要實作 Bot 作為活動處理程式，請從 ActivityHandler衍生 Bot 類別，以實作 Bot 介面。 ActivityHandler 針對不同類型的活動定義各種處理程式，例如 onMessageActivity、 和 onMembersAdded。 這些方法受到保護，但由於我們是從 ActivityHandler 衍生而來，因此可以覆寫。

中 ActivityHandler 定義的處理程式如下：

活動	處理器	描述
收到的任何活動類型	onTurn	根據收到的活動類型，呼叫其他處理程式之一。
已接收的訊息活動	onMessageActivity	覆寫此方法以處理 message 活動。
已收到交談更新活動	onConversationUpdateActivity	當有成員（除 Bot 外）加入或離開對話時，在conversationUpdate活動中會呼叫處理程式。
非 Bot 成員已加入交談	onMembersAdded	覆寫此項目以處理加入交談的成員。
非 Bot 成員離開交談	onMembersRemoved	覆寫此選項以處理離開交談的成員。
已接收的事件活動	onEventActivity	在event活動中，呼叫特定於事件類型的處理程式。
接收到令牌回應的事件活動	onTokenResponseEvent	覆寫此項目以處理 Token 回應事件。
收到非令牌回應事件活動	onEvent	覆寫此選項以處理其他類型的事件。
已收到訊息的回應活動	onMessageReactionActivity	messageReaction在某個活動上，如果訊息中的一個或多個回應已被新增或移除，則呼叫處理程式。
新增至訊息的訊息反應	onReactionsAdded	覆寫此選項以處理新增至訊息的回應。
訊息回應已從訊息中刪除	onReactionsRemoved	覆寫此處以處理從訊息中移除的回應。
接收到安裝更新通知	onInstallationUpdate	installationUpdate在活動上，根據 Bot 是否已安裝或卸載，呼叫處理程式。
已安裝機器人	onInstallationUpdateAdd	覆寫該選項，以便在將機器人安裝到某個組織單位時新增邏輯。
已卸載 Bot	onInstallationUpdateRemove	覆寫此選項，以在組織單位內卸載 Bot 時新增邏輯。
收到的其他活動類型	onUnrecognizedActivityType	覆寫此選項以處理任何未處理的活動類型。

這些不同的處理程式具有 turnContext ，提供有關傳入動作的相關信息，其對應至輸入的 HTTP 請求。 活動可以有多種不同的類型，因此每個處理程式會在其回合上下文參數中提供一個具體型別的活動;在大多數情況下，onMessageActivity 都會被處理，這通常是最為普遍的。

另外還有一個選項可以實作公用方法 onTurn。 目前，此方法的基底實作會處理錯誤檢查，然後根據傳入活動的類型呼叫每個特定處理程式（例如我們在此範例中定義的兩個處理程式）。 在大部分情況下，您可以不動用該方法，而是使用個別處理程式，但如果您的情況需要的自訂實作 onTurn，它仍然是一個選項。

重要

如果您覆寫 onTurn 方法，您必須呼叫 super.onTurn 以取得基礎實作，以便呼叫所有其他 on<activity> 處理程式，或您可以自行呼叫這些處理程式。 否則，不會呼叫這些處理程式，而且不會執行該程序代碼。

Python

主要 Bot 邏輯定義於 Bot 程式代碼中。 若要實作 Bot 作為活動處理程式，請從 ActivityHandler衍生 Bot 類別，而該類別又衍生自抽象 Bot 類。 ActivityHandler 針對不同類型的活動定義各種處理程式，例如 on_message_activity 和 on_members_added。 這些方法受到保護，但可以覆寫，因為我們衍生自 ActivityHandler。

中 ActivityHandler 定義的處理程式如下：

活動	處理器	描述
任何收到的活動類型	on_turn	根據收到的活動類型，呼叫其他處理程式之一。
已接收的訊息活動	on_message_activity	覆寫此項目以處理 message 活動。
已接收對話更新活動	on_conversation_update_activity	在活動期間，如果有成員（而非bot）加入或離開對話，則會呼叫處理程式。
非 Bot 成員已加入交談	on_members_added_activity	覆寫此項目以處理成員們加入對話。
非 Bot 成員離開交談	on_members_removed_activity	覆寫此選項以處理離開交談的成員。
已接收的事件活動	on_event_activity	在特定活動中，呼叫與事件類型對應的處理程式。
已收到令牌回應事件活動	on_token_response_event	覆寫此項目以處理令牌回應事件。
收到非Token回應的事件活動	on_event_activity	覆寫此選項以處理其他類型的事件。
已接收訊息反應活動	on_message_reaction_activity	在一個活動中，如果訊息中有一個或多個反應被添加或移除，則呼叫處理程式。
訊息反應已被新增到訊息中	on_reactions_added	覆寫此選項以處理新增至訊息的反應。
訊息回應已從訊息中移除	on_reactions_removed	覆寫此選項以處理從訊息中移除的反應。
接收到安裝更新作業	on_installation_update	在活動installationUpdate上，根據 Bot 是否已安裝或被卸載，呼叫相應的處理程式。
已安裝機器人	on_installation_update_add	覆寫此設定，以在將 Bot 安裝在組織單位時新增邏輯。
已卸載 Bot	on_installation_update_remove	覆寫此選項，以在組織單位內卸載 Bot 時新增邏輯。
收到的其他活動類型	on_unrecognized_activity_type	覆寫此指令以處理任何未處理的活動類型。

這些不同的處理程式具有 turn_context ，提供傳入活動的相關信息，其對應至輸入 HTTP 要求。 活動可以是各種類型，因此每個處理程式都會在其回合內容參數中提供強類型的活動，在大部分情況下，on_message_activity 一律會被處理，而且通常是最常見的。

如同此框架先前的 4.x 版本，這裡也可以選擇實作公用方法 on_turn。 目前，此方法的基底實作會處理錯誤檢查，然後根據傳入活動的類型呼叫每個特定處理程式（例如我們在此範例中定義的兩個處理程式）。 在大多數情況下，您可以不改變該方法並使用個別處理程式，但如果您的情況需要自定義的 on_turn 實作，仍然可以選擇如此做。

重要

如果您覆寫 on_turn 方法，您必須呼叫 super().on_turn 以取得基底實作，以呼叫所有其他 on_<activity> 處理程式或自行呼叫這些處理程式。 否則，不會呼叫這些處理程式，而且不會執行該程序代碼。

範例活動處理程式

例如，您可以處理當成員被新增時以歡迎使用者進入交談，並處理訊息以回應他們傳送給機器人的訊息。

C#

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

JavaScript

class EchoBot extends ActivityHandler {
    constructor() {
        super();
        // See https://aka.ms/about-bot-activity-message to learn more about the message and other activity types.
        this.onMessage(async (context, next) => {
            const replyText = `Echo: ${ context.activity.text }`;
            await context.sendActivity(MessageFactory.text(replyText, replyText));
            // By calling next() you ensure that the next BotHandler is run.
            await next();
        });

        this.onMembersAdded(async (context, next) => {
            const membersAdded = context.activity.membersAdded;
            const welcomeText = 'Hello and welcome!';
            for (let cnt = 0; cnt < membersAdded.length; ++cnt) {
                if (membersAdded[cnt].id !== context.activity.recipient.id) {
                    await context.sendActivity(MessageFactory.text(welcomeText, welcomeText));
                }
            }
            // By calling next() you ensure that the next BotHandler is run.
            await next();
        });
    }
}

Java

警告

您要尋找的範例看起來已經移動！ 放心，我們正在努力解決這個問題。

Python

class EchoBot(ActivityHandler):
    async def on_members_added_activity(
        self, members_added: [ChannelAccount], turn_context: TurnContext
    ):
        for member in members_added:
            if member.id != turn_context.activity.recipient.id:
                await turn_context.send_activity("Hello and welcome!")

    async def on_message_activity(self, turn_context: TurnContext):
        return await turn_context.send_activity(
            MessageFactory.text(f"Echo: {turn_context.activity.text}")
        )

下一步

• Microsoft Teams 頻道引進一些 Teams 特定活動，您的 Bot 必須支援才能與 Teams 正常運作。 若要了解開發 Microsoft Teams Bot 的重要概念，請參閱 Microsoft Teams Bot 的運作方式
• 活動處理程式是設計不需要追蹤回合之間對話狀態的 Bot 的好方法。 對話庫提供方式來管理與用戶的持續對話。