Беседы на основе событий с помощью обработчика действий

ОБЛАСТЬ ПРИМЕНЕНИЯ: ПАКЕТ SDK версии 4

Обработчик действий — это управляемый событиями способ упорядочить логику общения для бота. Каждый тип или подтип действия представляет собой другой тип события беседы. Под обложкой обработчик поворота бота вызывает отдельный обработчик действий для любого типа полученного действия.

Например, если бот получает действие сообщения, обработчик поворота увидит, что входящее действие и отправит его в обработчик действий сообщения . При создании бота логика бота для обработки и реагирования на сообщения будет выполняться в этом обработчике действий сообщений. Аналогичным образом логика обработки элементов, добавляемых в беседу, будет выполняться в добавленном обработчике участников, который вызывается при добавлении члена в беседу.

Другие способы упорядочивания логики бота см. в разделе логики бота в том, как работают боты.

Примечание.

Пакеты SDK для JavaScript, C# и Python для Bot Framework по-прежнему будут поддерживаться, однако пакет SDK java отменяется с окончательной долгосрочной поддержкой, заканчивающейся в ноябре 2023 года. В этом репозитории будут выполняться только критически важные исправления безопасности и ошибок.

Существующие боты, созданные с помощью пакета SDK для Java, будут продолжать функционировать.

Для создания нового бота рекомендуется использовать Power Virtual Agent и ознакомиться с выбором подходящего решения чат-бота.

Дополнительные сведения см. в статье "Будущее создания бота".

C#

Чтобы реализовать логику для этих обработчиков, вы переопределите эти методы в боте, например в разделе обработчика действий примера ниже. Для каждого из этих обработчиков нет базовой реализации, поэтому просто добавьте логику, которую вы хотите переопределить.

Существуют некоторые ситуации, когда вы хотите переопределить базовый обработчик поворота, например сохранение состояния в конце поворота. Перед этим обязательно вызовите await base.OnTurnAsync(turnContext, cancellationToken);, чтобы убедиться, что базовая реализация OnTurnAsync выполняется перед дополнительным кодом. Эта базовая реализация, помимо прочего, отвечает за вызов остальных обработчиков действий, таких как OnMessageActivityAsync.

JavaScript

ActivityHandler в JavaScript использует модель передатчика и прослушивателя событий. Например, метод onMessage позволяет зарегистрировать прослушиватель событий для обработки сообщений. Вы можете зарегистрировать несколько прослушивателей. Когда бот получает действие message, обработчик действий получает информацию о нем и отправляет каждому прослушивателю действий onMessage в том порядке, в котором они были зарегистрированы.

При создании бота именно в прослушиватели onMessage следует помещать логику обработки сообщений и реагирования на них. Аналогичным образом, логика обработки участников, добавляемых в диалог, помещается в прослушиватели onMembersAdded, которые вызываются при каждом добавлении участника в диалог. Чтобы добавить эти прослушиватели, вы зарегистрируете их в боте, как показано в разделе логики Бота ниже. Добавьте логику бота для каждого прослушивателя, а в конце кода не забудьте вызвать next(). При вызове next()убедитесь, что следующий прослушиватель запущен.

Обеспечьте сохранение состояния перед завершением реплики. Для этого переопределите метод обработчика действий run и сохраните состояние после завершения родительского метода run.

Нет распространенных ситуаций, когда вы хотите переопределить обработчик базового поворота, поэтому будьте осторожны, если вы попытаетесь сделать это. Существует специальный обработчик onDialog. Обработчик onDialog выполняется в конце, после выполнения остальных обработчиков и не привязан к определенному типу действия. Как и для всех упомянутых выше обработчиков, обязательно вызовите next(), чтобы закончить завершающую часть процесса.

Java

Чтобы реализовать логику для этих обработчиков, вы переопределите эти методы в боте, например в разделе обработчика действий примера ниже. Для каждого из этих обработчиков нет базовой реализации, поэтому добавьте логику, которую вы хотите переопределить.

Существуют некоторые ситуации, когда вы хотите переопределить базовый обработчик поворота, например сохранение состояния в конце поворота. При этом необходимо сначала вызвать super.onTurn(turnContext); базовую реализацию onTurn перед дополнительным кодом. Эта базовая реализация, помимо прочего, отвечает за вызов остальных обработчиков действий, таких как onMessageActivity.

Python

У созданного бота логика обработки сообщений и реагирования на них будет связываться с этим обработчиком on_message_activity. Аналогичным образом, логика обработки участников, добавляемых в диалог, будет связываться с вашим обработчиком on_members_added, который вызывается при каждом добавлении участника в диалог.

