Écrire un manifeste de compétence

  • Article

S'APPLIQUE À : SDK v4

Un manifeste de compétence est un fichier JSON qui décrit les actions qu'une compétence peut effectuer, ses paramètres d'entrée et de sortie, ainsi que les points de terminaison de la compétence. Le manifeste contient des informations lisibles par une machine qu'un développeur peut utiliser pour accéder à la compétence à partir d'un autre bot.

Cet article décrit les versions prises en charge du schéma du manifeste de compétences Bot Framework.

Version Notes
version 2.2 Mise à jour de certaines propriétés d'URI pour accepter les références d'URI.
version 2.1 Permet de décrire les activités proactives que la compétence peut envoyer et les modèles de répartition qu'elle utilise.
version 2.0 Version d'origine.

Les schémas des manifestes de compétences du Bot Framework utilisent le brouillon 7 du vocabulaire du schéma JSON.

Prérequis

Manifeste de compétence

Le manifeste de compétence contient différentes catégories d’informations :

  • Métadonnées décrivant de manière générale la compétence.
  • Liste des points de terminaison fournis par la compétence.
  • Listes facultatives des activités que la compétence peut recevoir et envoyer de manière proactive.
  • Objet de définitions facultatif contenant des schémas pour les objets référencés par d’autres parties du document.
  • Liste facultative des modèles Dispatch pris en charge par la compétence.

Le tableau suivant décrit le schéma complet de la version 2.2 du manifeste de compétence Bot Framework.

Catégorie/champ Type/format Requis Description
Métadonnées
$id Chaîne Requis Identificateur du manifeste de compétence.
$schema String/URI Requis L’URI HTTPs d’une ressource de schéma JSON qui décrit le format du manifeste. Pour la version 2.2, l'URI est https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json.
copyright Chaîne Facultatif Mention de copyright pour la compétence.
description Chaîne Facultatif Description de la compétence à l’intention des utilisateurs.
iconUrl String/URI-reference Facultatif URI de l’icône à afficher pour la compétence.
license Chaîne Facultatif Contrat de licence de la compétence.
name Chaîne Requis Nom de la compétence.
privacyUrl String/URI-reference Facultatif URI de la description de confidentialité pour la compétence.
publisherName Chaîne Requis Nom de l’éditeur de la compétence.
tags Tableau de chaîne Facultatif Ensemble d’étiquettes pour la compétence. Si des étiquettes sont présentes, chaque étiquette doit être unique.
version Chaîne Requis Version de la compétence décrite par le manifeste.
Points de terminaison
points de terminaison Tableau des points de terminaison Requis Liste des points de terminaison pris en charge par la compétence. Au moins un point de terminaison doit être défini. Chaque point de terminaison doit être unique.
Activités
activities Objet contenant des objets d'activité nommés Facultatif L’ensemble des activités initiales acceptées par la compétence.
activitiesSent Objet contenant des objets d'activité nommés Facultatif Décrit les activités proactives que la compétence peut envoyer.
Définitions
définitions Object Facultatif Objet contenant des sous-schémas pour les objets utilisés dans le manifeste.
Modèles Dispatch
dispatchModels Objet dispatchModels Facultatif Décrit les modèles de langage et les intentions de niveau supérieur pris en charge par la compétence. Voir les modèles de répartition pour le schéma de cet objet.

Points de terminaison

Chaque objet de point de terminaison décrit un point de terminaison pris en charge par la compétence.

Cet exemple liste deux points de terminaison pour une compétence.

"endpoints": [
    {
        "name": "americas",
        "protocol": "BotFrameworkV3",
        "description": "Production endpoint for SkillBot in the Americas",
        "endpointUrl": "http://myskill.contoso.com/api/messages",
        "msAppId": "00000000-0000-0000-0000-000000000000"
    },
    {
        "name": "eu",
        "protocol": "BotFrameworkV3",
        "description": "Production endpoint for SkillBot in Europe",
        "endpointUrl": "http://myskill.contoso.com/api/messages",
        "msAppId": "11111111-0000-0000-0000-000000000000"
    }
],

Objet endpoint

Décrit un point de terminaison pris en charge par la compétence.

