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 processador de atividades é utilizado para organizar a lógica de conversação do bot. As atividades são tratadas de duas maneiras usando os manipuladores de atividades do Teams e a lógica de bot. O processador 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, é encaminhado para os processadores de atividade. 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 demorar mais de 15 segundos a ser processada, o Teams envia um pedido de repetição para o ponto final do bot. Assim, verá pedidos duplicados no 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 existe nenhuma implementação base para estes processadores. Por conseguinte, adicione a lógica pretendida na 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. Continua a ser verdade para os bots derivados da classe de processador de atividades do Teams, que verifica primeiro 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 processadores 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 Pode substituir este método para processar uma Message atividade.
Atividade de atualização de mensagens recebida OnMessageUpdateActivityAsync Pode substituir este método para processar uma atividade de atualização de mensagens.
Atividade de eliminação de mensagens recebida OnMessageDeleteActivityAsync Pode substituir este método para processar uma atividade de eliminação de mensagens.
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 expande a lista de processadores na secção principais processadores 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, veja canal criado em Eventos de atualização de conversação.
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 eliminado em Eventos de atualização de conversação.
channelRenamed OnTeamsChannelRenamedAsync Esse método pode ser substituído para manipular um canal do Teams sendo renomeado. Para obter mais informações, consulte o nome do canal mudado em Eventos de atualização de conversação.
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 o nome da equipa mudado em Eventos de atualização de conversação.
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 equipa adicionados em Eventos de atualização de conversação.
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, veja Membros da equipa removidos em Eventos de atualização de conversação.
messageEdit OnTeamsMessageEditAsync Pode substituir este método para processar um evento de edição de mensagens do Teams.
messageUndelete OnTeamsMessageUndeleteAsync Pode substituir este método para processar um evento de anulação de eliminação de mensagens do Teams.
messageSoftDelete OnTeamsMessageSoftDeleteAsync Pode substituir este método para processar um evento de eliminação recuperável de mensagens do Teams.

Atividades de invocação do Teams

A lista de processadores de atividade do Teams chamados a partir do processador 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 de cartão, este método é invocado.
fileConsent/invoke OnTeamsFileConsentAcceptAsync Quando um utilizador aceita um cartão de consentimento de ficheiro, este método é invocado.
fileConsent/invoke OnTeamsFileConsentAsync Quando o conector recebe uma atividade de cartão de consentimento de ficheiro, este método é invocado.
fileConsent/invoke OnTeamsFileConsentDeclineAsync Quando um utilizador recusa um cartão de consentimento de ficheiro, este método é invocado.
actionableMessage/executeAction OnTeamsO365ConnectorCardActionAsync Quando o conector recebe um cartão de conector para a atividade de ação dos Grupos do Microsoft 365, este método é invocado.
signin/verifyState OnTeamsSigninVerifyStateAsync Quando o conector recebe uma signIn atividade de estado de verificação, este método é invocado.
task/fetch OnTeamsTaskModuleFetchAsync Pode substituir este método numa classe derivada para fornecer lógica quando for obtida uma caixa de diálogo (referida como módulo de tarefas no TeamsJS v1.x).
task/submit OnTeamsTaskModuleSubmitAsync Pode substituir este método numa classe derivada para fornecer lógica quando uma caixa de diálogo é submetida.

As atividades de Invocação listadas nesta secção destinam-se a bots de conversação 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 se familiarizou com os processadores de atividade de bots, deixe-nos ver como os bots se comportam de forma diferente consoante a conversação e as mensagens que recebe ou envia.

Exemplo de código

Nome do exemplo Descrição .NET Node.js Python
Bot de conversas do Teams Esta aplicação de exemplo mostra como utilizar diferentes eventos de conversação de bot disponíveis no Bot Framework v4. View View Exibir
Exemplos de bot Conjunto de exemplos do Bot Framework v4. View View View

Próxima etapa

Confira também