Например, если бот получает действие сообщения, обработчик шагов оценивает это входящее действие, а затем отправляет его в обработчик действий on_message_activity.

Чтобы реализовать логику для этих обработчиков, вы переопределите эти методы в боте, например в разделе обработчика действий примера ниже. Для каждого из этих обработчиков нет базовой реализации, поэтому просто добавьте логику, которую вы хотите переопределить.

Существуют некоторые ситуации, когда вы хотите переопределить базовый обработчик поворота, например сохранение состояния в конце поворота. Перед этим обязательно вызовите await super().on_turn(turnContext);, чтобы убедиться, что базовая реализация on_turn выполняется перед дополнительным кодом. Эта базовая реализация, помимо прочего, отвечает за вызов остальных обработчиков действий, таких как on_message_activity.

Обработка действий

Логика бота обрабатывает входящие действия из одного или нескольких каналов и создает исходящие действия в ответ.

C#

Основная логика бота определяется в коде бота. Чтобы реализовать бот в качестве обработчика действий, наследуйте класс бота, ActivityHandlerкоторый реализует IBot интерфейс. ActivityHandler определяет различные обработчики для различных типов действий, таких как OnMessageActivityAsync, и OnMembersAddedAsync. Эти методы защищены, но могут быть переопределены, так как мы производимся от ActivityHandler.

Ниже описаны обработчики, определенные в ActivityHandler:

Событие	Обработчик	Description
Любой тип полученного действия	OnTurnAsync	Вызывает один из других обработчиков на основе типа полученного действия.
Полученное действие сообщения	OnMessageActivityAsync	Переопределите для обработки действия message.
Полученное действие обновления диалога	OnConversationUpdateActivityAsync	В действии conversationUpdate вызывает обработчик, если участники не добавлены в бота или покидают беседу.
Не добавленные в бота участники, которые присоединяются к беседе	OnMembersAddedAsync	Переопределите для обработки участников, присоединяющихся к беседе.
Не добавленные в бота участники, которые покидают беседу	OnMembersRemovedAsync	Переопределите для обработки участников, покидающих беседу.
Полученное действие события	OnEventActivityAsync	В действии event вызывает обработчик для события определенного типа.
Полученное действие события ответа маркера	OnTokenResponseEventAsync	Переопределите для обработки событий ответа маркера.
Полученное действие события другого ответа	OnEventAsync	Переопределите для обработки событий других типов.
Получение действия реакции на сообщение	OnMessageReactionActivityAsync	При получении действия messageReaction вызывает обработчик, если в сообщении были добавлены или удалены одна или несколько реакций.
Добавление реакции на сообщение в сообщение	OnReactionsAddedAsync	Переопределите, чтобы обрабатывать добавление реакций в сообщение.
Удаление реакции на сообщение из сообщения	OnReactionsRemovedAsync	Переопределите, чтобы обрабатывать удаление реакций из сообщения.
Получено действие обновления установки	OnInstallationUpdateActivityAsync	В действии installationUpdate вызывает обработчик на основе того, был ли установлен или удален бот.
Бот установлен	OnInstallationUpdateAddAsync	Переопределите это, чтобы добавить логику при установке бота в подразделении.
Бот удален	OnInstallationUpdateRemoveAsync	Переопределите это, чтобы добавить логику при удалении бота в подразделении.
Другой тип полученного действия	OnUnrecognizedActivityTypeAsync	Переопределите для обработки действия любого типа, которое иначе не будет обработано.

Эти разные обработчики используют turnContext для получения сведений о входящем действии, которое соответствует входящему HTTP-запросу. Действия могут быть разных типов, поэтому каждый обработчик предоставляет действием со строгой типизацией в параметре контекста шага. В большинстве случаев OnMessageActivityAsync является наиболее распространенным и всегда обрабатывается.

Как и в предыдущих версиях 4.x этой платформы, существует также возможность реализации общедоступного метода OnTurnAsync. Сейчас базовая реализация этого метода выполняет проверку ошибок, а затем вызывает каждый из определенных обработчиков (например те два, которые мы определяем в этом примере) в зависимости от типа входящего действия. В большинстве случаев этот метод можно оставить в одиночку и использовать отдельные обработчики, но если для вашей ситуации требуется пользовательская реализация OnTurnAsync, это по-прежнему вариант.

Важно!

При переопределении метода OnTurnAsync вам нужно вызвать base.OnTurnAsync, чтобы получить базовую реализацию для вызова всех остальных обработчиков On<activity>Async. Но вы также можете вызвать эти обработчики самостоятельно. В противном случае эти обработчики не будут вызваны и код не будет выполняться.

JavaScript

