Escritura de un manifiesto de aptitud v2.1How to write a v2.1 skill manifest

se aplica a: SDK V4APPLIES TO: SDK v4

Un manifiesto de aptitud es un archivo JSON que describe las actividades que puede realizar la aptitud, sus parámetros de entrada y salida y sus puntos de conexión.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. El manifiesto contiene la información que necesita un desarrollador para tener acceso a la aptitud desde otro bot.The manifest contains the information a developer needs to access the skill from another bot. Con la versión 2.1 del esquema del manifiesto de aptitud, el manifiesto también puede describir actividades proactivas y la aptitud puede enviar y distribuir los modelos que dicha aptitud usa.With v2.1 of the skill manifest schema, the manifest can also describe proactive activities the skill can send and dispatch models the skill uses.

En este artículo se describe la versión 2,1 del esquema del manifiesto de aptitudes de bot Framework.This article describes version 2.1 of the Bot Framework skill manifest schema. Para obtener una descripción de la versión 2,0, consulte Cómo escribir un manifiesto de habilidad v 2.0.For a description of version 2.0, see how to Write a v2.0 skill manifest.

El esquema del manifiesto de aptitud de Bot Framework usa el borrador 7 del vocabulario del esquema JSON.The Bot Framework skill manifest schema uses draft 7 of the JSON schema vocabulary.

PrerrequisitosPrerequisites

El manifiesto de aptitudThe skill manifest

El manifiesto de aptitud contiene diferentes categorías de información:The skill manifest contains different categories of information:

  • Metadatos que describen la aptitud a nivel general.Metadata that describes the skill at a general level.
  • Una lista de los puntos de conexión proporcionados por la aptitud.A list of the endpoints that the skill provides.
  • Listas opcionales de las actividades que la aptitud puede recibir y enviar de forma proactiva.Optional lists of the activities the the skill can receive and proactively send.
  • Un objeto definitions opcional que contiene esquemas para objetos a los que otras partes del documento hacen referencia.An optional definitions object that contains schemas for objects referenced by other parts of the document.
  • Una lista opcional de los modelos de distribución que admite la aptitud.An optional list of the dispatch models the skill supports.

A continuación puede ver el esquema completo para v2.1 del manifiesto de aptitud de Bot Framework.The following is the full schema for v2.1 of the Bot Framework skill manifest.

Categoría/campoCategory/Field TipoType ObligatorioRequired DescripciónDescription
MetadataMetadata
$id$id stringstring ObligatorioRequired Identificador del manifiesto de aptitud.The identifier for the skill manifest.
$schema$schema stringstring ObligatorioRequired URI HTTPS de un recurso de esquema JSON que describe el formato del manifiesto.The HTTPS URI of a JSON schema resource that describes the format of the manifest. En el caso de la versión 2.1.0, el URI es https://schemas.botframework.com/schemas/skills/v2.1/skill-manifest.json.For version 2.1.0, the URI is https://schemas.botframework.com/schemas/skills/v2.1/skill-manifest.json.
copyrightcopyright stringstring OpcionalOptional Aviso de copyright de la aptitud.The copyright notice for the skill.
descriptiondescription stringstring OpcionalOptional Descripción legible de la aptitud.A human-readable description of the skill.
iconUrliconUrl stringstring OpcionalOptional URI del icono que se va a mostrar para la aptitud.The URI of the icon to show for the skill.
licenselicense stringstring OpcionalOptional Contrato de licencia de la aptitud.The license agreement for the skill.
namename stringstring ObligatorioRequired Nombre de la aptitud.The name of the skill.
versionversion stringstring ObligatorioRequired Versión de la aptitud que describe el manifiesto.The version of the skill the manifest describes.
privacyUrlprivacyUrl stringstring OpcionalOptional URI de la descripción de privacidad de la aptitud.The URI of the privacy description for the skill.
publisherNamepublisherName stringstring ObligatorioRequired Nombre del publicador de la aptitud.The name of the skill publisher.
etiquetastags matriz de cadenasstring array OpcionalOptional Conjunto de etiquetas para la aptitud.A set of tags for the skill. Si está presente, cada etiqueta debe ser única.If present, each tag must be unique.
ExtremosEndpoints
extremosendpoints matriz de puntos de conexiónendpoint array ObligatorioRequired Lista de puntos de conexión compatibles con la aptitud.The list of endpoints supported by the skill. Se debe definir al menos un punto de conexión.At least one endpoint must be defined. Cada punto de conexión debe ser único.Each endpoint must be unique.
ActividadesActivities
activitiesactivities objeto que contiene objetos activity con nombreobject containing named activity objects ObligatorioRequired Conjunto de actividades iniciales aceptadas por la aptitud.The set of initial activities accepted by the skill.
activitiesSentactivitiesSent objeto que contiene objetos activity con nombreobject containing named activity objects OpcionalOptional Describe las actividades proactivas que puede enviar la aptitud.Describes the proactive activities that the skill can send.
DefinicionesDefinitions
definitionsdefinitions objectobject OpcionalOptional Objeto que contiene subesquemas para objetos usados en el manifiesto.An object containing subschemas for objects used in the manifest.
Modelos de distribuciónDispatch models
dispatchModelsdispatchModels Objeto dispatchModelsdispatchModels object OpcionalOptional Describe los modelos de lenguaje y las intenciones de nivel superior que admite la aptitud.Describes the language models and top-level intents supported by the skill. Consulte a continuación el esquema para este objeto.See below for the schema for this object.

