Condividi tramite

Scrivere un manifesto della competenza

  • Articolo

SI APPLICA A: SDK v4

Un manifesto della competenza è un file JSON che descrive le azioni che una competenza può eseguire, i relativi parametri di input e output e gli endpoint della competenza. Il manifesto contiene informazioni leggibili dal computer che uno sviluppatore può usare per accedere alla competenza da un altro bot.

Questo articolo descrive le versioni supportate dello schema del manifesto della competenza di Bot Framework.

Versione Note
versione 2.2 Sono state aggiornate alcune proprietà URI per accettare riferimenti URI.
versione 2.1 Aggiunge la possibilità di descrivere le attività proattive che la competenza può inviare e inviare i modelli usati dalla competenza.
versione 2.0 Versione iniziale.

Gli schemi del manifesto della competenza di Bot Framework usano la bozza 7 del vocabolario dello schema JSON.

Prerequisiti

Manifesto della competenza

Il manifesto della competenza contiene diverse categorie di informazioni:

  • Metadati che descrivono la competenza a livello generale.
  • Un elenco degli endpoint forniti dalla competenza.
  • Elenchi facoltativi delle attività che la competenza può ricevere e inviare in modo proattivo.
  • Un oggetto definizioni facoltativo che contiene gli schemi per gli oggetti a cui fanno riferimento altre parti del documento.
  • Elenco facoltativo dei modelli dispatch supportati dalla competenza.

La tabella seguente descrive lo schema completo per la versione 2.2 del manifesto della competenza di Bot Framework.

Categoria/Campo Tipo/formato Richiesto Descrizione
Metadati UFX
$id Stringa Richiesto Identificatore del manifesto della competenza.
$schema String/URI Richiesto URI HTTPS di una risorsa dello schema JSON che descrive il formato del manifesto. Per la versione 2.2, l'URI è https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json.
copyright Stringa Facoltativo Informazioni sul copyright della competenza.
description Stringa Facoltativo Descrizione leggibile della competenza.
iconUrl String/URI-reference Facoltativo URI dell'icona da visualizzare per la competenza.
Licenza Stringa Facoltativo Contratto di licenza della competenza.
name string Richiesto Nome della competenza.
privacyUrl String/URI-reference Facoltativo URI della descrizione della privacy per la competenza.
publisherName Stringa Richiesto Nome dell'editore della competenza.
tags Matrice di stringhe Facoltativo Set di tag per la competenza. Se presente, ogni tag deve essere univoco.
version Stringa Richiesto Versione della competenza descritta dal manifesto.
Endpoint
endpoint matrice di endpoint Richiesto Elenco degli endpoint supportati dalla competenza. È necessario definire almeno un endpoint. Ogni endpoint deve essere univoco.
Impegni
attività Oggetto contenente oggetti attività denominati Facoltativo Set di attività iniziali accettate dalla competenza.
activitiesSent Oggetto contenente oggetti attività denominati Facoltativo Descrive le attività proattive che la competenza può inviare.
Definizioni
definitions Oggetto Facoltativo Oggetto contenente i sottoschemi per gli oggetti usati nel manifesto.
Modelli dispatch
dispatchModels Oggetto dispatchModels Facoltativo Descrive i modelli linguistici e le finalità di primo livello supportati dalla competenza. Vedere Dispatch models for the schema for this object (Modelli dispatch per questo oggetto).

Endpoint

Ogni oggetto endpoint descrive un endpoint supportato dalla competenza.

In questo esempio vengono elencati due endpoint per una competenza.

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

Oggetto endpoint

Descrive un endpoint supportato dalla competenza.

Campo Tipo/formato Richiesto Descrizione
description Stringa Facoltativo Descrizione dell'endpoint.
endpointUrl String/URI Richiesto Endpoint URI per la competenza.
msAppId Stringa Richiesto AppId (GUID) Microsoft per la competenza, usato per autenticare le richieste. Deve corrispondere all'espressione regolare: ^[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 string Richiesto Nome univoco per l'endpoint.
protocollo Stringa Facoltativo Protocollo bot supportato. Il valore predefinito è "BotFrameworkV3", che rappresenta l'API bot Connessione or versione 3. Usare il valore predefinito a meno che la competenza non usi in modo specifico un protocollo diverso.

Attività

Ogni oggetto attività descrive un'attività accettata dalla competenza. La competenza avvia un'azione o un'attività in base all'attività iniziale ricevuta. Il nome associato all'oggetto attività indica l'azione o l'attività eseguita dalla competenza.

