Controladores de actividad de bots

  • Artículo

Este documento se basa en el artículo sobre cómo funcionan los bots de la documentación de Bot Framework principal. La principal diferencia entre los bots desarrollados para Microsoft Teams y el Bot Framework principal se encuentra en las características proporcionadas en Teams.

Se usa un controlador de actividad para organizar la lógica conversacional del bot. Las actividades se controlan de dos maneras mediante controladores de actividad de Teams y la lógica de bot. El controlador de actividad de Teams agrega compatibilidad con eventos e interacciones específicos de Teams. El objeto del bot contiene el razonamiento conversacional o la lógica de un turno y expone un controlador de turnos, que es el método que puede aceptar actividades entrantes desde el adaptador del bot.

Controladores de actividades de Teams

El controlador de actividad de Teams se deriva del controlador de actividad de Microsoft Bot Framework. Enruta todas las actividades Teams antes de permitir que se controlen las actividades específicas que no sean de Teams.

Cuando un bot de Teams recibe una actividad, se enruta a los controladores de actividad. Todas las actividades se enrutan a través de un controlador base denominado controlador de turnos. El controlador de turnos llama al controlador de actividad necesario para controlar el tipo de actividad que se recibió. El bot de Teams se deriva de la clase TeamsActivityHandler, que se deriva de la clase ActivityHandler de Bot Framework.

Nota:

Si la actividad del bot tarda más de 15 segundos en procesarse, Teams envía una solicitud de reintento al punto de conexión del bot. Por lo tanto, verá solicitudes duplicadas en el bot.

Los bots se crean con Bot Framework. Si los bots reciben una actividad de mensaje, el controlador de turnos recibe una notificación de esa actividad entrante. A continuación, el controlador de turnos envía la actividad entrante al controlador de actividad OnMessageActivityAsync. En Teams, esta funcionalidad sigue siendo la misma. Si el bot recibe una actividad de actualización de conversación, el controlador de turnos recibe una notificación de esa actividad entrante y la envía a OnConversationUpdateActivityAsync. El controlador de actividad de Teams comprueba primero si hay eventos específicos de Teams. Si no se encuentra ningún evento, los pasa al controlador de actividad de Bot Framework.

En la clase del controlador de actividad de Teams, hay dos controladores de actividad de Teams principales, OnConversationUpdateActivityAsync y OnInvokeActivityAsync. OnConversationUpdateActivityAsyncenruta todas las actividades de actualización de conversación y OnInvokeActivityAsync enruta todas las actividades de invocación de Teams.

Para implementar la lógica para los controlares de actividades específicas de Teams, debe invalidar los métodos en el bot, como se muestra en la sección Lógica del bot. No hay ninguna implementación base para estos controladores. Por lo tanto, agregue la lógica que desee en la invalidación.

Fragmentos de código para controladores de actividad de 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 del bot

La lógica del bot procesa las actividades entrantes desde uno o varios de los canales del bot y, en respuesta, genera actividades salientes. Sigue siendo cierto en el caso de los bots derivados de la clase de controlador de actividad de Teams, que primero comprueba las actividades de Teams. Después de comprobar si hay actividades de Teams, pasa todas las demás actividades al controlador de actividad de Bot Framework.

Controladores del Bot Framework principal

Nota:

  • Excepto para las actividades de los miembros agregados y quitados, todos los controladores de actividad descritos en esta sección siguen funcionando como lo hacen con un bot que no es de Teams.
  • El método onInstallationUpdateActivityAsync() se usa para obtener la configuración regional de Teams a la vez que se agrega el bot a Teams.

Los controladores de actividad son diferentes en el contexto de un equipo, ya que se agrega un nuevo miembro al equipo en lugar de una conversación.

La lista de controladores definidos en ActivityHandler incluye los siguientes eventos:

Evento Controlador Descripción
Cualquier tipo de actividad recibida OnTurnAsync Este método llama a uno de los otros controladores, en función del tipo de actividad recibida.
Actividad de mensaje recibida OnMessageActivityAsync Puede invalidar este método para controlar una Message actividad.
Actividad de actualización de mensajes recibida OnMessageUpdateActivityAsync Puede invalidar este método para controlar una actividad de actualización de mensajes.
Actividad de eliminación de mensajes recibida OnMessageDeleteActivityAsync Puede invalidar este método para controlar una actividad de eliminación de mensajes.
Actividad de actualización de conversación recibida OnConversationUpdateActivityAsync Este método llama a un controlador si miembros distintos del bot se unieron o abandonaron la conversación, en una actividad ConversationUpdate.
Miembros que no son bots se unieron a la conversación OnMembersAddedAsync Este método se puede invalidar para controlar los miembros que se unen a una conversación.
Miembros que no son bots abandonaron la conversación OnMembersRemovedAsync Este método se puede invalidar para controlar los miembros que salen de una conversación.
Actividad de evento recibida OnEventActivityAsync Este método llama a un controlador específico del tipo de evento, en una actividad Event.
Actividad de evento de respuesta de token recibida OnTokenResponseEventAsync Este método se puede invalidar para controlar los eventos de respuesta de token.
Actividad de evento que no es de respuesta de token recibida OnEventAsync Este método se puede invalidar para controlar otros tipos de eventos.
Otro tipo de actividad recibido OnUnrecognizedActivityTypeAsync Este método se puede invalidar para controlar cualquier tipo de actividad que no está controlada.