Основная логика бота определяется в коде бота. Чтобы реализовать бота в качестве обработчика действий, расширьте его ActivityHandler. ActivityHandler определяет различные события для различных типов действий, и вы можете изменить поведение бота, регистрируя прослушиватели событий, например с onMessage и onConversationUpdate.

Используйте следующие методы, чтобы зарегистрировать прослушиватели для каждого типа события.

Событие	Метод регистрации	Description
Любой тип полученного действия	onTurn	Регистрация прослушивателя, который вызывается при получении любого действия .
Полученное действие сообщения	onMessage	Регистрация прослушивателя, который вызывается при получении действия message.
Полученное действие обновления диалога	onConversationUpdate	Регистрация прослушивателя, который вызывается при получении любого действия conversationUpdate.
Присоединение участников к беседе	onMembersAdded	Регистрация прослушивателя, который вызывается при присоединении к беседе любого участника, включая самого бота.
Выход участников из беседы	onMembersRemoved	Регистрация прослушивателя, который вызывается при выходе из беседы любого участника, включая самого бота.
Получение действия реакции на сообщение	onMessageReaction	Регистрация прослушивателя, который вызывается при получении любого действия messageReaction.
Добавление реакции на сообщение в сообщение	onReactionsAdded	Регистрация прослушивателя, который вызывается при добавлении реакций к сообщению.
Удаление реакции на сообщение из сообщения	onReactionsRemoved	Регистрация прослушивателя, который вызывается при удалении реакций из сообщения.
Полученное действие события	onEvent	Регистрация прослушивателя, который вызывается при получении любого действия event.
Полученное действие события ответа маркера	onTokenResponseEvent	Регистрация прослушивателя, который вызывается при получении события tokens/response.
Получено действие обновления установки	onInstallationUpdate	Регистрация прослушивателя, который вызывается при получении любого действия installationUpdate.
Бот установлен	onInstallationUpdateAdd	Регистрирует прослушиватель при установке бота в подразделении.
Бот удален	onInstallationUpdateRemove	Регистрирует прослушиватель при удалении бота в подразделении.
Другой тип полученного действия	onUnrecognizedActivityType	Регистрирует прослушиватель, когда обработчик для определенного типа действия не определен.
Выполненные обработчики действий	onDialog	Вызывается после завершения всех применимых обработчиков.

Вызывайте функцию продолжения next из каждого обработчика, чтобы продолжить обработку. Если next не вызывается, обработка действия заканчивается.

Java

Основная логика бота определяется в коде бота. Чтобы реализовать бот в качестве обработчика действий, наследуйте класс бота, ActivityHandlerкоторый реализует Bot интерфейс. ActivityHandler определяет различные обработчики для различных типов действий, таких как onMessageActivity, и onMembersAdded. Эти методы защищены, но могут быть переопределены, так как мы производимся от ActivityHandler.

Ниже описаны обработчики, определенные в ActivityHandler:

Событие	Обработчик	Description
Любой тип полученного действия	onTurn	Вызывает один из других обработчиков на основе типа полученного действия.
Полученное действие сообщения	onMessageActivity	Переопределите для обработки действия message.
Полученное действие обновления диалога	onConversationUpdateActivity	В действии conversationUpdate вызывает обработчик, если участники не добавлены в бота или покидают беседу.
Не добавленные в бота участники, которые присоединяются к беседе	onMembersAdded	Переопределите для обработки участников, присоединяющихся к беседе.
Не добавленные в бота участники, которые покидают беседу	onMembersRemoved	Переопределите для обработки участников, покидающих беседу.
Полученное действие события	onEventActivity	В действии event вызывает обработчик для события определенного типа.
Полученное действие события ответа маркера	onTokenResponseEvent	Переопределите для обработки событий ответа маркера.
Полученное действие события другого ответа	onEvent	Переопределите для обработки событий других типов.
Получение действия реакции на сообщение	onMessageReactionActivity	При получении действия messageReaction вызывает обработчик, если в сообщении были добавлены или удалены одна или несколько реакций.
Добавление реакции на сообщение в сообщение	onReactionsAdded	Переопределите, чтобы обрабатывать добавление реакций в сообщение.
Удаление реакции на сообщение из сообщения	onReactionsRemoved	Переопределите, чтобы обрабатывать удаление реакций из сообщения.
Получено действие обновления установки	onInstallationUpdate	В действии installationUpdate вызывает обработчик на основе того, был ли установлен или удален бот.
Бот установлен	onInstallationUpdateAdd	Переопределите это, чтобы добавить логику при установке бота в подразделении.
Бот удален	onInstallationUpdateRemove	Переопределите это, чтобы добавить логику при удалении бота в подразделении.
Другой тип полученного действия	onUnrecognizedActivityType	Переопределите для обработки действия любого типа, которое иначе не будет обработано.

