Delen via

Een vaardigheidsmanifest schrijven

  • Artikel

VAN TOEPASSING OP: SDK v4

Een vaardigheidsmanifest is een JSON-bestand dat de acties beschrijft die een vaardigheid kan uitvoeren, de invoer- en uitvoerparameters en de eindpunten van de vaardigheid. Het manifest bevat machineleesbare informatie die een ontwikkelaar kan gebruiken om toegang te krijgen tot de vaardigheid van een andere bot.

In dit artikel worden ondersteunde versies van het manifestschema voor bot framework-vaardigheden beschreven.

Versie Aantekeningen
versie 2.2 Sommige URI-eigenschappen zijn bijgewerkt om URI-verwijzingen te accepteren.
versie 2.1 Hiermee kunt u proactieve activiteiten beschrijven die de vaardigheid kan verzenden en de verzendmodellen die door de vaardigheid worden gebruikt.
versie 2.0 Initiële versie.

De bot framework-manifestschema's maken gebruik van concept 7 van het JSON-schema-vocabulaire.

Vereisten

Het vaardigheidsmanifest

Het vaardigheidsmanifest bevat verschillende informatiecategorieën:

  • Metagegevens die de vaardigheid op algemeen niveau beschrijven.
  • Een lijst met de eindpunten die de vaardigheid biedt.
  • Optionele lijsten van de activiteiten die de vaardigheid kan ontvangen en proactief verzenden.
  • Een optioneel definitieobject dat schema's bevat voor objecten waarnaar wordt verwezen door andere delen van het document.
  • Een optionele lijst met de verzendmodellen die door de vaardigheid worden ondersteund.

In de volgende tabel wordt het volledige schema voor v2.2 van het Bot Framework-vaardigheidsmanifest beschreven.

Categorie/veld Type/opmaak Vereist Beschrijving
Metagegevens
$id String Vereist De id voor het vaardigheidsmanifest.
$schema Tekenreeks/URI Vereist De HTTPS-URI van een JSON-schemaresource die de indeling van het manifest beschrijft. Voor versie 2.2 is https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.jsonde URI .
Copyright String Optioneel De copyrightmelding voor de vaardigheid.
beschrijving String Optioneel Een door mensen leesbare beschrijving van de vaardigheid.
iconUrl Tekenreeks-/URI-verwijzing Optioneel De URI van het pictogram die moet worden weergegeven voor de vaardigheid.
licentie String Optioneel De gebruiksrechtovereenkomst voor de vaardigheid.
name String Vereist De naam van de vaardigheid.
privacyUrl Tekenreeks-/URI-verwijzing Optioneel De URI van de privacybeschrijving voor de vaardigheid.
publisherName String Vereist De naam van de uitgever van de vaardigheid.
tags Tekenreeksmatrix Optioneel Een set tags voor de vaardigheid. Indien aanwezig, moet elke tag uniek zijn.
versie Tekenreeks Vereist De versie van de vaardigheid die in het manifest wordt beschreven.
Eindpunten
eindpunten eindpuntmatrix Vereist De lijst met eindpunten die door de vaardigheid worden ondersteund. Er moet ten minste één eindpunt worden gedefinieerd. Elk eindpunt moet uniek zijn.
Activiteiten
activities Object met benoemde activiteitsobjecten Optioneel De set initiële activiteiten die door de vaardigheid worden geaccepteerd.
activitiesSent Object met benoemde activiteitsobjecten Optioneel Beschrijft de proactieve activiteiten die de vaardigheid kan verzenden.
Definities
Definities Object Optioneel Een object met subschema's voor objecten die in het manifest worden gebruikt.
Verzendmodellen
dispatchModels dispatchModels-object Optioneel Beschrijft de taalmodellen en intenties op het hoogste niveau die door de vaardigheid worden ondersteund. Zie Verzendmodellen voor het schema voor dit object.

Eindpunten

Elk eindpuntobject beschrijft een eindpunt dat wordt ondersteund door de vaardigheid.

In dit voorbeeld worden twee eindpunten voor een vaardigheid weergegeven.

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

eindpuntobject

Beschrijft een eindpunt dat wordt ondersteund door de vaardigheid.