Puntos de conexiónEndpoints

Cada objeto endpoint describe un punto de conexión compatible con la aptitud.Each endpoint object describes an endpoint supported by the skill.

En este ejemplo se muestran dos puntos de conexión de una aptitud.This example lists two endpoints for a skill.

"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"
    }
],

Objeto endpointendpoint object

Describe un punto de conexión compatible con la aptitud.Describes an endpoint supported by the skill.

CampoField TipoType ObligatorioRequired DescripciónDescription
descriptiondescription stringstring OpcionalOptional Descripción del punto de conexión.A description of the endpoint.
endpointUrlendpointUrl stringstring ObligatorioRequired Punto de conexión del URI de la aptitud.The URI endpoint for the skill.
msAppIdmsAppId stringstring ObligatorioRequired Microsoft AppId (GUID) de la aptitud, usado para autenticar solicitudes.The Microsoft AppId (GUID) for the skill, used to authenticate requests.
namename stringstring ObligatorioRequired Nombre único para el punto de conexión.The unique name for the endpoint.
protocolprotocol stringstring OpcionalOptional Protocolo admitido.The supported protocol. El valor predeterminado es "BotFrameworkV3".Default is "BotFrameworkV3".

ActividadesActivities

Cada objeto activity describe una actividad aceptada por la aptitud o una que la aptitud puede enviar de forma proactiva.Each activity object describes an activity accepted by the skill or one the skill can send proactively. En el caso de las actividades entrantes, la aptitud iniciará una acción o tarea en función de la actividad inicial recibida.For incoming activities, the skill will initiate an action or task based on the initial activity received. El nombre asociado al objeto activity indica la acción o tarea que realizará la aptitud.The name associated with the activity object indicates the action or task the skill will perform.

Algunos tipos de actividad tienen una propiedad Value que se puede usar para proporcionar una entrada adicional a la aptitud.Some activity types have a value property that can be used to provide additional input to the skill. Al finalizar la aptitud (completar la acción), puede proporcionar un valor devuelto en la propiedad Value de la actividad de final de conversación asociada.When the skill ends (completes the action) it can provide a return value in the associated end-of-conversation activity's value property.

Los tipos de actividad permitidos en el esquema del manifiesto de aptitud v2.1.preview-1 son: actividades message, event, invoke y otras actividades.The activity types allowed in the v2.1.preview-1 skill manifest schema are: message, event, invoke, and other activities. Una aptitud puede recibir una actividad invoke, pero no puede enviarla.A skill can receive an invoke activity, but can't send one.

Esta es una descripción de la actividad de ejemplo.This is a sample activity description.

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

Objeto eventActivityeventActivity object

Describe una actividad event aceptada o enviada por la aptitud.Describes an event activity accepted or sent by the skill.

CampoField TipoType ObligatorioRequired DescripciónDescription
descriptiondescription stringstring OpcionalOptional Descripción de la acción.A description of the action.
namename stringstring ObligatorioRequired Valor de la propiedad Name de la actividad event.The value of the event activity's name property.
resultValueresultValue objectobject OpcionalOptional Definición de esquema JSON del tipo de objeto que la acción asociada puede devolver.A JSON schema definition of the type of object that the associated action can return.
typetype stringstring ObligatorioRequired Tipo de actividad.The activity type. Debe ser "event".Must be "event".
valuevalue objectobject OpcionalOptional Definición de esquema JSON del tipo de objeto que esta acción espera como entrada.A JSON schema definition of the type of object that this action expects as input.

Objeto invokeActivityinvokeActivity object

Describe una actividad invoke aceptada por la aptitud.Describes an invoke activity accepted by the skill.

CampoField TipoType ObligatorioRequired DescripciónDescription
descriptiondescription stringstring OpcionalOptional Descripción de la acción.A description of the action.
namename stringstring ObligatorioRequired Valor de la propiedad Name de la actividad invoke.The value of the invoke activity's name property.
resultValueresultValue objectobject OpcionalOptional Definición de esquema JSON del tipo de objeto que la acción asociada puede devolver.A JSON schema definition of the type of object that the associated action can return.
typetype stringstring ObligatorioRequired Tipo de actividad.The activity type. Debe ser "invoke".Must be "invoke".
valuevalue objectobject OpcionalOptional Definición de esquema JSON del tipo de objeto que esta acción espera como entrada.A JSON schema definition of the type of object that this action expects as input.

Objeto messageActivitymessageActivity object

Describe una actividad message aceptada o enviada por la aptitud.Describes a message activity accepted or sent by the skill. La propiedad Text de la actividad message contiene la expresión del usuario.The message activity's text property contains the user's utterance.