Champ Type/format Requis Description
description Chaîne Facultatif Une description de l'état du point de terminaison.
endpointUrl String/URI Requis Point de terminaison de l’URI de la compétence.
msAppId Chaîne Requis Valeur Microsoft AppId (GUID) de la compétence permettant d’authentifier les demandes. Doit correspondre à l'expression régulière :^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$.
name Chaîne Requis Nom unique du point de terminaison.
protocol Chaîne Facultatif Le protocole Bot pris en charge. La valeur par défaut est « BotFrameworkV3 », qui représente la version 3 de l'API Bot Connector. Utilisez la valeur par défaut, sauf si votre compétence utilise spécifiquement un autre protocole.

Activités

Chaque objet d’activité décrit une activité acceptée par la compétence. La compétence commence une action ou une tâche en fonction de l'activité initiale qu'elle reçoit. Le nom associé à l’objet d’activité indique l’action ou la tâche que la compétence effectuera.

Certains types d'activités ont une propriété de valeur permettant de fournir une entrée supplémentaire à la compétence. Lorsque la compétence se termine (achève l'action), elle peut fournir une valeur de retour dans la propriété de valeur de l'activité de fin de conversation associée.

Les types d'activités autorisés sont les suivants : message, événement, appel et autres activités. Une compétence peut recevoir une activité invoke, mais ne peut pas en envoyer.

Vous trouverez ci-dessous un exemple de description d'activité.

"bookFlight": {
    "description": "Books a flight",
    "type": "event",
    "name": "BookFlight",
    "value": {
        "$ref": "#/definitions/bookingInfo"
    },
    "resultValue": {
        "$ref": "#/definitions/bookingInfo"
    }
},

Objet eventActivity

Décrit une activité event acceptée ou envoyée par la compétence. La signification d'une activité événement est définie par son champ de nom, qui est significatif dans le cadre de la compétence.

Champ Type Requise Description
description Chaîne Facultatif Description de l'action que l'événement doit lancer.
name Chaîne Requis Valeur de la propriété de nom de l’activité event.
resultValue Object Facultatif Définition de schéma JSON du type d'objet que l'action peut retourner.
type Chaîne Requis Le type d’activité. Doit être « event ».
value Object Facultatif Définition de schéma JSON du type d’objet que cette action attend comme entrée.

Objet invokeActivity

Décrit une activité invoke acceptée par la compétence. La signification d'une activité appel est définie par son champ de nom, qui est significatif dans le cadre de la compétence.

Champ Type Requise Description
description Chaîne Facultatif Une description de l'action que l'appel doit lancer.
name Chaîne Requis Valeur de la propriété de nom de l’activité invoke.
resultValue Object Facultatif Définition de schéma JSON du type d’objet que l’action associée peut retourner.
type Chaîne Requis Le type d’activité. Doit être « invoke ».
value Object Facultatif Définition de schéma JSON du type d’objet que cette action attend comme entrée.

Objet messageActivity

Décrit une activité message acceptée ou envoyée par la compétence. La propriété de texte de l'activité message contient l'énoncé de l'utilisateur ou du bot.

Champ Type Requise Description
description Chaîne Facultatif Description de l'action
resultValue Object Facultatif Définition de schéma JSON du type d’objet que l’action associée peut retourner.
type Chaîne Requis Le type d’activité. Doit être « message ».
value Object Facultatif Définition de schéma JSON du type d’objet que cette action attend comme entrée.

Objet otherActivities

Décrit tout autre type d'activité accepté ou envoyé par la compétence.

Champ Type Requise Description
type Chaîne Requis Le type d’activité. Doit être un des autres types d'activités Bot Framework : « contactRelationUpdate », « conversationUpdate », « deleteUserData », « endOfConversation », « handoff », « installationUpdate », « messageDelete », « messageReaction », « messageUpdate », « suggestion », « trace » ou « typing ».

L'objet otherActivities peut inclure d'autres propriétés, mais le schéma du manifeste de compétence ne définit pas sa signification.

Définitions

Chaque définition décrit un sous-schéma qui peut être consommé par d’autres parties du document.

Vous trouverez ci-dessous un exemple de sous-schéma pour les informations relatives aux réservations de vols.

"bookingInfo": {
    "type": "object",
    "required": [
        "origin"
    ],
    "properties": {
        "origin": {
            "type": "string",
            "description": "this is the origin city for the flight"
        },
        "destination": {
            "type": "string",
            "description": "this is the destination city for the flight"
        },
        "date": {
            "type": "string",
            "description": "The date for the flight in YYYY-MM-DD format"
        }
    }
},

Modèles Dispatch

Le modèle Dispatch contient une liste de modèles de langage et une liste d’intentions de niveau supérieur prises en charge par la compétence. Il s'agit d'une fonctionnalité avancée qui permet au développeur d'un consommateur de compétences de composer un modèle de langage combinant les fonctionnalités des bots du consommateur et de la compétence.

