Gestionnaire d'activité du robot

  • Article

Ce document s’appuie sur l’article sur le fonctionnement des bots dans la documentation principale de Bot Framework. La principale différence entre les bots développés pour Microsoft Teams et le framework bot principal réside dans les fonctionnalités fournies dans Teams.

Un gestionnaire d’activités est utilisé pour organiser la logique conversationnelle de votre bot. Les activités sont gérées de deux manières à l’aide de gestionnaires d’activités Teams et de logique de bot. Le gestionnaire d’activités Teams ajoute la prise en charge des événements et des interactions spécifiques à Teams. L’objet bot contient le raisonnement conversationnel ou la logique d’un tour et expose un gestionnaire de tours, qui est la méthode qui peut accepter les activités entrantes de l’adaptateur de bot.

Gestionnaires d’activités Microsoft Teams

Teams gestionnaire d’activités est dérivé du gestionnaire d’activités de Microsoft Bot Framework. Il achemine toutes les activités Teams avant d’autoriser la gestion des activités non Teams spécifiques.

Lorsqu’un bot pour Teams reçoit une activité, elle est routée vers les gestionnaires d’activités. Toutes les activités sont routées via un gestionnaire de base appelé gestionnaire de tour. Le gestionnaire de tours appelle le gestionnaire d’activités requis pour gérer le type d’activité reçu. Le bot Teams est dérivé de la TeamsActivityHandler classe, qui est dérivée de la classe bot ActivityHandler framework.

Remarque

Si le traitement de l’activité du bot prend plus de 15 secondes, Teams envoie une demande de nouvelle tentative au point de terminaison du bot. Par conséquent, vous verrez des demandes en double dans votre bot.

Les bots sont créés à l’aide de Bot Framework. Si les bots reçoivent une activité de message, le gestionnaire de tours reçoit une notification de cette activité entrante. Le gestionnaire de tours envoie ensuite l’activité entrante au gestionnaire d’activités OnMessageActivityAsync. Dans Teams, cette fonctionnalité reste la même. Si le bot reçoit une activité de mise à jour de conversation, le gestionnaire de tours reçoit une notification de cette activité entrante et envoie l’activité entrante à OnConversationUpdateActivityAsync. Le gestionnaire d’activités Teams vérifie d’abord les événements spécifiques Teams. Si aucun événement n’est trouvé, il les transmet ensuite au gestionnaire d’activités de Bot Framework.

Dans la classe de gestionnaire d’activités Teams, il existe deux principaux gestionnaires d’activités Teams, OnConversationUpdateActivityAsync et OnInvokeActivityAsync. OnConversationUpdateActivityAsyncroute toutes les activités de mise à jour de conversation et OnInvokeActivityAsync route toutes les activités Teams appeler.

Pour implémenter votre logique pour Teams gestionnaires d’activités spécifiques, vous devez remplacer les méthodes de votre bot, comme indiqué dans la section logique du bot. Il n’existe aucune implémentation de base pour ces gestionnaires. Par conséquent, ajoutez la logique souhaitée dans votre remplacement.

Extraits de code pour les gestionnaires d’activités 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 
  }

Logique de bot

La logique du bot traite les activités entrantes à partir d’un ou plusieurs de vos canaux de bot et génère en réponse des activités sortantes. Cela est toujours vrai pour les bots dérivés de la classe de gestionnaire d’activités Teams, qui vérifie d’abord les activités Teams. Après avoir vérifié Teams activités, elle transmet toutes les autres activités au gestionnaire d’activités de Bot Framework.

Principaux gestionnaires Bot Framework

Remarque

  • À l’exception des activités des membres ajoutés et supprimés, tous les gestionnaires d’activités décrits dans cette section continuent de fonctionner comme ils le font avec un bot non Teams.
  • La méthode onInstallationUpdateActivityAsync() est utilisée pour obtenir les paramètres régionaux de Microsoft Teams lors de l’ajout du bot à Microsoft Teams.

Les gestionnaires d’activités sont différents dans le contexte d’une équipe, où un nouveau membre est ajouté à l’équipe au lieu d’un thread de message.

La liste des gestionnaires définis dans ActivityHandler inclut les événements suivants :

Événement Handler Description
Tout type d’activité reçu OnTurnAsync Cette méthode appelle l’un des autres gestionnaires, en fonction du type d’activité reçue.
Activité de message reçue OnMessageActivityAsync Vous pouvez remplacer cette méthode pour gérer une Message activité.
Activité de mise à jour de message reçue OnMessageUpdateActivityAsync Vous pouvez remplacer cette méthode pour gérer une activité de mise à jour de message.
Activité de suppression de message reçue OnMessageDeleteActivityAsync Vous pouvez remplacer cette méthode pour gérer une activité de suppression de message.
Activité de mise à jour de conversation reçue OnConversationUpdateActivityAsync Cette méthode appelle un gestionnaire si des membres autres que le bot ont rejoint ou quitté la conversation, sur une ConversationUpdate activité.
Les membres non-bot ont rejoint la conversation OnMembersAddedAsync Cette méthode peut être remplacée pour gérer les membres qui rejoignent une conversation.
Les membres non-bot ont quitté la conversation OnMembersRemovedAsync Cette méthode peut être substituée pour gérer les membres quittant une conversation.
Activité d’événement reçue OnEventActivityAsync Cette méthode appelle un gestionnaire spécifique au type d’événement, sur une Event activité.
Activité d’événement de réponse de jeton reçue OnTokenResponseEventAsync Cette méthode peut être remplacée pour gérer les événements de réponse de jeton.
Activité d’événement sans réponse de jeton reçue OnEventAsync Cette méthode peut être remplacée pour gérer d’autres types d’événements.
Autre type d’activité reçu OnUnrecognizedActivityTypeAsync Cette méthode peut être substituée pour gérer n’importe quel type d’activité autrement non géré.

