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
  }

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 Esse método pode ser substituído para manipular uma atividade de Message.
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 saber mais, veja 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 saber mais, veja 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 saber mais, veja 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 saber mais, veja 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 saber mais, veja 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 saber mais, veja membros da equipe removidos em eventos de atualização de conversa.

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 um cartão de consentimento de arquivo é aceito pelo usuário.
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 um cartão de consentimento de arquivo é recusado pelo usuário.
actionableMessage/executeAction OnTeamsO365ConnectorCardActionAsync Esse método é invocado quando uma atividade de ação de cartão do conector Office 365 é recebida do conector.
signin/verifyState OnTeamsSigninVerifyStateAsync Esse método é invocado quando uma atividade de estado de verificação de entrada é 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.

Próxima etapa

Confira também