Principes de base du service Bot Framework

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

Un bot est une application avec laquelle les utilisateurs interagissent par le biais d’une conversation textuelle, graphique (cartes ou images) ou vocale. Azure Bot Service est une plateforme cloud. Il héberge des bots et les rend disponibles pour les canaux, tels que Microsoft Teams, Facebook ou Slack.

Bot Framework Service, qui est un composant d’Azure Bot Service, envoie des informations entre l’application connectée au bot de l’utilisateur et le bot. Chaque canal peut inclure des informations supplémentaires dans les activités qu’ils envoient. Avant de créer des bots, il est important de comprendre comment un bot utilise les objets d’activité pour communiquer avec ses utilisateurs.

Ce diagramme illustre deux types d’activités, la mise à jour de conversation et le message, qui peuvent être échangés lorsqu’un utilisateur communique avec un bot d’écho simple.

activity diagram

Bot Framework Service envoie une mise à jour de conversation lorsqu’une partie rejoint la conversation. Par exemple, lors du démarrage d’une conversation avec l’émulateur Bot Framework, vous pouvez voir deux activités de mise à jour de conversation (une pour l’utilisateur joignant la conversation et une pour la jointure de bot). Pour distinguer ces activités de mise à jour de conversation, vérifiez qui est inclus dans les membres ajoutés à la propriété de l’activité.

L’activité de message contient des informations de conversation entre les parties. Dans un exemple de bot d’écho, les activités de message transfèrent du texte simple et le canal rend ce texte. L’activité de message peut également contenir du texte à prononcer, des actions suggérées ou des cartes à afficher.

Conseil

Il est à chaque canal d’implémenter le protocole Bot Framework et comment chaque canal le fait peut être un peu différent. Par exemple, certains canaux envoient d’abord des activités de mise à jour de conversation et des activités de mise à jour de conversation après avoir envoyé la première activité de message. Un canal peut inclure le bot et l’utilisateur dans une activité de mise à jour de conversation, tandis qu’un autre peut envoyer deux activités de mise à jour de conversation.

Dans cet exemple, le bot crée et envoie une activité de message en réponse à l’activité de message entrant reçu. Toutefois, un bot peut répondre d’une autre manière à une activité de message reçue ; il n’est pas rare qu’un bot réponde à une activité de mise à jour de conversation en envoyant du texte d’accueil dans une activité de message. Pour plus d’informations, consultez comment accueillir un utilisateur.

Kit de développement logiciel (SDK) Bot Framework

Le Kit de développement logiciel (SDK) Bot Framework vous permet de créer des bots qui peuvent être hébergés sur Azure Bot Service. Le service définit une API REST et un protocole d’activité pour la façon dont votre bot et vos canaux ou utilisateurs peuvent interagir. Le Kit de développement logiciel (SDK) s’appuie sur cette API REST et fournit une abstraction du service afin que vous puissiez vous concentrer sur la logique conversationnelle. Bien que vous n’ayez pas besoin de comprendre le service REST pour utiliser le Kit de développement logiciel (SDK), la compréhension de certaines de ses fonctionnalités peut être utile.

Les bots sont des applications qui ont une interface conversationnelle. Les bots peuvent être utilisés pour faire passer des tâches répétitives et simples, comme la réservation de table ou le recueil d’informations de profil, vers des systèmes automatisés qui ne nécessitent plus d’intervention humaine directe. Les utilisateurs conversent avec le bot à l’aide de texte, de cartes interactives et avec la voix. Une interaction avec un bot peut se composer d’une question-réponse rapide, ou il peut s’agir d’une conversation plus sophistiquée fournissant un accès à des services de manière plus intelligente.

Notes

La prise en charge des fonctionnalités fournies par le Kit de développement logiciel (SDK) et l’API REST varient selon le canal. Vous pouvez tester votre bot à l’aide de l’émulateur Bot Framework, mais vous devez également tester toutes les fonctionnalités de votre bot sur chaque canal dans lequel vous envisagez de rendre votre bot disponible.

Les interactions impliquent l’échange d’activités, qui sont gérées à tour de tour.

Activités

Chaque interaction entre l’utilisateur (ou un canal) et le bot est représentée en tant qu’activité. Le schéma d’activité Bot Framework définit les activités qui peuvent être échangées entre un utilisateur ou un canal et un bot. Les activités peuvent représenter des notifications de texte ou de synthèse vocale humaine, des notifications d’application à application, des réactions à d’autres messages, et ainsi de suite.

Tours

