Manipuladores de atividade de bot
Este documento se baseia no artigo sobre como os bots funcionam na principal Documentação Bot Framework. A principal diferença entre os bots desenvolvidos para o Microsoft Teams e o Bot Framework principal está nos recursos fornecidos no Teams.
Um manipulador de atividades é usado para organizar a lógica de conversa para o bot. As atividades são tratadas de duas maneiras usando os manipuladores de atividades do Teams e a lógica de bot. O manipulador de atividades do Teams adiciona suporte para eventos e interações específicos do Teams. O objeto de bot contém o raciocínio ou a lógica de conversação para um turno e expõe um manipulador de turnos, que é o método que pode aceitar atividades de entrada do adaptador de bot.
Manipuladores de atividades do Teams
O manipulador de atividades do Teams é derivado do manipulador de atividades do Microsoft Bot Framework. Ele roteia todas as atividades do Teams antes de permitir que as atividades específicas que não sejam do Teams sejam tratadas.
Quando um bot do Teams recebe uma atividade, ele é roteado para os manipuladores de atividades. Todas as atividades são roteadas por meio de um manipulador base chamado manipulador de turnos. O manipulador de turnos chama o manipulador de atividades necessário para gerenciar qualquer atividade recebida. O bot do Teams é derivado da classe TeamsActivityHandler
, que é derivada da classe ActivityHandler
do Bot Framework.
Observação
Se a atividade do bot levar mais de 15 segundos para ser processada, o Teams enviará uma solicitação de repetição para o ponto de extremidade do bot. Portanto, você verá solicitações duplicadas em seu bot.
Os bots são criados usando o Bot Framework. Se os bots receberem uma atividade de mensagem, o manipulador de turnos receberá uma notificação dessa atividade de entrada. Em seguida, o manipulador de turnos envia a atividade de entrada para o manipulador de atividades OnMessageActivityAsync
. No Teams, essa funcionalidade permanece a mesma. Se o bot receber uma atividade de atualização de conversa, o manipulador de turnos receberá uma notificação dessa atividade de entrada e enviará a atividade de entrada para o OnConversationUpdateActivityAsync
. Primeiro, o manipulador de atividades do Teams verifica se há eventos específicos do Teams. Se nenhum evento for encontrado, ele as passará para o manipulador de atividades do Bot Framework.
Na classe do manipulador de atividades do Teams, há dois manipuladores de atividades principais do Teams, OnConversationUpdateActivityAsync
e OnInvokeActivityAsync
. A classe OnConversationUpdateActivityAsync
roteia todas as atividades de atualização de conversa e a classe OnInvokeActivityAsync
roteia todas as atividades de invocação do Teams.
Para implementar sua lógica de manipuladores de atividades específicos do Teams, você deve substituir os métodos em seu bot, conforme mostrado na seção lógica do bot. Não há implementação base para esses manipuladores. Portanto, adicione a lógica desejada em sua substituição.
Os trechos de código para manipuladores de atividades do 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
}
Lógica do bot
A lógica do bot processa atividades de entrada de um ou mais de seus canais de bot e, em resposta, gera atividades de saída. Ainda é verdade para bots derivados da classe manipulador de atividades do Teams, que primeiro verifica as atividades do Teams. Depois de verificar as atividades do Teams, ele passa todas as outras atividades para o manipulador de atividades do Bot Framework.
Manipuladores Principais do Bot Framework
Observação
- Exceto para as atividades dos membros adicionados e removidos, todos os manipuladores de atividades descritos nesta seção continuam funcionando como fazem com um bot que não é do Teams.
- O método
onInstallationUpdateActivityAsync()
é usado para obter a Localidade do Teams ao adicionar o bot ao Teams.
Os manipuladores de atividade são diferentes no contexto de uma equipe, onde um novo membro é adicionado à equipe em vez de um thread de mensagens.
A lista de manipuladores definidos em ActivityHandler
inclui os seguintes eventos:
Evento | Manipulador | Descrição |
---|---|---|
Qualquer tipo de atividade recebida | OnTurnAsync |
Esse método chama um dos outros manipuladores, com base no tipo de atividade recebida. |
Atividade de mensagem recebida | OnMessageActivityAsync |
Você pode substituir esse método para lidar com uma Message atividade. |
Atividade de atualização de mensagem recebida | OnMessageUpdateActivityAsync |
Você pode substituir esse método para lidar com uma atividade de atualização de mensagem. |
Atividade de exclusão de mensagem recebida | OnMessageDeleteActivityAsync |
Você pode substituir esse método para lidar com uma atividade de exclusão de mensagem. |
Atividade de atualização de conversa recebida | OnConversationUpdateActivityAsync |
Esse método chama um manipulador se outros membros que não sejam o bot ingressaram ou saíram da conversa, em uma atividade de ConversationUpdate . |
Membros que não são bots ingressaram na conversa | OnMembersAddedAsync |
Esse método pode ser substituído para manipular membros que ingressam em uma conversa. |
Membros que não são bots saíram da conversa | OnMembersRemovedAsync |
Esse método pode ser substituído para manipular membros que saem de uma conversa. |
Atividade de evento recebida | OnEventActivityAsync |
Esse método chama um manipulador específico para o tipo de evento, em uma atividade de Event . |
Atividade de evento de resposta de token recebida | OnTokenResponseEventAsync |
Esse método pode ser substituído para manipular eventos de resposta de token. |
Atividade de evento de resposta sem token recebida | OnEventAsync |
Esse método pode ser substituído para manipular outros tipos de eventos. |
Outro tipo de atividade recebida | OnUnrecognizedActivityTypeAsync |
Esse método pode ser substituído para manipular qualquer tipo de atividade que não seria manipulada. |
Manipuladores de atividades específicos do Teams
O TeamsActivityHandler
estende a lista de manipuladores na seção principal de manipuladores do Bot Framework para incluir os seguintes eventos:
Evento | Manipulador | Descrição |
---|---|---|
channelCreated | OnTeamsChannelCreatedAsync |
Esse método pode ser substituído para manipular um canal do Teams sendo criado. Para obter mais informações, consulte canal criado em eventos de atualização de conversa. |
channelDeleted | OnTeamsChannelDeletedAsync |
Esse método pode ser substituído para manipular um canal do Teams sendo excluído. Para obter mais informações, consulte canal excluído em eventos de atualização de conversa. |
channelRenamed | OnTeamsChannelRenamedAsync |
Esse método pode ser substituído para manipular um canal do Teams sendo renomeado. Para obter mais informações, consulte canal renomeado em Eventos de atualização de conversa. |
teamRenamed | OnTeamsTeamRenamedAsync |
return Task.CompletedTask; Esse método pode ser substituído para manipular uma equipe do Teams sendo renomeada. Para obter mais informações, consulte equipe renomeada em eventos de atualização de conversa. |
MembersAdded | OnTeamsMembersAddedAsync |
Esse método chama o método OnMembersAddedAsync no ActivityHandler . O método pode ser substituído para manipular membros que ingressam em uma equipe. Para obter mais informações, consulte membros da equipe adicionados em eventos de atualização de conversa. |
MembersRemoved | OnTeamsMembersRemovedAsync |
Esse método chama o método OnMembersRemovedAsync no ActivityHandler . O método pode ser substituído para manipular membros que saem de uma equipe. Para obter mais informações, consulte membros da equipe removidos em eventos de atualização de conversa. |
messageEdit | OnTeamsMessageEditAsync |
Você pode substituir esse método para lidar com um evento de edição de mensagens do Teams. |
messageUndelete | OnTeamsMessageUndeleteAsync |
Você pode substituir esse método para lidar com um evento undelete de mensagem do Teams. |
messageSoftDelete | OnTeamsMessageSoftDeleteAsync |
Você pode substituir esse método para lidar com um evento de exclusão suave da mensagem do Teams. |
Atividades de invocação do Teams
A lista de manipuladores de atividades do Teams chamados do manipulador de atividades do OnInvokeActivityAsync
Teams inclui os seguintes tipos de invocação:
Invocar tipos | Manipulador | Descrição |
---|---|---|
CardAction.Invoke | OnTeamsCardActionInvokeAsync |
Esse método é invocado quando uma atividade de invocação de ação de cartão é recebida do conector. |
fileConsent/invoke | OnTeamsFileConsentAcceptAsync |
Esse método é invocado quando o usuário aceita um cartão de consentimento do arquivo. |
fileConsent/invoke | OnTeamsFileConsentAsync |
Esse método é invocado quando uma atividade de cartão de consentimento de arquivo é recebida do conector. |
fileConsent/invoke | OnTeamsFileConsentDeclineAsync |
Esse método é invocado quando o usuário recusa um cartão de consentimento do arquivo. |
actionableMessage/executeAction | OnTeamsO365ConnectorCardActionAsync |
Esse método é invocado quando um conector cartão para Grupos do Microsoft 365 atividade de ação é recebido do conector. |
signin/verifyState | OnTeamsSigninVerifyStateAsync |
Esse método é invocado quando uma signIn atividade de estado de verificação é recebida do conector. |
task/fetch | OnTeamsTaskModuleFetchAsync |
Esse método pode ser substituído em uma classe derivada para fornecer lógica quando um módulo de tarefa é buscado. |
task/submit | OnTeamsTaskModuleSubmitAsync |
Esse método pode ser substituído em uma classe derivada para fornecer lógica quando um módulo de tarefa é enviado. |
As atividades de invocação listadas nesta seção são para bots de conversa no Teams. O Bot Framework SDK também é compatível com atividades de invocação específicas para extensões de mensagem. Para saber mais, confira o que são extensões de mensagem.
Agora que você se familiarizou com manipuladores de atividades de bot, vamos ver como os bots se comportam de forma diferente dependendo da conversa e das mensagens que ele recebe ou envia.
Exemplo de código
Nome do exemplo | Descrição | .NET | Node.js | Python |
---|---|---|---|---|
Bot de conversas do Teams | Este aplicativo de exemplo mostra como usar diferentes eventos de conversa de bot disponíveis no Bot Framework v4. | View | View | Exibir |
Exemplos de bot | Conjunto de exemplos do Bot Framework v4. | View | View | View |