Vue d’ensemble des compétencesSkills overview

s’applique à : SDK v4APPLIES TO: SDK v4

À partir de la version 4.7 du SDK Bot Framework, vous pouvez étendre un bot à l’aide d’un autre bot (une compétence).Starting with version 4.7 of the Bot Framework SDK, you can extend a bot using another bot (a skill). Une compétence peut être consommée par divers autres bots, ce qui en facilite la réutilisation, et vous pouvez ainsi créer un bot orienté utilisateur et l’étendre en consommant vos propres compétences ou des compétences tierces.A skill can be consumed by various other bots, facilitating reuse, and in this way, you can create a user-facing bot and extend it by consuming your own or 3rd party skills.

  • Une compétence est un bot qui peut effectuer un ensemble de tâches pour un autre bot.A skill is a bot that can perform a set of tasks for another bot. Un bot peut être à la fois une compétence et un bot orienté utilisateur.A bot can be both a skill and a user-facing bot.
  • Un consommateur de compétences est un bot qui peut appeler une ou plusieurs compétences.A skill consumer is a bot that can call one or more skills. Un consommateur de compétences orienté utilisateur est également appelé bot racine.A user-facing skill consumer is also called a root bot.
  • Un manifeste de compétence est un fichier JSON qui décrit les actions que la compétence peut effectuer, ses paramètres d’entrée et de sortie, ainsi que ses points de terminaison.A skill manifest is a JSON file that describes the actions the skill can perform, its input and output parameters, and the skill's endpoints.
    • Les développeurs qui n’ont pas accès au code source de la compétence peuvent utiliser les informations du manifeste pour concevoir leur consommateur de compétences.Developers who don't have access to the skill's source code can use the information in the manifest to design their skill consumer.
    • Le schéma de manifeste de compétence est un fichier JSON qui décrit le schéma du manifeste de compétence.The skill manifest schema is a JSON file that describes the schema of the skill manifest. La version actuelle est 2.1.0.The current version is 2.1.0.
    • Découvrez comment implémenter une compétence et comment écrire un manifeste de compétence pour les exemples de manifestes de compétences.See how to implement a skill and how to write a skill manifest for sample skill manifests.

En d’autres termes, l’utilisateur interagit directement avec le bot racine et le bot racine délègue une partie de sa logique de conversation à une compétence.In other words, the user interacts directly with the root bot, and the root bot delegates some of its conversational logic to a skill.

La fonctionnalité de compétences est conçue avec les objectifs ci-dessous :The skills feature is designed so that:

  • Les compétences et les consommateurs communiquent via HTTP à l’aide du protocole de framework du bot.Skills and consumers communicate over HTTP using the bot framework protocol.
  • Un consommateur de compétences peut consommer plusieurs compétences.A skill consumer can consume multiple skills.
  • Un consommateur de compétences peut consommer n’importe quelle compétence, quel que soit le langage utilisé pour implémenter la compétence.A skill consumer can consume a skill regardless of the language used to implement the skill. Par exemple, un bot C# peut consommer une compétence implémentée à l’aide de Python.For example, a C# bot can consume a skill implemented using Python.
  • Une compétence peut également être un consommateur de compétences et appeler d’autres compétences.A skill can also be a skill consumer and call other skills.
  • Les compétences prennent en charge l’authentification utilisateur ; toutefois, l’authentification utilisateur est locale pour la compétence et ne peut pas être transférée à un autre bot.Skills support user authentication; however, user authentication is local to the skill and cannot be transferred to another bot.
  • Les compétences peuvent fonctionner avec l’adaptateur Bot Framework et des adaptateurs personnalisés.Skills can work with both the Bot Framework adapter and custom adapters.

Ce diagramme montre quelques-unes des permutations possibles.This diagram shows some of the possible permutations.

Schéma fonctionnel

Architecture conceptuelleConceptual architecture

