Conversations pilotées par les événements à l’aide d’un gestionnaire d’activités

  • Article
  • 16 minutes de lecture

S’APPLIQUE À : Kit de développement logiciel (SDK) v4

Un gestionnaire d’activités est un moyen piloté par les événements d’organiser la logique conversationnelle de votre bot. Chaque type ou sous-type d’activité différent représente un type différent d’événement conversationnel. En cache, le gestionnaire de tour du bot appelle le gestionnaire d’activité individuel pour le type d’activité qu’il a reçu.

Par exemple, si le bot reçoit une activité de message, le gestionnaire de tours voit cette activité entrante et l’envoie au gestionnaire d’activité d’activité de message activé. Lors de la création de votre bot, la logique de votre bot pour la gestion et la réponse aux messages s’effectue dans ce cas sur le gestionnaire d’activité de message . De même, votre logique de gestion des membres ajoutés à la conversation s’affiche dans votre gestionnaire sur les membres ajoutés , qui est appelé chaque fois qu’un membre est ajouté à la conversation.

Pour d’autres façons d’organiser votre logique de bot, consultez la section logique du bot dans le fonctionnement des bots.

Pour implémenter votre logique pour ces gestionnaires, vous allez remplacer ces méthodes dans votre bot, par exemple dans la section exemple de gestionnaire d’activités ci-dessous. Pour chacun de ces gestionnaires, il n’existe aucune implémentation de base. Il vous suffit donc d’ajouter la logique souhaitée dans votre remplacement.

Dans certaines situations, vous souhaiterez remplacer le gestionnaire de tour de base, comme l’enregistrement de l’état à la fin d’un tour. Dans ce cas, veillez à appeler d’abord await base.OnTurnAsync(turnContext, cancellationToken); pour vous assurer que l’implémentation de base est OnTurnAsync exécutée avant votre code supplémentaire. Cette implémentation de base est, entre autres, responsable de l’appel du reste des gestionnaires d’activités tels que OnMessageActivityAsync.

Gestion des activités

La logique du bot traite les activités entrantes à partir d’un ou plusieurs canaux et génère des activités sortantes en réponse.

La logique principale du bot est définie dans le code du bot. Pour implémenter un bot en tant que gestionnaire d’activités, dérivez votre classe de bot à partir de ActivityHandlerlaquelle implémente l’interface IBot . ActivityHandler définit différents gestionnaires pour différents types d’activités, tels que OnMessageActivityAsync, et OnMembersAddedAsync. Ces méthodes sont protégées, mais peuvent être substituées, car nous dérivations de ActivityHandler.

Les gestionnaires définis sont ActivityHandler les suivants :

Événement Gestionnaire Description
Tout type d’activité reçu OnTurnAsync Appelle l’un des autres gestionnaires, en fonction du type d’activité reçue.
Activité de message reçue OnMessageActivityAsync Remplacez-la pour gérer une message activité.
Activité de mise à jour de conversation reçue OnConversationUpdateActivityAsync Sur une conversationUpdate activité, appelle un gestionnaire si des membres autres que le bot ont rejoint ou quitté la conversation.
Les membres non-bot ont rejoint la conversation OnMembersAddedAsync Remplacez cette option pour gérer les membres qui rejoignent une conversation.
Les membres non-bot ont quitté la conversation OnMembersRemovedAsync Remplacez cette option pour gérer les membres quittant une conversation.
Activité d’événement reçue OnEventActivityAsync Sur une event activité, appelle un gestionnaire spécifique au type d’événement.
Activité d’événement de réponse de jeton reçue OnTokenResponseEventAsync Remplacez-la pour gérer les événements de réponse de jeton.
Activité d’événement sans réponse de jeton reçue OnEventAsync Remplacez-la pour gérer d’autres types d’événements.
Activité de réaction de message reçue OnMessageReactionActivityAsync Sur une messageReaction activité, appelle un gestionnaire si une ou plusieurs réactions ont été ajoutées ou supprimées d’un message.
Réactions de message ajoutées à un message OnReactionsAddedAsync Remplacez cette option pour gérer les réactions ajoutées à un message.
Réactions de message supprimées d’un message OnReactionsRemovedAsync Remplacez cette option pour gérer les réactions supprimées d’un message.
Activité de mise à jour d’installation reçue OnInstallationUpdateActivityAsync Sur une installationUpdate activité, appelle un gestionnaire en fonction de l’installation ou de la désinstallation du bot.
Bot installé OnInstallationUpdateAddAsync Remplacez-la pour ajouter une logique pour le moment où le bot est installé au sein d’une unité d’organisation.
Bot désinstallé OnInstallationUpdateRemoveAsync Remplacez-la pour ajouter une logique pour le moment où le bot est désinstallé au sein d’une unité d’organisation.
Autre type d’activité reçu OnUnrecognizedActivityTypeAsync Remplacez-la pour gérer n’importe quel type d’activité autrement non géré.

Ces différents gestionnaires ont un turnContext qui fournit des informations sur l’activité entrante, qui correspond à la requête HTTP entrante. Les activités peuvent être de différents types, de sorte que chaque gestionnaire fournit une activité fortement typée dans son paramètre de contexte de tour ; dans la plupart des cas, OnMessageActivityAsync sera toujours géré et est généralement le plus courant.

Comme dans les versions 4.x précédentes de ce framework, il existe également la possibilité d’implémenter la méthode OnTurnAsyncpublique. Actuellement, l’implémentation de base de cette méthode gère la vérification des erreurs, puis appelle chacun des gestionnaires spécifiques (comme les deux que nous définissons dans cet exemple) en fonction du type d’activité entrante. Dans la plupart des cas, vous pouvez laisser cette méthode seule et utiliser les gestionnaires individuels, mais si votre situation nécessite une implémentation personnalisée de OnTurnAsync, il s’agit toujours d’une option.

Important

Si vous remplacez la OnTurnAsync méthode, vous devez appeler base.OnTurnAsync pour obtenir l’implémentation de base afin d’appeler tous les autres On<activity>Async gestionnaires ou d’appeler ces gestionnaires vous-même. Sinon, ces gestionnaires ne seront pas appelés et ce code ne sera pas exécuté.

Exemple de gestionnaire d’activités

Par exemple, vous pouvez gérer les membres ajoutés pour accueillir les utilisateurs à une conversation et gérer les messages pour renvoyer les messages qu’ils envoient au bot.

public class EchoBot : ActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        var replyText = $"Echo: {turnContext.Activity.Text}";
        await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
    }

    protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
    {
        var welcomeText = "Hello and welcome!";
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text(welcomeText, welcomeText), cancellationToken);
            }
        }
    }
}

Étapes suivantes

  • Le canal Microsoft Teams introduit certaines activités spécifiques à Teams que votre bot devra prendre en charge pour fonctionner correctement avec Teams. Pour comprendre les concepts clés du développement de bots pour Microsoft Teams, consultez le fonctionnement des bots Microsoft Teams
  • Un gestionnaire d’activités est un bon moyen de concevoir un bot qui n’a pas besoin de suivre l’état conversationnel entre les tours. La bibliothèque de dialogues fournit des moyens de gérer une conversation de longue durée avec l’utilisateur.