Veld Type/opmaak Vereist Beschrijving
beschrijving String Optioneel Een beschrijving van het eindpunt.
endpointUrl Tekenreeks/URI Vereist Het URI-eindpunt voor de vaardigheid.
msAppId String Vereist De Microsoft AppId (GUID) voor de vaardigheid, die wordt gebruikt voor het verifiëren van aanvragen. Moet overeenkomen met de reguliere expressie: ^[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 Vereist De unieke naam voor het eindpunt.
protocol String Optioneel Het ondersteunde Bot-protocol. De standaardwaarde is 'BotFrameworkV3', die de Bot Verbinding maken or-API versie 3 vertegenwoordigt. Gebruik de standaardwaarde, tenzij uw vaardigheid specifiek een ander protocol gebruikt.

Activiteiten

Elk activiteitsobject beschrijft een activiteit die door de vaardigheid wordt geaccepteerd. De vaardigheid begint een actie of taak op basis van de eerste activiteit die wordt ontvangen. De naam die aan het activiteitsobject is gekoppeld, geeft de actie of taak aan die door de vaardigheid wordt uitgevoerd.

Sommige activiteitstypen hebben een waarde-eigenschap die kan worden gebruikt om extra invoer voor de vaardigheid te bieden. Wanneer de vaardigheid eindigt (de actie voltooit), kan deze een retourwaarde opgeven in de waarde-eigenschap van de gekoppelde waarde van de gespreksactiviteit.

De toegestane activiteitstypen zijn: bericht, gebeurtenis, aanroepen en andere activiteiten. Een vaardigheid kan een aanroepactiviteit ontvangen, maar kan er geen verzenden.

Hier volgt een beschrijving van een voorbeeldactiviteit.

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

eventActivity-object

Beschrijft een gebeurtenisactiviteit die door de vaardigheid is geaccepteerd of verzonden. De betekenis van een gebeurtenisactiviteit wordt gedefinieerd door het naamveld, wat zinvol is binnen het bereik van de vaardigheid.

Veld Type Vereist Beschrijving
beschrijving String Optioneel Een beschrijving van de actie die de gebeurtenis moet initiëren.
name String Vereist De waarde van de naameigenschap van de gebeurtenisactiviteit.
resultValue Object Optioneel Een JSON-schemadefinitie van het type object dat door de actie kan worden geretourneerd.
type String Vereist Het activiteitstype. Moet 'gebeurtenis' zijn.
waarde Object Optioneel Een JSON-schemadefinitie van het type object dat door deze actie als invoer wordt verwacht.

invokeActivity-object

Beschrijft een aanroepactiviteit die door de vaardigheid wordt geaccepteerd. De betekenis van een aanroepactiviteit wordt gedefinieerd door het naamveld, wat zinvol is binnen het bereik van de vaardigheid.

Veld Type Vereist Beschrijving
beschrijving String Optioneel Een beschrijving van de actie die de aanroep moet starten.
name String Vereist De waarde van de naameigenschap van de aanroepactiviteit.
resultValue Object Optioneel Een JSON-schemadefinitie van het type object dat door de bijbehorende actie kan worden geretourneerd.
type String Vereist Het activiteitstype. Moet 'aanroepen' zijn.
waarde Object Optioneel Een JSON-schemadefinitie van het type object dat door deze actie als invoer wordt verwacht.

messageActivity-object

Beschrijft een berichtactiviteit die door de vaardigheid is geaccepteerd of verzonden. De teksteigenschap van de berichtactiviteit bevat de uiting van de gebruiker of bot.

Veld Type Vereist Beschrijving
beschrijving String Optioneel Een beschrijving van de actie.
resultValue Object Optioneel Een JSON-schemadefinitie van het type object dat door de bijbehorende actie kan worden geretourneerd.
type String Vereist Het activiteitstype. Moet 'bericht' zijn.
waarde Object Optioneel Een JSON-schemadefinitie van het type object dat door deze actie als invoer wordt verwacht.

otherActivities-object

Beschrijft elk ander activiteitstype dat door de vaardigheid is geaccepteerd of verzonden.

Veld Type Vereist Beschrijving
type String Vereist Het activiteitstype. Moet een van de andere Bot Framework-activiteitstypen zijn: "contactRelationUpdate", "conversationUpdate", "deleteUserData", "endOfConversation", "handoff", "installationUpdate", "messageDelete", "messageReaction", "messageUpdate", "suggestion", "trace" of "type".

Het object otherActivities kan andere eigenschappen bevatten, maar het vaardigheidsmanifestschema definieert de betekenis ervan niet.

Definities

Elke definitie beschrijft een subschema dat kan worden gebruikt door andere delen van het document.

Hier volgt een voorbeeldsubschema voor vluchtboekingsgegevens.

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

Verzendmodellen

Het verzendmodel bevat een lijst met taalmodellen en een lijst met intenties op het hoogste niveau die door de vaardigheid worden ondersteund. Het is een geavanceerde functie waarmee een ontwikkelaar van een vaardigheidsgebruiker een taalmodel kan opstellen dat de functies van de bots voor consumenten en vaardigheden combineert.

Elk taalmodel maakt gebruik van de .lu of .qna bestandsindeling. Zie .lu-bestandsindeling en .qna-bestandsindeling voor meer informatie over deze indelingen.

Een landinstellingsnaam is een combinatie van een ISO 639-cultuurcode met twee letters die is gekoppeld aan een taal en een optionele ISO 3166-subcultuurcode met twee letters die is gekoppeld aan een land of regio, bijvoorbeeld 'en' of 'en-US'.

Veld Type Vereist Beschrijving
intents Tekenreeksmatrix Optioneel Een lijst met de intenties op het hoogste niveau die worden ondersteund door de vaardigheid. Elke intentie moet uniek zijn.
talen Object met benoemde languageModel-matrices Optioneel Een lijst met de taalmodellen die door de vaardigheid worden ondersteund. Elke naam is de landinstelling waarvoor de taalmodellen zijn bedoeld en de matrix bevat de taalmodellen voor die landinstelling. Een verzendmodel moet ten minste één landinstelling ondersteunen. Elke landinstelling in het talenveld moet uniek zijn.

Hier volgt een voorbeeld van een verzendmodel met twee talenmodellen op drie landinstellingen. Er worden ook twee intenties op het hoogste niveau beschreven die door de vaardigheid kunnen worden herkend.

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

languageModel-object

Beschrijft een taalmodel voor een bepaalde cultuur. De naam is een landinstellingsnaam.

Veld Type/opmaak Vereist Beschrijving
Contenttype String Vereist Type van het taalmodel.
beschrijving String Optioneel Een beschrijving van het taalmodel.
name String Vereist Naam van het taalmodel.
URL Tekenreeks-/URI-verwijzing Vereist De URL voor het taalmodel.

Voorbeeldmanifest

Hier volgt een volledig voorbeeld van v2.2-manifest voor een vaardigheid die meerdere activiteiten beschikbaar maakt.

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

Volgende stappen