Une compétence et un consommateur de compétences sont des bots distincts que vous publiez indépendamment.A skill and skill consumer are separate bots, and you publish them independently.

  • Un consommateur de compétences requiert une logique ajoutée pour la gestion d’une compétence, par exemple quand appeler ou annuler la compétence, et ainsi de suite.A skill consumer requires added logic for managing a skill, such as when to call or cancel the skill, and so on. En plus des objets de bot et d’adaptateur habituels, le consommateur comprend quelques objets liés aux compétences, utilisés pour échanger des activités avec la compétence.In addition to the usual bot and adapter objects, the consumer includes a few skill-related objects, used to exchange activities with the skill. Un consommateur de compétences implémente au moins deux points de terminaison HTTP :A skill consumer implements at least two HTTP endpoints:
    • Un point de terminaison de messagerie reçoit des activités de l’utilisateur ou du canal.A messaging endpoint receives activities from the user or channel. Il s’agit du point de terminaison de messagerie habituel que tous les robots implémentent.This is the usual messaging endpoint that all bots implement.
    • Point de terminaison hôte de compétence pour la réception d’activités d’une compétence.A skill host endpoint for receiving activities from a skill. Il s’agit d’une URL de rappel, l’URL de service à laquelle la compétence répond.This acts as a callback URL, the service URL to which the skill replies. (L’utilisateur de compétence doit associer du code qui reçoit la demande de méthode HTTP de la compétence avec un gestionnaire de compétences.)(The skill consumer needs to pair code that receives the HTTP method request from the skill with a skill handler.)
  • Une compétence nécessite une logique supplémentaire pour envoyer une endOfConversation activité lorsqu’elle se termine, afin que le consommateur de compétences sache quand arrêter le transfert des activités à la compétence.A skill requires added logic to send an endOfConversation activity when it completes, so that the skill consumer knows when to stop forwarding activities to the skill.

Ce diagramme décrit le flux d’activités de l’utilisateur vers le bot racine vers une compétence, et inversement.This diagram outlines the flow of activities from the user to the root bot to a skill and back again.

