Manipuladores de atividade de bot

  • Artigo

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 Quando o conector recebe uma atividade de invocação de ação cartão, esse método é invocado.
fileConsent/invoke OnTeamsFileConsentAcceptAsync Quando um usuário aceita um cartão de consentimento do arquivo, esse método é invocado.
fileConsent/invoke OnTeamsFileConsentAsync Quando o conector recebe um consentimento do arquivo cartão atividade, esse método é invocado.
fileConsent/invoke OnTeamsFileConsentDeclineAsync Quando um usuário recusa um cartão de consentimento do arquivo, esse método é invocado.
actionableMessage/executeAction OnTeamsO365ConnectorCardActionAsync Quando o conector recebe um conector cartão para Grupos do Microsoft 365 atividade de ação, esse método é invocado.
signin/verifyState OnTeamsSigninVerifyStateAsync Quando o conector recebe uma signIn atividade de estado de verificação, esse método é invocado.
task/fetch OnTeamsTaskModuleFetchAsync Você pode substituir esse método em uma classe derivada para fornecer lógica quando uma caixa de diálogo (conhecida como módulo de tarefa no TeamsJS v1.x) é buscada.
task/submit OnTeamsTaskModuleSubmitAsync Você pode substituir esse método em uma classe derivada para fornecer lógica quando uma caixa de diálogo é enviada.

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 Exibir

Próxima etapa

Noções básicas sobre conversas

Confira também