Эти разные обработчики используют turnContext для получения сведений о входящем действии, которое соответствует входящему HTTP-запросу. Действия могут быть разных типов, поэтому каждый обработчик предоставляет действием со строгой типизацией в параметре контекста шага. В большинстве случаев onMessageActivity является наиболее распространенным и всегда обрабатывается.

Существует также возможность реализации общедоступного метода onTurn. Сейчас базовая реализация этого метода выполняет проверку ошибок, а затем вызывает каждый из определенных обработчиков (например те два, которые мы определяем в этом примере) в зависимости от типа входящего действия. В большинстве случаев этот метод можно оставить в одиночку и использовать отдельные обработчики, но если для вашей ситуации требуется пользовательская реализация onTurn, это по-прежнему вариант.

Важно!

При переопределении метода onTurn вам нужно вызвать super.onTurn, чтобы получить базовую реализацию для вызова всех остальных обработчиков on<activity>. Но вы также можете вызвать эти обработчики самостоятельно. В противном случае эти обработчики не будут вызваны и код не будет выполняться.

Python

Основная логика бота определяется в коде бота. Чтобы реализовать бот в качестве обработчика действий, наследуйте класс бота, ActivityHandlerкоторый, в свою очередь, является производным от абстрактного Bot класса. ActivityHandler определяет различные обработчики для различных типов действий, таких как on_message_activity и on_members_added. Эти методы защищены, но могут быть переопределены, так как мы производимся от ActivityHandler.

Ниже описаны обработчики, определенные в ActivityHandler:

Событие	Обработчик	Description
Любой тип полученного действия	on_turn	Вызывает один из других обработчиков на основе типа полученного действия.
Полученное действие сообщения	on_message_activity	Переопределите для обработки действия message.
Полученное действие обновления диалога	on_conversation_update_activity	В действии conversationUpdate вызывает обработчик, если участники не добавлены в бота или покидают беседу.
Не добавленные в бота участники, которые присоединяются к беседе	on_members_added_activity	Переопределите для обработки участников, присоединяющихся к беседе.
Не добавленные в бота участники, которые покидают беседу	on_members_removed_activity	Переопределите для обработки участников, покидающих беседу.
Полученное действие события	on_event_activity	В действии event вызывает обработчик для события определенного типа.
Полученное действие события ответа маркера	on_token_response_event	Переопределите для обработки событий ответа маркера.
Полученное действие события другого ответа	on_event_activity	Переопределите для обработки событий других типов.
Получение действия реакции на сообщение	on_message_reaction_activity	При получении действия messageReaction вызывает обработчик, если в сообщении были добавлены или удалены одна или несколько реакций.
Добавление реакции на сообщение в сообщение	on_reactions_added	Переопределите, чтобы обрабатывать добавление реакций в сообщение.
Удаление реакции на сообщение из сообщения	on_reactions_removed	Переопределите, чтобы обрабатывать удаление реакций из сообщения.
Получено действие обновления установки	on_installation_update	В действии installationUpdate вызывает обработчик на основе того, был ли установлен или удален бот.
Бот установлен	on_installation_update_add	Переопределите это, чтобы добавить логику при установке бота в подразделении.
Бот удален	on_installation_update_remove	Переопределите это, чтобы добавить логику при удалении бота в подразделении.
Другой тип полученного действия	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

public class EchoBot extends ActivityHandler {

    @Override
    protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
        return turnContext.sendActivity(
            MessageFactory.text("Echo: " + turnContext.getActivity().getText())
        ).thenApply(sendResult -> null);
    }

    @Override
    protected CompletableFuture<Void> onMembersAdded(
        List<ChannelAccount> membersAdded,
        TurnContext turnContext
    ) {
        String welcomeText = "Hello and welcome!";
        return membersAdded.stream()
            .filter(
                member -> !StringUtils
                    .equals(member.getId(), turnContext.getActivity().getRecipient().getId())
            ).map(channel -> turnContext.sendActivity(MessageFactory.text(welcomeText, welcomeText, null)))
            .collect(CompletableFutures.toFutureList()).thenApply(resourceResponses -> null);
    }
}

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, которые бот должен поддерживать для правильной работы с Teams. Основные понятия разработки ботов для Microsoft Teams вам поможет понять статья How Microsoft Teams bots work (Принцип работы ботов Microsoft Teams).
• Обработчик действий — это хороший способ разработки бота, который не требуется отслеживать состояние беседы между поворотами. Библиотека диалогов предоставляет способы управления длительным диалогом с пользователем.