Escritura de un manifiesto de aptitud
SE APLICA A: 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. El manifiesto contiene información legible por máquina que un desarrollador puede utilizar para acceder a la aptitud desde otro bot.
En este artículo se describe las versiones compatibles del esquema del manifiesto de aptitud de Bot Framework.
Versión | Notas |
---|---|
versión 2.2 | Se han actualizado algunas propiedades de URI para aceptar referencias de URI. |
versión 2.1 | Agrega capacidad para describir las actividades proactivas que la aptitud puede enviar y los modelos de distribución que usa la aptitud. |
versión 2.0 | Versión inicial |
El esquema del manifiesto de aptitud de Bot Framework usa el borrador 7 del vocabulario del esquema JSON.
- Conocimientos de aptitudes.
- Cierta familiaridad con el esquema JSON y el formato JSON.
El manifiesto de aptitud contiene diferentes categorías de información:
- Metadatos que describen la aptitud a nivel general.
- Una lista de los puntos de conexión proporcionados por la aptitud.
- Listas opcionales de las actividades que la aptitud puede recibir y enviar de forma proactiva.
- Un objeto definitions opcional que contiene esquemas para objetos a los que otras partes del documento hacen referencia.
- Una lista opcional de los modelos de distribución que admite la aptitud.
En la tabla siguiente se describe el esquema completo para la v2.2 del manifiesto de aptitudes de Bot Framework.
Categoría/campo | Tipo/Formato | Obligatorio | Descripción |
---|---|---|---|
Metadata | |||
$id | Cadena | Obligatorio | Identificador del manifiesto de aptitud. |
$schema | Identificador URI de cadena | Obligatorio | URI HTTPS de un recurso de esquema JSON que describe el formato del manifiesto. En el caso de la versión 2.2, el URI es https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json . |
copyright | Cadena | Opcionales | Aviso de copyright de la aptitud. |
descripción | Cadena | Opcionales | Descripción legible de la aptitud. |
iconUrl | String/URI-reference | Opcionales | URI del icono que se va a mostrar para la aptitud. |
licencia | Cadena | Opcionales | Contrato de licencia de la aptitud. |
name | Cadena | Obligatorio | Nombre de la aptitud. |
privacyUrl | String/URI-reference | Opcionales | URI de la descripción de privacidad de la aptitud. |
publisherName | Cadena | Obligatorio | Nombre del publicador de la aptitud. |
etiquetas | Matriz de cadenas | Opcionales | Conjunto de etiquetas para la aptitud. Si está presente, cada etiqueta debe ser única. |
version | Cadena | Obligatorio | Versión de la aptitud que describe el manifiesto. |
Extremos | |||
extremos | matriz de puntos de conexión | Obligatorio | Lista de puntos de conexión compatibles con la aptitud. Se debe definir al menos un punto de conexión. Cada punto de conexión debe ser único. |
Actividades | |||
activities | objeto que contiene objetos activity con nombre | Opcionales | Conjunto de actividades iniciales aceptadas por la aptitud. |
activitiesSent | objeto que contiene objetos activity con nombre | Opcionales | Describe las actividades proactivas que puede enviar la aptitud. |
Definiciones | |||
definitions | Object | Opcionales | Objeto que contiene subesquemas para objetos usados en el manifiesto. |
Modelos de distribución | |||
dispatchModels | Objeto dispatchModels | Opcionales | Describe los modelos de lenguaje y las intenciones de nivel superior que admite la aptitud. Consulte Modelos de distribución para ver el esquema de este objeto. |
Cada objeto endpoint describe un punto de conexión compatible con la aptitud.
En este ejemplo se muestran dos puntos de conexión de una aptitud.
"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"
}
],
Describe un punto de conexión compatible con la aptitud.
Campo | Tipo/Formato | Obligatorio | Descripción |
---|---|---|---|
descripción | Cadena | Opcionales | Descripción del punto de conexión. |
endpointUrl | Identificador URI de cadena | Obligatorio | Punto de conexión del URI de la aptitud. |
msAppId | Cadena | Obligatorio | Microsoft AppId (GUID) de la aptitud, usado para autenticar solicitudes. Debe coincidir con la expresión regular: ^[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 | Cadena | Obligatorio | Nombre único para el punto de conexión. |
protocolo | Cadena | Opcionales | No se admite el protocolo Bot. Por defecto es "BotFrameworkV3", que representa la versión 3 de la API del bot Conector. Use el valor predeterminado a menos que la aptitud use específicamente un protocolo diferente. |
Cada objeto activity describe una actividad aceptada por la aptitud. La aptitud inicia una acción o tarea en función de la actividad inicial que recibe. El nombre asociado al objeto activity indica la acción o tarea que realizará la aptitud.
Algunos tipos de actividad tienen una propiedad Value que se puede usar para proporcionar una entrada adicional a la aptitud. 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.
Los tipos de actividad permitidos son: message, event, invoke y otras actividades. Una aptitud puede recibir una actividad invoke, pero no puede enviarla.
He aquí un ejemplo de descripción de la actividad.
"bookFlight": {
"description": "Books a flight",
"type": "event",
"name": "BookFlight",
"value": {
"$ref": "#/definitions/bookingInfo"
},
"resultValue": {
"$ref": "#/definitions/bookingInfo"
}
},
Describe una actividad event aceptada o enviada por la aptitud. El significado de una actividad de evento viene definido por su campo de nombre, que es significativo dentro del ámbito de la aptitud.
Campo | Tipo | Obligatorio | Descripción |
---|---|---|---|
descripción | Cadena | Opcionales | Descripción de la acción que debe iniciar el evento. |
name | Cadena | Obligatorio | Valor de la propiedad Name de la actividad event. |
resultValue | Object | Opcionales | Definición de esquema JSON del tipo de objeto que la acción puede devolver. |
type | String | Obligatorio | Tipo de actividad. Debe ser "event". |
value | Object | Opcionales | Definición de esquema JSON del tipo de objeto que esta acción espera como entrada. |
Describe una actividad invoke aceptada por la aptitud. El significado de una actividad de invocación viene definido por su campo de nombre, que es significativo dentro del ámbito de la aptitud.
Campo | Tipo | Obligatorio | Descripción |
---|---|---|---|
descripción | Cadena | Opcionales | Una descripción de la acción que debe iniciar la invocación. |
name | Cadena | Obligatorio | Valor de la propiedad Name de la actividad invoke. |
resultValue | Object | Opcionales | Definición de esquema JSON del tipo de objeto que la acción asociada puede devolver. |
type | String | Obligatorio | Tipo de actividad. Debe ser "invoke". |
value | Object | Opcionales | Definición de esquema JSON del tipo de objeto que esta acción espera como entrada. |
Describe una actividad message aceptada o enviada por la aptitud. La propiedad Text de la actividad message contiene la expresión del usuario o del bot.
Campo | Tipo | Obligatorio | Descripción |
---|---|---|---|
descripción | Cadena | Opcionales | Descripción de la acción. |
resultValue | Object | Opcionales | Definición de esquema JSON del tipo de objeto que la acción asociada puede devolver. |
type | String | Obligatorio | Tipo de actividad. Debe ser "message". |
value | Object | Opcionales | Definición de esquema JSON del tipo de objeto que esta acción espera como entrada. |
Describe cualquier otro tipo de actividad aceptada o enviada por la aptitud.
Campo | Tipo | Obligatorio | Descripción |
---|---|---|---|
type | String | Obligatorio | Tipo de actividad. Debe ser uno de los otros tipos de actividad de Bot Framework: "contactRelationUpdate", "conversationUpdate", "deleteUserData", "endOfConversation", "handoff", "installationUpdate", "messageDelete", "messageReaction", "messageUpdate", "suggestion", "trace", o "typing". |
El objeto otherActivities puede incluir otras propiedades, pero el esquema del manifiesto de aptitud no define su significado.
Cada definición describe un subesquema que pueden usar otras partes del documento.
Este es un subesquema de ejemplo para la información de reserva de vuelos.
"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"
}
}
},
El modelo de distribución contiene una lista de modelos de lenguaje y una lista de intenciones de nivel superior compatibles con la aptitud. 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.
Cada modelo de lenguaje usa el formato de archivo .lu
o .qna
. Para obtener más información sobre estos formatos, vea formato de archivo .lu y formato de archivo .qna.
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".
Campo | Tipo | Obligatorio | Descripción |
---|---|---|---|
intenciones | Matriz de cadenas | Opcionales | Una lista de las intenciones de nivel superior compatibles con la aptitud. Cada intención debe ser única. |
languages | objeto que contiene matrices languageModel con nombre | Opcionales | Una lista de los modelos de lenguaje compatibles con la aptitud. Cada nombre es la configuración regional a la que corresponden los modelos de lenguaje y la matriz contiene los modelos de lenguaje correspondientes a esa configuración regional. Un modelo de distribución debe admitir al menos una configuración regional. Cada configuración regional del campo languages debe ser única. |
Este es un modelo de distribución de ejemplo que contiene dos modelos de lenguaje en tres configuraciones regionales. También describe dos intenciones de nivel superior que la aptitud puede reconocer.
"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"
]
},
Describe un modelo de lenguaje para una referencia cultural determinada. El nombre es un nombre de configuración regional.
Campo | Tipo/Formato | Obligatorio | Descripción |
---|---|---|---|
contentType | Cadena | Obligatorio | Tipo del modelo de lenguaje. |
descripción | Cadena | Opcionales | Una descripción del modelo de lenguaje. |
name | Cadena | Obligatorio | Nombre del modelo de lenguaje. |
url | String/URI-reference | Obligatorio | Dirección URL del modelo de lenguaje. |
Se trata de un manifiesto v2.2 de ejemplo completo de una aptitud que expone varias actividades.
{
"$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"
}
}
}
}
}
}