Diagramme de l'architecture

  1. L’adaptateur du bot racine reçoit les activités de l’utilisateur et les transmet au gestionnaire d’activités du bot racine.The root bot's adapter receives activities from the user and forwards them to the root bot's activity handler. (Les activités de l’utilisateur sont reçues au niveau du point de terminaison de messagerie du bot racine.)(Activities from the user are received at the root bot's messaging endpoint.)
  2. Le bot racine utilise un client HTTP de compétence pour envoyer une activité à la compétence.The root bot uses a skill HTTP client to send an activity to the skill. Le client obtient les informations de conversation consommateur-compétence à partir d’une définition de compétence et d’une fabrique d’ID de conversation de compétence.The client gets the consumer-skill conversation information from a skill definition and a skill conversation ID factory. Il s’agit notamment de l’URL du service que la compétence utilisera pour répondre à l’activité.This includes the service URL that the skill will use to reply to the activity.
  3. L’adaptateur de la compétence reçoit les activités du consommateur de compétences et les transmet au gestionnaire d’activités de la compétence.The skill's adapter receives activities from the skill consumer and forwards them to the skill's activity handler. (Les activités du consommateur sont reçues au niveau du point de terminaison de messagerie du robot de compétences.)(Activities from the consumer are received at the skill bot's messaging endpoint.)
  4. Lorsque la compétence répond, le gestionnaire de compétence du bot racine reçoit l’activité.When the skill responds, the root bot's skill handler receives the activity. Il obtient les informations la conversation racine-utilisateur à partir de la fabrique d’ID de conversation de compétence.It gets the root-user conversation information from the skill conversation ID factory. Il transfère ensuite l’activité à l’adaptateur du bot racine.It then forwards the activity to the root bot's adapter. (Les activités de la compétence sont reçues au niveau du point de terminaison de l’hôte de compétence du robot racine.)(Activities from the skill are received at the root bot's skill host endpoint.)
  5. L’adaptateur du bot racine génère en interne un message proactif pour reprendre la conversation avec l’utilisateur.The root bot's adapter internally generates a proactive message to resume the conversation with the user.
  6. L’adaptateur du bot racine envoie tous les messages de la compétence à l’utilisateur.The root bot's adapter sends any messages from the skill to the user.

Ces objets aident à gérer les compétences et à router le trafic des compétences :These objects help manage skills and route skill traffic:

  • Une compétence Bot Framework décrit les informations de routage pour une compétence et peut être lue à partir du fichier de configuration du consommateur de compétences.A Bot Framework skill describes routing information for a skill and can be read from the skill consumer's configuration file.
  • Un client HTTP de compétence envoie des activités à une compétence.A skill HTTP client sends activities to a skill.
  • Un gestionnaire de compétence reçoit des activités d’une compétence.A skill handler receives activities from a skill.
  • La fabrique d’ID de conversation de compétence effectue une conversion entre la référence de la conversation utilisateur-racine et la référence de la conversation racine-compétence.The skill conversation ID factory translates between the user-root conversation reference and the root-skill conversation reference.
  • Le service Bot Connector fournit une authentification de canal et de bot-à-bot.The Bot Connector service provides both channel and bot-to-bot authentication. À l’aide d’un objet de configuration d’authentification , vous pouvez ajouter la validation des revendications à un consommateur de compétences ou de compétences pour limiter les applications ou les utilisateurs ayant accès.Using an authentication configuration object, you can add claims validation to a skill or skill consumer to limit which applications or users have access.

Les objets client de compétence et gestionnaire de compétence utilisent tous deux la fabrique d’ID de conversation pour effectuer une conversion entre la conversation que le bot racine utilise pour interagir avec l’utilisateur et la conversation que le bot racine utilise pour interagir avec la compétence.The skill client and skill handler objects both use the conversation ID factory to translate between the conversation the root bot uses to interact with the user and the conversation the root bot uses to interact with the skill.

Communication de bot-à-botBot-to-bot communication

Il est important de comprendre certains aspects de cette conception, quel que soit le bot que vous concevez.It's important to understand certain aspects of this design, independent of which bot you're designing.

Références de conversationConversation references

La conversation utilisateur-racine est différente de la conversation racine-compétence.The user-root conversation is different than the root-skill conversation.

La fabrique d’ID de conversation permet de gérer le trafic entre un consommateur de compétences et une compétence.The conversation ID factory helps to manage traffic between a skill consumer and a skill. La fabrique effectue une conversion entre l’ID de la conversation que la racine a avec l’utilisateur et celle qu’elle a avec la compétence.The factory translates between the ID of the conversation the root has with the user and the one it has with the skill. En d’autres termes, elle génère un ID de conversation pour une utilisation entre la racine et la compétence, et récupère l’ID de la conversation utilisateur-racine d’origine à partir de l’ID de la conversation racine-compétence.In other words, it generates a conversation ID for use between the root and the skill, and recovers the original user-root conversation ID from the root-skill conversation ID.

Coordination entre serveursCross-server coordination

Les bots racine et de compétences communiquent via HTTP.The root and skill bots communicate over HTTP. Ainsi, l’instance du bot racine qui reçoit une activité d’une compétence peut ne pas être la même que celle qui a envoyé l’activité de lancement ; en d’autres termes, il est possible que des serveurs différents gèrent ces deux requêtes.So, the instance of the root bot that receives an activity from a skill may not be the same instance that sent the initiating activity; in other words, different servers may handle these two requests.

  • Enregistrez toujours l’état dans le consommateur de compétences avant de transférer une activité à une compétence.Always save state in the skill consumer before forwarding an activity to a skill. Cela garantit que l’instance qui reçoit le trafic d’une compétence peut reprendre là où l’instance précédente s’est arrêtée avant d’appeler la compétence.This ensures that the instance that receives traffic from a skill can pick up where the previous instance left off before it called the skill.
  • Lorsque le gestionnaire de compétence reçoit une activité d’une compétence, il la convertit en une forme appropriée pour le consommateur de compétences et la transmet à l’adaptateur du consommateur.When the skill handler receives an activity from a skill, it translates it into a form appropriate for the skill consumer, and forwards it to the consumer's adapter.

Consommateur de compétences et état de compétenceSkill consumer and skill state

Le consommateur de compétences et la compétence gèrent leur propre état séparément.The skill consumer and skill manage their own state separately. Toutefois, le consommateur crée l’ID de conversation qu’il utilise pour communiquer avec la compétence.However, the consumer creates the conversation ID that it uses to communicate with the skill. Cela peut avoir un effet sur l’état de la conversation dans la compétence.This can have an effect on conversation state in the skill.

Important

Comme indiqué précédemment, lorsque le consommateur de compétences délègue une activité utilisateur à une compétence, une autre instance du consommateur peut recevoir la réponse de la compétence.As noted previously, when the skill consumer delegates a user activity to a skill, a different instance of the consumer may receive the skill response. Le consommateur doit toujours enregistrer l’état de la conversation immédiatement avant de transférer une activité à une compétence.The consumer should always save conversation state immediately before forwarding an activity to a skill.

Authentification de bot-à-botBot-to-bot authentication

À partir de la version 4,11, vous n’avez pas besoin d’un ID d’application et d’un mot de passe pour tester une compétence et un consommateur de compétence localement dans le Emulator.Starting with version 4.11, you do not need an app ID and password to test a skill and skill consumer locally in the Emulator. Un abonnement Azure est toujours requis pour déployer vos compétences sur Azure.An Azure subscription is still required to deploy your skill to Azure.

L’authentification au niveau du service est gérée par le service Bot Connector.Service-level authentication is managed by the Bot Connector service. Le framework utilise des jetons de porteur et des ID d’application de bot pour vérifier l’identité de chaque bot.The framework uses bearer tokens and bot application IDs to verify the identity of each bot. (L’infrastructure bot utilise un objet de configuration d’authentification pour valider l’en-tête d’authentification sur les demandes entrantes.)(The Bot Framework uses an authentication configuration object to validate the authentication header on incoming requests.)

Important

Cela nécessite que tous les robots déployés (l’utilisateur de compétences et les compétences qu’il utilise) disposent d’informations d’identification d’application valides.This requires all deployed bots (the skill consumer and any skills it consumes) to have valid application credentials.

Validation des revendicationsClaims validation

Vous devez ajouter un validateur de revendications à la configuration de l’authentification.You must add a claims validator to the authentication configuration. Les revendications sont évaluées après l’en-tête d’authentification.The claims are evaluated after the authentication header. Levez une erreur ou une exception dans votre code de validation pour refuser la demande.Throw an error or exception in your validation code to reject the request.

Notes

Le bot effectue une validation des revendications s’il possède un ID d’application et un mot de passe. Sinon, la validation des revendications n’est pas effectuée.The bot performs claims validation if it has an app ID and password; otherwise, claims validation is not performed.

Nombreuses sont les raisons pour lesquelles vous pouvez souhaiter refuser une demande par ailleurs authentifiée :There are various reasons you might reject an otherwise authenticated request:

  • Quand le consommateur de compétences doit accepter le trafic uniquement des compétences avec lesquelles il a pu initier une conversation.When the skill consumer should accept traffic only from skills that it may have initiated a conversation with.
  • Quand une compétence fait partie d’un service payant et que les utilisateurs ne figurant pas dans la base de données ne doivent pas y avoir accès.When a skill is part of a paid-for service, and users not in the database should not have access.
  • Quand vous souhaitez restreindre l’accès à la compétence à des consommateurs de compétences spécifiques.When you want to restrict access to the skill to specific skill consumers.

Important

Si vous ne fournissez pas de validateur de revendications, votre bot génère une erreur ou une exception lors de la réception d’une activité à partir d’un autre bot, que votre robot soit une compétence ou un consommateur de compétences.If you don't provide a claims validator, your bot will generate an error or exception upon receiving an activity from another bot, whether your bot is a skill or a skill consumer.

Informations supplémentairesAdditional information

De son point de vue, l’utilisateur interagit avec le bot racine.From the user's perspective, they are interacting with the root bot. Du point de vue de la compétence, le consommateur de compétences est le canal sur lequel elle communique avec l’utilisateur.From the skill's perspective, the skill consumer is the channel over which it communicates with the user.