Alcuni tipi di attività hanno una proprietà value che può essere usata per fornire input aggiuntivo alla competenza. Al termine della competenza (completa l'azione), può fornire un valore restituito nella proprietà value dell'attività di fine conversazione associata.

I tipi di attività consentiti sono: message, event, invoke e altre attività. Una competenza può ricevere ma non inviare un'attività invoke.

Ecco una descrizione dell'attività di esempio.

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

Oggetto eventActivity

Descrive un'attività event accettata o inviata dalla competenza. Il significato di un'attività evento è definito dal relativo campo nome, che è significativo nell'ambito della competenza.

Campo Type Richiesto Descrizione
description Stringa Facoltativo Descrizione dell'azione che l'evento deve avviare.
name string Richiesto Valore della proprietà name dell'attività event.
resultValue Oggetto Facoltativo Definizione dello schema JSON del tipo di oggetto che l'azione può restituire.
Tipo Stringa Richiesto Tipo di attività. Deve essere "event".
value Oggetto Facoltativo Definizione dello schema JSON del tipo di oggetto prevista come input da questa azione.

Oggetto invokeActivity

Descrive un'attività invoke accettata dalla competenza. Il significato di un'attività invoke è definito dal relativo campo del nome, significativo nell'ambito della competenza.

Campo Type Richiesto Descrizione
description Stringa Facoltativo Descrizione dell'azione che deve essere avviata dall'richiamare.
name string Richiesto Valore della proprietà name dell'attività invoke.
resultValue Oggetto Facoltativo Definizione dello schema JSON del tipo di oggetto che l'azione associata può restituire.
Tipo Stringa Richiesto Tipo di attività. Deve essere "invoke".
value Oggetto Facoltativo Definizione dello schema JSON del tipo di oggetto prevista come input da questa azione.

Oggetto messageActivity

Descrive un'attività message accettata o inviata dalla competenza. La proprietà text dell'attività del messaggio contiene l'espressione dell'utente o del bot.

Campo Type Richiesto Descrizione
description Stringa Facoltativo Descrizione dell'azione.
resultValue Oggetto Facoltativo Definizione dello schema JSON del tipo di oggetto che l'azione associata può restituire.
Tipo Stringa Richiesto Tipo di attività. Deve essere "message".
value Oggetto Facoltativo Definizione dello schema JSON del tipo di oggetto prevista come input da questa azione.

Oggetto otherActivities

Descrive qualsiasi altro tipo di attività accettato o inviato dalla competenza.

Campo Type Richiesto Descrizione
Tipo Stringa Richiesto Tipo di attività. Deve essere uno degli altri tipi di attività di Bot Framework: "contactRelationUpdate", "conversationUpdate", "deleteUserData", "endOfConversation", "handoff", "installationUpdate", "messageDelete", "messageReaction", "messageUpdate", "suggestion", "trace" o "typing".

L'altro oggettoActivities può includere altre proprietà, ma lo schema del manifesto della competenza non ne definisce il significato.

Definizioni

Ogni definizione descrive un sottoschema che può essere utilizzato da altre parti del documento.

Ecco un sottoschema di esempio per informazioni sulla prenotazione dei voli.

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

Modelli dispatch

Il modello dispatch contiene un elenco di modelli linguistici e un elenco di finalità di primo livello supportate dalla competenza. Si tratta di una funzionalità avanzata per consentire a uno sviluppatore di un consumer di competenze di comporre un modello linguistico che combina le funzionalità dei bot consumer e competenza.

Ogni modello linguistico usa il .lu formato di file o .qna . Per altre informazioni su questi formati, vedere formato di file con estensione lu e formato di file con estensione qna.

Un nome di impostazioni locali è dato dalla combinazione di un codice impostazioni cultura ISO 639 a due lettere minuscole associato a una lingua e di un codice impostazioni cultura secondarie ISO 3166 a due lettere maiuscole facoltativo associato a un paese o un'area geografica, ad esempio "en" o "en-US".

Campo Type Richiesto Descrizione
Finalità Matrice di stringhe Facoltativo Elenco delle finalità di primo livello supportate dalla competenza. Ogni finalità deve essere univoca.
lingue Oggetto contenente matrici languageModel denominate Facoltativo Elenco dei modelli linguistici supportati dalla competenza. Ogni nome è costituito dalle impostazioni locali per cui si trovano i modelli linguistici e la matrice contiene i modelli linguistici per tali impostazioni locali. Un modello dispatch deve supportare almeno una delle impostazioni locali. Le impostazioni locali nel campo languages devono essere univoche.

Ecco un modello dispatch di esempio che contiene due lingue tra tre impostazioni locali. Descrive inoltre descritte due finalità di primo livello che la competenza è in grado di riconoscere.

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

Oggetto languageModel

Descrive un modello linguistico per impostazioni cultura specifiche. Il nome corrisponde a un nome di impostazioni locali.

Campo Tipo/formato Richiesto Descrizione
contentType Stringa Richiesto Tipo del modello linguistico.
description Stringa Facoltativo Descrizione del modello linguistico.
name string Richiesto Nome del modello linguistico.
URL. String/URI-reference Richiesto URL del modello linguistico.

Manifesto di esempio

Ecco un manifesto completo della versione 2.2 di esempio per una competenza che espone più attività.

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

Passaggi successivi