Gestionnaires d’activités Microsoft Teams

Étend TeamsActivityHandler la liste des gestionnaires dans la section Principaux gestionnaires Bot Framework pour inclure les événements suivants :

Événement Handler Description
channelCreated OnTeamsChannelCreatedAsync Cette méthode peut être substituée pour gérer un canal Teams en cours de création. Pour plus d’informations, consultez canal créé dans Événements de mise à jour de conversation.
ChannelDeleted OnTeamsChannelDeletedAsync Cette méthode peut être remplacée pour gérer un canal Teams en cours de suppression. Pour plus d’informations, consultez Canal supprimé dans Événements de mise à jour de conversation.
channelRenamed OnTeamsChannelRenamedAsync Cette méthode peut être remplacée pour gérer un canal Teams renommé. Pour plus d’informations, consultez Canal renommé dans Événements de mise à jour de conversation.
teamRenamed OnTeamsTeamRenamedAsync return Task.CompletedTask;Cette méthode peut être remplacée pour gérer une équipe Teams renommée. Pour plus d’informations, consultez l’équipe renommée dans Événements de mise à jour de conversation.
MembersAdded OnTeamsMembersAddedAsync Cette méthode appelle la OnMembersAddedAsync méthode dans ActivityHandler. La méthode peut être remplacée pour gérer les membres qui rejoignent une équipe. Pour plus d’informations, consultez Membres de l’équipe ajoutés dans Événements de mise à jour de conversation.
MembersRemoved OnTeamsMembersRemovedAsync Cette méthode appelle la OnMembersRemovedAsync méthode dans ActivityHandler. La méthode peut être remplacée pour gérer les membres quittant une équipe. Pour plus d’informations, consultez Membres de l’équipe supprimés dans Événements de mise à jour de conversation.
messageModifier OnTeamsMessageEditAsync Vous pouvez remplacer cette méthode pour gérer un événement de modification de message Teams.
messageUndelete OnTeamsMessageUndeleteAsync Vous pouvez remplacer cette méthode pour gérer un événement d’annulation de suppression de message Teams.
messageSoftDelete OnTeamsMessageSoftDeleteAsync Vous pouvez remplacer cette méthode pour gérer un événement de suppression réversible de message Teams.

Teams appeler des activités

La liste des gestionnaires d’activités Teams appelés à partir du OnInvokeActivityAsync gestionnaire d’activités Teams comprend les types d’appels suivants :

Appeler des types Handler Description
CardAction.Invoke OnTeamsCardActionInvokeAsync Lorsque le connecteur reçoit une activité d’appel d’action carte, cette méthode est appelée.
fileConsent/invoke OnTeamsFileConsentAcceptAsync Lorsqu’un utilisateur accepte un carte de consentement de fichier, cette méthode est appelée.
fileConsent/invoke OnTeamsFileConsentAsync Lorsque le connecteur reçoit un consentement de fichier carte activité, cette méthode est appelée.
fileConsent/invoke OnTeamsFileConsentDeclineAsync Lorsqu’un utilisateur refuse un consentement de fichier carte, cette méthode est appelée.
actionableMessage/executeAction OnTeamsO365ConnectorCardActionAsync Lorsque le connecteur reçoit un connecteur carte pour Groupes Microsoft 365 activité d’action, cette méthode est appelée.
signin/verifyState OnTeamsSigninVerifyStateAsync Lorsque le connecteur reçoit une signIn activité de vérification de l’état, cette méthode est appelée.
tâche/extraction OnTeamsTaskModuleFetchAsync Vous pouvez remplacer cette méthode dans une classe dérivée pour fournir une logique lorsqu’une boîte de dialogue (appelée module de tâche dans TeamsJS v1.x) est extraite.
task/submit OnTeamsTaskModuleSubmitAsync Vous pouvez remplacer cette méthode dans une classe dérivée pour fournir une logique lors de l’envoi d’un dialogue.

Les activités Invoke répertoriées dans cette section sont destinées aux bots conversationnels dans Teams. Le Kit de développement logiciel (SDK) Bot Framework prend également en charge les activités d’appel spécifiques aux extensions de message. Pour plus d’informations, consultez les extensions de message.

Maintenant que vous vous êtes familiarisé avec les gestionnaires d’activité des bots, voyons comment les bots se comportent différemment en fonction de la conversation et des messages qu’ils reçoivent ou envoient.

Exemple de code

Exemple de nom Description .NET Node.js Python
Bot de conversation Teams Cet exemple d’application montre comment utiliser différents événements de conversation de bot disponibles dans Bot Framework v4. View View View
Échantillons de bottes Ensemble d’exemples Bot Framework v4. View View View

Étape suivante

Concepts de base d’une conversation

Voir aussi