Chaque modèle de langage utilise le format de fichier .lu ou .qna. Pour plus d'informations sur ces formats, consultez les formats de fichier .lu et les formats de fichier .qna.

Un nom de paramètres régionaux est une combinaison d’un code de culture ISO 639 à deux lettres minuscules associé à une langue et d’un code de sous-culture ISO 3166 facultatif à deux lettres majuscules, associé à un pays ou une région, par exemple « en » ou « en-US ».

Champ Type Requise Description
intentions Tableau de chaîne Facultatif Une liste des intentions de niveau supérieur prises en charge par la compétence. Chaque intention doit être unique.
languages Objet contenant des tableaux intitulés languageModel Facultatif Une liste des modèles de langage pris en charge par la compétence. Chaque nom représente la région à laquelle les modèles de langage sont destinés. En outre, le tableau contient les modèles de langage pour ces paramètres régionaux. Un modèle Dispatch doit prendre en charge au moins un paramètre régional. Chaque paramètre régional dans le champ des langages doit être unique.

Il s'agit d'un exemple de modèle Dispatch contenant deux modèles de langage répartis sur trois paramètres régionaux. Il décrit également deux intentions de niveau supérieur que la compétence peut reconnaître.

"dispatchModels": {
    "languages": {
        "en": [
            {
                "name": "SkillBot LU (English)",
                "contentType": "application/lu",
                "url": "http://sample.com/SkillBot-en.lu",
                "description": "English language model for the skill"
            },
            {
                "name": "SkillBot QnA LU (English)",
                "contentType": "application/qna",
                "url": "http://sample.com/SkillBot-QnA-en.qna",
                "description": "English language model for the skill (QnAMaker)"
            }
        ],
        "es-ES": [
            {
                "name": "SkillBot LU (Spanish-Spain)",
                "contentType": "application/lu",
                "url": "http://sample.com/SkillBot-es-ES.lu",
                "description": "Spanish (Spain) language model for the skill"
            },
            {
                "name": "SkillBot QnA LU (Spanish-Spain)",
                "contentType": "application/qna",
                "url": "http://sample.com/SkillBot-QnA-es-ES.qna",
                "description": "Spanish (Spain) language model for the skill (QnAMaker)"
            }
        ],
        "es-MX": [
            {
                "name": "SkillBot LU (Spanish-Mexico)",
                "contentType": "application/lu",
                "url": "http://sample.com/SkillBot-es-MX.lu",
                "description": "Spanish (Mexico) language model for the skill"
            },
            {
                "name": "SkillBot QnA LU (Spanish-Mexico)",
                "contentType": "application/qna",
                "url": "http://sample.com/SkillBot-QnA-es-MX.qna",
                "description": "Spanish (Mexico) language model for the skill (QnAMaker)"
            }
        ]
    },
    "intents": [
        "bookFlight",
        "getWeather"
    ]
},

Objet languageModel

Décrit un modèle de langage pour une culture donnée. Le nom est un nom de paramètre régional.

Champ Type/format Requis Description
contentType Chaîne Requis Type de modèle de langage.
description Chaîne Facultatif Une description du modèle de langage.
name Chaîne Requis Nom du modèle de langage.
url String/URI-reference Requis L’URL du modèle de langage.

Exemple de manifeste

Vous trouverez ci-dessous un exemple complet de manifeste v2.2 pour une compétence qui expose plusieurs activités.