CampoField TipoType ObligatorioRequired DescripciónDescription
descriptiondescription stringstring OpcionalOptional Descripción de la acción.A description of the action.
resultValueresultValue objectobject OpcionalOptional Definición de esquema JSON del tipo de objeto que la acción asociada puede devolver.A JSON schema definition of the type of object that the associated action can return.
typetype stringstring ObligatorioRequired Tipo de actividad.The activity type. Debe ser "message".Must be "message".
valuevalue objectobject OpcionalOptional Definición de esquema JSON del tipo de objeto que esta acción espera como entrada.A JSON schema definition of the type of object that this action expects as input.

Objeto otherActivitiesotherActivities object

Describe una actividad aceptada o enviada por la aptitud.Describes an activity accepted or sent by the skill.

CampoField TipoType ObligatorioRequired DescripciónDescription
typetype stringstring ObligatorioRequired Tipo de actividad.The activity type. Debe ser uno de los otros tipos de actividad de Bot Framework: "contactRelationUpdate", "conversationUpdate", "deleteUserData", "endOfConversation", "handoff", "installationUpdate", "messageDelete", "messageUpdate", "messageReaction", "suggestion", "trace" o "typing".Must be one of the other Bot Framework activity types: "contactRelationUpdate", "conversationUpdate", "deleteUserData", "endOfConversation", "handoff", "installationUpdate", "messageDelete", "messageUpdate", "messageReaction", "suggestion", "trace", or "typing".

El objeto otherActivities puede incluir otras propiedades, pero el esquema del manifiesto de aptitud no define su significado.The otherActivities object can include other properties, but the skill manifest schema does not define their meaning.

DefinicionesDefinitions

Cada definición describe un subesquema que pueden usar otras partes del documento.Each definition describes a subschema that can be consumed by other parts of the document.

Este es un subesquema de ejemplo para la información de reserva de vuelos.This is a sample subschema for flight booking information.

"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"
        }
    }
},

Modelos de distribuciónDispatch models

El modelo de distribución contiene una lista de modelos de lenguaje y una lista de intenciones de nivel superior compatibles con la aptitud.The dispatch model contains a list of language models and a list of top-level intents supported by the skill. Se trata de una característica avanzada que permite a un desarrollador de un consumidor de aptitudes componer un modelo de lenguaje que combina las características de los bots de aptitudes y consumidores.This is an advanced feature to enable a developer of a skill consumer to compose a language model that combines the features of the consumer and skill bots.

Un nombre de configuración regional es una combinación de un código de referencia cultural en minúsculas de dos letras ISO 639 asociado a un idioma y un código de subcultura en mayúsculas de dos letras ISO 3166 asociado a un país o región, por ejemplo "en" o "en-US".A locale name is a combination of an ISO 639 two-letter lowercase culture code associated with a language and an optional ISO 3166 two-letter uppercase subculture code associated with a country or region, for example "en" or "en-US".

CampoField TipoType ObligatorioRequired DescripciónDescription
intencionesintents matriz de cadenasstring array OpcionalOptional Una lista de las intenciones de nivel superior compatibles con la aptitud.A list of the top-level intents supported by the skill. Cada intención debe ser única.Each intent must be unique.
languageslanguages objeto que contiene matrices languageModel con nombreobject containing named languageModel arrays ObligatorioRequired Una lista de los modelos de lenguaje compatibles con la aptitud.A list of the language models supported by the skill. Cada nombre es la configuración regional a la que corresponden los modelos de lenguaje y la matriz contiene los módulos de lenguaje correspondientes a esa configuración regional.Each name is the locale the language models are for, and the array contains the language modules for that locale. Un modelo de distribución debe admitir al menos una configuración regional.A dispatch model must support at least one locale. Cada configuración regional del campo languages debe ser única.Each locale within the languages field must be unique.

Este es un modelo de distribución de ejemplo que contiene dos modelos de lenguaje en tres configuraciones regionales.This is a sample dispatch model that contains two languages models across three locales. También describe dos intenciones de nivel superior que la aptitud puede reconocer.It also describes two top-level intents that the skill can recognize.

"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"
    ]
},

Objeto languageModellanguageModel object

Describe un modelo de lenguaje para una referencia cultural determinada.Describes a language model for a given culture. El nombre es un nombre de configuración regional.The name is a locale name.

CampoField TipoType ObligatorioRequired DescripciónDescription
contentTypecontentType stringstring ObligatorioRequired Tipo del modelo de lenguaje.Type of the language model.
descriptiondescription stringstring OpcionalOptional Una descripción del modelo de lenguaje.A description of the language model.
namename stringstring ObligatorioRequired Nombre del modelo de lenguaje.Name of the language model.
urlurl stringstring ObligatorioRequired Dirección URL del modelo de lenguaje.The URL for the language model.

Manifiesto de ejemploSample manifest

Se trata de un manifiesto v2.1 de ejemplo completo de una aptitud que expone varias actividades.This is a full sample v2.1 manifest for a skill that exposes multiple activities.

{
    "$schema": "https://schemas.botframework.com/schemas/skills/v2.1/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": "https://myskill.contoso.com/icon.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"
                    }
                }
            }
        }
    }
}