Controladores de actividades específicas de Teams

TeamsActivityHandler amplía la lista de controladores en la sección principal de controladores de Bot Framework para incluir los siguientes eventos:

Evento Controlador Descripción
channelCreated OnTeamsChannelCreatedAsync Este método se puede invalidar para controlar un canal de Teams que se está creando. Para obtener más información, vea Canal creado en Eventos de actualización de conversación.
ChannelDeleted OnTeamsChannelDeletedAsync Este método se puede invalidar para controlar un canal de Teams que se va a eliminar. Para obtener más información, vea Canal eliminado en Eventos de actualización de conversación.
channelRenamed OnTeamsChannelRenamedAsync Este método se puede invalidar para controlar un canal de Teams al que se le está cambiando el nombre. Para obtener más información, consulte el nombre del canal en Eventos de actualización de conversación.
teamRenamed OnTeamsTeamRenamedAsync return Task.CompletedTask; Este método se puede invalidar para controlar un equipo de Teams al que se le va a cambiar el nombre. Para obtener más información, consulte cambio de nombre del equipo en Eventos de actualización de conversación.
MembersAdded OnTeamsMembersAddedAsync Este método llama al método OnMembersAddedAsync en ActivityHandler. El método se puede invalidar para controlar los miembros que se unen a un equipo. Para obtener más información, consulte los miembros del equipo agregados en Eventos de actualización de conversación.
MembersRemoved OnTeamsMembersRemovedAsync Este método llama al método OnMembersRemovedAsync en ActivityHandler. El método se puede invalidar para controlar los miembros que abandonan un equipo. Para obtener más información, vea Miembros del equipo eliminados en Eventos de actualización de conversaciones.
messageEdit OnTeamsMessageEditAsync Puede invalidar este método para controlar un evento de edición de mensajes de Teams.
messageUndelete OnTeamsMessageUndeleteAsync Puede invalidar este método para controlar un evento de recuperación de mensajes de Teams.
messageSoftDelete OnTeamsMessageSoftDeleteAsync Puede invalidar este método para controlar un evento de eliminación temporal de mensajes de Teams.

Actividades de invocación de Teams

La lista de controladores de actividad de Teams a los que se llama desde el OnInvokeActivityAsync controlador de actividad de Teams incluye los siguientes tipos de invocación:

Tipos de invocación Controlador Descripción
CardAction.Invoke OnTeamsCardActionInvokeAsync Cuando el conector recibe una actividad de invocación de acción de tarjeta, se invoca este método.
fileConsent/invoke OnTeamsFileConsentAcceptAsync Cuando un usuario acepta una tarjeta de consentimiento de archivo, se invoca este método.
fileConsent/invoke OnTeamsFileConsentAsync Cuando el conector recibe una actividad de tarjeta de consentimiento de archivo, se invoca este método.
fileConsent/invoke OnTeamsFileConsentDeclineAsync Cuando un usuario rechaza una tarjeta de consentimiento de archivo, se invoca este método.
actionableMessage/executeAction OnTeamsO365ConnectorCardActionAsync Cuando el conector recibe una tarjeta de conector para Grupos de Microsoft 365 actividad de acción, se invoca este método.
signin/verifyState OnTeamsSigninVerifyStateAsync Cuando el conector recibe una signIn actividad de estado de comprobación, se invoca este método.
task/fetch OnTeamsTaskModuleFetchAsync Puede invalidar este método en una clase derivada para proporcionar lógica cuando se captura un cuadro de diálogo (denominado módulo de tareas en TeamsJS v1.x).
task/submit OnTeamsTaskModuleSubmitAsync Puede invalidar este método en una clase derivada para proporcionar lógica cuando se envía un cuadro de diálogo.

Las actividades invoke enumeradas en esta sección son para bots conversacionales en Teams. El SDK de Bot Framework también admite la invocación de actividades específicas de las extensiones de mensaje. Para obtener más información, consulte ¿Qué son las extensiones de mensaje?

Ahora que se ha familiarizado con los controladores de actividad del bot, veamos cómo se comportan los bots de forma diferente en función de la conversación y de los mensajes que recibe o envía.

Ejemplo de código

Ejemplo de nombre Descripción .NET Node.js Python
Bot de conversación de Teams Esta aplicación de ejemplo muestra cómo usar diferentes eventos de conversación de bot disponibles en Bot Framework v4. View View View
Ejemplos de bot Conjunto de ejemplos de Bot Framework v4. View View View

Paso siguiente

Conceptos básicos de la conversación

Consulte también