Escritura de un manifiesto de aptitud

  • Artículo

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.

Requisitos previos

El manifiesto de aptitud

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.

Puntos de conexión

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

Objeto endpoint

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.

Actividades

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

Objeto eventActivity

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.

Objeto invokeActivity

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.

Objeto messageActivity

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.

Objeto otherActivities

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.

Definiciones

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

Modelos de distribución

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

Objeto languageModel

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.

Manifiesto de ejemplo

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

Pasos siguientes