Dans une conversation, les gens parlent un à la fois, tour à tour. En général, un bot réagit à l’entrée utilisateur. Dans le kit SDK Bot Framework, un tour désigne l’activité entrante de l’utilisateur dans le bot et toute activité que le bot renvoie à l’utilisateur comme réponse immédiate. Vous pouvez considérer un tour comme le traitement associé au bot recevant une activité donnée.

Par exemple, un utilisateur peut demander à un bot d’effectuer une certaine tâche. Le bot peut répondre avec une question pour obtenir plus d’informations sur la tâche, à quel moment ce tour se termine. Au prochain tour, le bot reçoit un nouveau message de l’utilisateur qui peut contenir la réponse à la question du bot, ou il peut représenter un changement de sujet ou une demande d’ignorer la demande initiale pour effectuer la tâche.

Structure d’application bot

Le Kit de développement logiciel (SDK) définit une classe de bot qui gère le raisonnement conversationnel de l’application bot. Classe de bot :

  • Reconnaît et interprète l’entrée de l’utilisateur.
  • Raisons de l’entrée et effectue des tâches pertinentes.
  • Génère des réponses sur ce que le bot fait ou a fait.

Le Kit de développement logiciel (SDK) définit également une classe d’adaptateur qui gère la connectivité avec les canaux. Adaptateur :

  • Fournit une méthode permettant de gérer les demandes provenant des requêtes et les méthodes permettant de générer des requêtes sur le canal de l’utilisateur.
  • Inclut un pipeline d’intergiciel, qui inclut le traitement de tour en dehors du gestionnaire de tour de votre bot.
  • Appelle le gestionnaire de tour du bot et intercepte les erreurs qui ne sont pas gérées dans le gestionnaire de tour.

En outre, les bots doivent souvent récupérer et stocker l’état chaque tour. Cela est géré par le biais de classes d’accesseur de stockage, de bot et de propriété . Le Kit de développement logiciel (SDK) ne fournit pas de stockage intégré, mais fournit des abstractions pour le stockage et quelques implémentations d’une couche de stockage. La rubrique d’état de gestion décrit ces fonctionnalités d’état et de stockage.

A bot has connectivity and reasoning elements, and an abstraction for state