{
    "$schema": "https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json",
    "$id": "SkillBot",
    "name": "Sample skill definition that can handle multiple types of activities",
    "version": "1.0",
    "description": "This is a sample skill definition for multiple activity types",
    "publisherName": "Microsoft",
    "privacyUrl": "https://myskill.contoso.com/privacy.html",
    "copyright": "Copyright (c) Microsoft Corporation. All rights reserved.",
    "license": "",
    "iconUrl": "skillIcon.png",
    "tags": [
        "sample",
        "travel",
        "weather"
    ],
    "endpoints": [
        {
            "name": "americas",
            "protocol": "BotFrameworkV3",
            "description": "Production endpoint for SkillBot in the Americas",
            "endpointUrl": "http://myskill.contoso.com/api/messages",
            "msAppId": "00000000-0000-0000-0000-000000000000"
        },
        {
            "name": "eu",
            "protocol": "BotFrameworkV3",
            "description": "Production endpoint for SkillBot in Europe",
            "endpointUrl": "http://myskill.contoso.com/api/messages",
            "msAppId": "11111111-0000-0000-0000-000000000000"
        }
    ],
    "dispatchModels": {
        "languages": {
            "en": [
                {
                    "name": "SkillBot LU (English)",
                    "contentType": "application/lu",
                    "url": "http://sample.com/SkillBot-en.lu",
                    "description": "English language model for the skill"
                },
                {
                    "name": "SkillBot QnA LU (English)",
                    "contentType": "application/qna",
                    "url": "http://sample.com/SkillBot-QnA-en.qna",
                    "description": "English language model for the skill (QnAMaker)"
                }
            ],
            "es-ES": [
                {
                    "name": "SkillBot LU (Spanish-Spain)",
                    "contentType": "application/lu",
                    "url": "http://sample.com/SkillBot-es-ES.lu",
                    "description": "Spanish (Spain) language model for the skill"
                },
                {
                    "name": "SkillBot QnA LU (Spanish-Spain)",
                    "contentType": "application/qna",
                    "url": "http://sample.com/SkillBot-QnA-es-ES.qna",
                    "description": "Spanish (Spain) language model for the skill (QnAMaker)"
                }
            ],
            "es-MX": [
                {
                    "name": "SkillBot LU (Spanish-Mexico)",
                    "contentType": "application/lu",
                    "url": "http://sample.com/SkillBot-es-MX.lu",
                    "description": "Spanish (Mexico) language model for the skill"
                },
                {
                    "name": "SkillBot QnA LU (Spanish-Mexico)",
                    "contentType": "application/qna",
                    "url": "http://sample.com/SkillBot-QnA-es-MX.qna",
                    "description": "Spanish (Mexico) language model for the skill (QnAMaker)"
                }
            ]
        },
        "intents": [
            "bookFlight",
            "getWeather"
        ]
    },
    "activities": {
        "bookFlight": {
            "description": "Books a flight",
            "type": "event",
            "name": "BookFlight",
            "value": {
                "$ref": "#/definitions/bookingInfo"
            },
            "resultValue": {
                "$ref": "#/definitions/bookingInfo"
            }
        },
        "getWeather": {
            "description": "Retrieves and returns the weather for the user's location",
            "type": "invoke",
            "name": "GetWeather",
            "value": {
                "$ref": "#/definitions/location"
            },
            "resultValue": {
                "$ref": "#/definitions/weatherReport"
            }
        },
        "message": {
            "type": "message",
            "description": "Receives the user's' utterance and attempts to resolve it using the skill's LU models"
        },
        "typing": {
            "type": "typing"
        },
        "conversationUpdate": {
            "type": "conversationUpdate"
        }
    },
    "definitions": {
        "localeValue": {
            "type": "object",
            "properties": {
                "locale": {
                    "type": "string",
                    "description": "The current user's locale ISO code"
                }
            }
        },
        "bookingInfo": {
            "type": "object",
            "required": [
                "origin"
            ],
            "properties": {
                "origin": {
                    "type": "string",
                    "description": "this is the origin city for the flight"
                },
                "destination": {
                    "type": "string",
                    "description": "this is the destination city for the flight"
                },
                "date": {
                    "type": "string",
                    "description": "The date for the flight in YYYY-MM-DD format"
                }
            }
        },
        "weatherReport": {
            "type": "array",
            "description": "Array of forecasts for the next week.",
            "items": [
                {
                    "type": "string"
                }
            ]
        },
        "location": {
            "type": "object",
            "description": "Location metadata",
            "properties": {
                "latitude": {
                    "type": "number",
                    "title": "Latitude"
                },
                "longitude": {
                    "type": "number",
                    "title": "Longitude"
                },
                "postalCode": {
                    "type": "string",
                    "title": "Postal code"
                }
            }
        }
    },
    "activitiesSent": {
        "flightUpdated": {
            "type": "event",
            "name": "FlightUpdated",
            "description": "Event which is sent by the skill when there is an update in flight info",
            "value": {
                "type": "object",
                "description": "Flight update information",
                "properties": {
                    "flightNumber": {
                        "type": "string"
                    },
                    "departureDate": {
                        "type": "string",
                        "description": "The departure date for the flight in YYYY-MM-DD format"
                    },
                    "departureTime": {
                        "type": "string",
                        "description": "The departure time for the flight in HH-MM format"
                    }
                }
            }
        }
    }
}

Étapes suivantes