Le Kit de développement logiciel (SDK) ne nécessite pas d’utiliser une couche d’application spécifique pour envoyer et recevoir des demandes web. Bot Framework contient des modèles et des exemples pour ASP.NET (C#), restify (JavaScript) et aiohttp (Python). Toutefois, vous pouvez choisir d’utiliser une couche d’application différente pour votre application.

Lorsque vous créez un bot à l’aide du Kit de développement logiciel (SDK), vous fournissez le code pour recevoir le trafic HTTP et le transférer à l’adaptateur. Bot Framework fournit quelques modèles et exemples que vous pouvez utiliser pour développer vos propres bots.

Logique du bot

L’objet bot contient le raisonnement conversationnel ou la logique d’un tour et expose un gestionnaire de tour, qui est la méthode qui peut accepter les activités entrantes à partir de l’adaptateur de bot.

Le Kit de développement logiciel (SDK) fournit deux paradigmes différents pour gérer votre logique de bot.

  • Les gestionnaires d’activités fournissent un modèle piloté par les événements dans lequel les types d’activité entrants et les sous-types sont les événements. Cela peut être bon pour les bots qui ont des interactions limitées et courtes avec l’utilisateur.
    • Utilisez un gestionnaire d’activités et implémentez des gestionnaires pour chaque type d’activité ou sous-type auquel votre bot reconnaît et réagit.
    • Utilisez un gestionnaire d’activités Teams pour créer des bots qui peuvent se connecter au canal Teams. (Le canal Teams nécessite que le bot gère un comportement spécifique au canal.)
  • La bibliothèque de dialogues fournit un modèle basé sur l’état pour gérer une conversation longue avec l’utilisateur.
  • Implémentez votre propre classe de bot et fournissez votre propre logique pour gérer chaque tour. Découvrez comment créer vos propres invites pour collecter les entrées utilisateur pour obtenir un exemple de ce que cela peut ressembler.

Adaptateur de bot

L’adaptateur a une méthode d’activité de processus pour démarrer un tour.

  • Il prend le corps de la requête (la charge utile de la requête, traduite en activité) et l’en-tête de requête en tant qu’arguments.
  • Elle vérifie si l’en-tête d’authentification est valide.
  • Il crée un objet de contexte pour le tour.
  • Il exécute cela via son pipeline d’intergiciel .
  • Il envoie l’activité au gestionnaire de tour de l’objet bot.

L’adaptateur également :

  • Met en forme et envoie des activités de réponse. Ces réponses sont généralement des messages pour l’utilisateur, mais peuvent également inclure des informations à consommer directement par le canal de l’utilisateur.
  • Surfaces d’autres méthodes fournies par l’API REST Bot Connector, telles que le message de mise à jour et le message de suppression.
  • Intercepte les erreurs ou exceptions qui ne sont pas interceptées pour le tour.

Contexte de tour

L’objet de contexte de tour fournit des informations sur l’activité, comme l’expéditeur et le destinataire, le canal, et d’autres données nécessaires pour traiter l’activité. Il permet également d’ajouter des informations pendant le tour entre les différentes couches du bot.

Le contexte de tour est l’une des abstractions les plus importantes du SDK. Non seulement il transporte l’activité entrante vers tous les composants middleware et la logique d’application, mais fournit également le mécanisme dans lequel les composants de middleware et la logique bot peuvent envoyer des activités sortantes.

Middlewares

Les intergiciels sont très similaires à n’importe quel autre intergiciel de messagerie, et comprennent un ensemble linéaire de composants qui sont exécutés dans un ordre précis, ce qui donne à chacun une chance d’agir sur l’activité. La dernière étape du pipeline d’intergiciels est un rappel au gestionnaire de tours, sur la classe du bot avec laquelle l’application s’est inscrite auprès de la méthode de traitement d’activité de l’adaptateur. Middleware implémente une méthode d’activation que l’adaptateur appelle.

Le gestionnaire de tour prend un contexte de tour comme argument, généralement la logique d’application s’exécutant à l’intérieur de la fonction de gestionnaire de tour traite le contenu de l’activité entrante et génère une ou plusieurs activités en réponse, en envoyant celles-ci à l’aide de la fonction d’activité d’envoi sur le contexte de tour. Appelez l’envoi d’activité sur le contexte de tour entraîne l’appel des composants des intergiciels sur les activités sortantes. Les composants middleware s’exécutent avant et après la fonction de gestionnaire de tour du bot. L’exécution est intrinsèquement imbriquée et, par conséquent, parfois appelée être comme une oignon.

La rubrique intergiciel décrit le middleware en profondeur.

État et stockage du bot

Comme avec d’autres applications web, un bot est intrinsèquement sans état. L’état au sein d’un bot suit les mêmes paradigmes que les applications web modernes, et le Kit de développement logiciel (SDK) Bot Framework fournit des abstractions de gestion de la couche de stockage et d’état pour faciliter la gestion de l’état.

La rubrique d’état de gestion décrit ces fonctionnalités d’état et de stockage.

Point de terminaison de messagerie et approvisionnement

En règle générale, votre application a besoin d’un point de terminaison REST auquel recevoir des messages. Il devra également provisionner des ressources pour votre bot conformément à la plateforme que vous décidez d’utiliser.

Suivez le guide de démarrage rapide Créer un bot pour créer et tester un bot d’écho simple.

Détails HTTP

Les activités arrivent dans le bot à partir du service Bot Framework via une requête HTTP POST. Le bot répond à la requête POST entrante avec un code d’état HTTP 200. Les activités sont envoyées du bot au canal dans une requête HTTP POST séparée vers le service Bot Framework. Leur réception génère un code d’état HTTP 200.

Le protocole ne spécifie pas l’ordre dans lequel ces requêtes POST et leurs accusés de réception sont effectués. Toutefois, pour s’adapter aux infrastructures de service HTTP courantes, ces demandes sont généralement imbriquées, ce qui signifie que la requête HTTP sortante est effectuée à partir du bot dans le périmètre de la requête HTTP entrante. Ce modèle est illustré dans le diagramme précédent. Dans la mesure où il existe deux connexions HTTP distinctes à la suite, le modèle de sécurité doit couvrir les deux.

Notes

Le bot a 15 secondes pour reconnaître l’appel avec un état 200 sur la plupart des canaux. Si le bot ne répond pas dans les 15 secondes, une erreur HTTP GatewayTimeout (504) se produit.

Pile de traitement d’une activité

Examinons le diagramme de séquence précédent avec un focus sur l’arrivée d’une activité de message.

activity processing stack

Dans l’exemple ci-dessus, le bot a répondu à l’activité de message avec une autre activité de message contenant le même message texte. Le traitement commence par la requête HTTP POST. Les informations de l’activité sont transportées sous la forme d’une charge JSON arrivant sur le serveur Web. En C#, il s’agit généralement d’un projet ASP.NET, dans un projet JavaScript Node.js il est probable qu’il s’agit de l’une des infrastructures populaires telles que Express ou restify.

L’adaptateur, un composant intégré du Kit de développement logiciel (SDK), est l’élément central du runtime du Kit de développement logiciel (SDK). L’activité est transmise sous forme de code JSON dans le corps HTTP POST. Ce JSON est désérialisé pour créer l’objet d’activité qui est ensuite remis à l’adaptateur via sa méthode d’activité de processus . Lors de la réception de l’activité, l’adaptateur crée un contexte de tour et appelle l’intergiciel.

Comme mentionné ci-dessus, le contexte de tour fournit le mécanisme pour permettre au bot d’envoyer des activités sortantes, le plus souvent en réponse à une activité entrante. Pour ce faire, le contexte de tour fournit des méthodes de réponse d’envoi, de mise à jour et de suppression d’activité . Chaque méthode de réponse s’exécute dans un processus asynchrone.

Important

Le thread qui traite le tour de bot principal se charge de supprimer l’objet de contexte quand il prend fin. Veillez à exécuter une opération await sur tous les appels d’activité, afin que le thread principal attende l’activité générée avant de terminer son traitement et de supprimer le contexte de tour. Sinon, si une réponse (et ses gestionnaires) prend un certain temps et essaie d’agir sur l’objet de contexte, elle risque de recevoir une erreur de type contexte supprimé.

Modèles de bot

Vous devez choisir l’utilisation de la couche application pour votre application ; Toutefois, Bot Framework possède des modèles et des exemples pour ASP.NET (C#), restify (JavaScript) et aiohttp (Python). La documentation est écrite en supposant que vous utilisez l’une de ces plateformes, mais le Kit de développement logiciel (SDK) ne vous nécessite pas. Consultez le guide de démarrage rapide Créer un bot pour obtenir des instructions sur l’accès et l’installation des modèles.

Un bot est une application web et des modèles sont fournis pour chaque version de langage du Kit de développement logiciel (SDK). Tous les modèles fournissent une implémentation et un adaptateur de point de terminaison par défaut. Chaque modèle comprend les éléments suivants :

  • Provisionnement des ressources
  • Implémentation de point de terminaison HTTP spécifique au langage qui route les activités entrantes vers un adaptateur.
  • Objet d’adaptateur
  • Objet bot

La principale différence entre les différents types de modèles est dans l’objet bot. Les modèles sont les suivants :

  • Bot vide
    • Inclut un gestionnaire d’activités qui accueille un utilisateur dans la conversation en envoyant un message « hello world » au premier tour de la conversation.
  • Bot d’écho
    • Utilise un gestionnaire d’activités pour accueillir les utilisateurs et renvoyer l’entrée utilisateur.
  • Bot principal
    • Rassemble de nombreuses fonctionnalités du Kit de développement logiciel (SDK) et illustre les meilleures pratiques pour un bot.
    • Utilise un gestionnaire d’activités pour accueillir les utilisateurs.
    • Utilise une boîte de dialogue de composant et des dialogues enfants pour gérer la conversation.
    • Les dialogues utilisent les fonctionnalités Language Understanding (LUIS) et QnA Maker.

Informations supplémentaires

Gestion des ressources de bot

Vous devez gérer les ressources de votre bot, telles que son ID d’application et son mot de passe, ainsi que des informations pour tous les services connectés. Lorsque vous déployez votre bot, il aura besoin d’un accès sécurisé à ces informations. Pour éviter toute complexité, la plupart des articles du Kit de développement logiciel (SDK) Bot Framework ne décrivent pas comment gérer ces informations.

Adaptateurs de canal

Le Kit de développement logiciel (SDK) vous permet également d’utiliser des adaptateurs de canal, dans lesquels l’adaptateur lui-même effectue également les tâches que le service Bot Connector effectuerait normalement pour un canal.

Le Kit de développement logiciel (SDK) fournit quelques adaptateurs de canal dans certaines langues. D’autres adaptateurs de canal sont disponibles via les référentiels Botkit et Community. Pour plus d’informations, consultez la table des canaux et des adaptateurs du référentiel sdk Bot Framework.

The Bot Connector REST API

Le Kit de développement logiciel (SDK) Bot Framework encapsule et s’appuie sur l’API REST Bot Connector. Si vous souhaitez comprendre les requêtes HTTP sous-jacentes qui prennent en charge le Kit de développement logiciel (SDK), consultez l’authentification du connecteur et les articles associés. Les activités qu’un bot envoie et reçoit sont conformes au schéma d’activité Bot Framework.

Étapes suivantes