Dela via

Skriva ett kunskapsmanifest

  • Artikel

GÄLLER FÖR: SDK v4

Ett färdighetsmanifest är en JSON-fil som beskriver de åtgärder som en färdighet kan vidta, dess indata- och utdataparametrar och kunskapens slutpunkter. Manifestet innehåller maskinläsbar information som en utvecklare kan använda för att komma åt kunskapen från en annan robot.

I den här artikeln beskrivs vilka versioner av Bot Framework-schemat för kunskapsmanifest som stöds.

Version: OBS!
version 2.2 Vissa URI-egenskaper har uppdaterats för att acceptera URI-referenser.
version 2.1 Lägger till möjligheten att beskriva proaktiva aktiviteter som färdigheten kan skicka och de sändningsmodeller som kunskapen använder.
version 2.0 Ursprunglig version.

Scheman för Bot Framework-färdighetsmanifestet använder utkast 7 i JSON-schemaförrådet.

Förutsättningar

Kunskapsmanifestet

Kunskapsmanifestet innehåller olika informationskategorier:

  • Metadata som beskriver kunskapen på allmän nivå.
  • En lista över slutpunkterna som färdigheten tillhandahåller.
  • Valfria listor över aktiviteter som färdigheten kan ta emot och skicka proaktivt.
  • Ett valfritt definitionsobjekt som innehåller scheman för objekt som refereras av andra delar av dokumentet.
  • En valfri lista över de sändningsmodeller som färdigheten stöder.

I följande tabell beskrivs det fullständiga schemat för v2.2 i Bot Framework-kunskapsmanifestet.

Kategori/fält Typ/format Obligatoriskt Beskrivning
Metadata
$id String Obligatoriskt Identifieraren för kunskapsmanifestet.
$schema Sträng/URI Obligatoriskt HTTPS-URI:n för en JSON-schemaresurs som beskriver manifestets format. För version 2.2 är https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.jsonURI:n .
Copyright String Valfritt Upphovsrättsmeddelandet för färdigheten.
beskrivning String Valfritt En människoläsbar beskrivning av skickligheten.
iconUrl Sträng/URI-referens Valfri URI:n för ikonen som ska visas för färdigheten.
licens String Valfritt Licensavtalet för färdigheten.
name String Obligatoriskt Namnet på färdigheten.
privacyUrl Sträng/URI-referens Valfri URI:n för sekretessbeskrivningen för färdigheten.
publisherName String Obligatoriskt Namnet på kunskapsutgivaren.
tags Strängmatris Valfri En uppsättning taggar för kunskapen. Om den finns måste varje tagg vara unik.
version Sträng Obligatoriskt Den version av färdigheten som manifestet beskriver.
Slutpunkter
slutpunkter slutpunktsmatris Obligatoriskt Listan över slutpunkter som stöds av färdigheten. Minst en slutpunkt måste definieras. Varje slutpunkt måste vara unik.
Aktiviteter
activities Objekt som innehåller namngivna aktivitetsobjekt Valfri Den uppsättning inledande aktiviteter som godkänts av färdigheten.
activitiesSent Objekt som innehåller namngivna aktivitetsobjekt Valfri Beskriver de proaktiva aktiviteter som färdigheten kan skicka.
Definitioner
Definitioner Objekt Valfri Ett objekt som innehåller underscheman för objekt som används i manifestet.
Dispatch-modeller
dispatchModels dispatchModels-objekt Valfri Beskriver de språkmodeller och avsikter på toppnivå som stöds av färdigheten. Se Dispatch models for the schema for this object (Skicka modeller för schemat för det här objektet).

Slutpunkter

Varje slutpunktsobjekt beskriver en slutpunkt som stöds av färdigheten.

I det här exemplet visas två slutpunkter för en färdighet.

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

slutpunktsobjekt

Beskriver en slutpunkt som stöds av färdigheten.

Fält Typ/format Obligatoriskt Beskrivning
beskrivning String Valfritt En beskrivning av slutpunkten.
endpointUrl Sträng/URI Obligatoriskt URI-slutpunkten för färdigheten.
msAppId String Obligatoriskt Microsoft AppId (GUID) för färdigheten som används för att autentisera begäranden. Måste matcha det reguljära uttrycket: ^[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 Obligatoriskt Slutpunktens unika namn.
Protokollet String Valfritt Bot-protokollet som stöds. Standardvärdet är "BotFrameworkV3", som representerar roboten Anslut eller API version 3. Använd standardvärdet om inte din färdighet specifikt använder ett annat protokoll.

Aktiviteter

Varje aktivitetsobjekt beskriver en aktivitet som godkänts av färdigheten. Färdigheten påbörjar en åtgärd eller uppgift baserat på den inledande aktiviteten som den tar emot. Namnet som är associerat med aktivitetsobjektet anger den åtgärd eller uppgift som färdigheten ska utföra.

Vissa aktivitetstyper har en värdeegenskap som kan användas för att ge extra indata till färdigheten. När kunskapen slutar (slutför åtgärden) kan den ge ett returvärde i den associerade värdeegenskapen för aktiviteten i slutet av konversationen.

De aktivitetstyper som tillåts är: meddelande, händelse, anropa och andra aktiviteter. En färdighet kan ta emot en anropande aktivitet, men kan inte skicka någon.

Här är en exempelaktivitetsbeskrivning.

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

eventActivity-objekt

Beskriver en händelseaktivitet som godkänts eller skickats av färdigheten. Innebörden av en händelseaktivitet definieras av dess namnfält, vilket är meningsfullt inom kompetensens omfång.

Fält Type Obligatoriskt Beskrivning
beskrivning String Valfritt En beskrivning av åtgärden som händelsen ska initiera.
name String Obligatoriskt Värdet för händelseaktivitetens namnegenskap.
resultValue Objekt Valfri En JSON-schemadefinition för den typ av objekt som åtgärden kan returnera.
type String Obligatoriskt Aktivitetstypen. Måste vara "händelse".
värde Objekt Valfri En JSON-schemadefinition av den typ av objekt som den här åtgärden förväntar sig som indata.

invokeActivity-objekt

Beskriver en anropande aktivitet som godkänts av färdigheten. Innebörden av en anropande aktivitet definieras av dess namnfält, vilket är meningsfullt inom kompetensens omfång.

Fält Type Obligatoriskt Beskrivning
beskrivning String Valfritt En beskrivning av den åtgärd som anropar ska initieras.
name String Obligatoriskt Värdet för anropa aktivitetens namnegenskap.
resultValue Objekt Valfri En JSON-schemadefinition av den typ av objekt som den associerade åtgärden kan returnera.
type String Obligatoriskt Aktivitetstypen. Måste vara "invoke".
värde Objekt Valfri En JSON-schemadefinition av den typ av objekt som den här åtgärden förväntar sig som indata.

messageActivity-objekt

Beskriver en meddelandeaktivitet som godkänts eller skickats av färdigheten. Meddelandeaktivitetens textegenskap innehåller användarens eller robotens yttrande.

Fält Type Obligatoriskt Beskrivning
beskrivning String Valfritt En beskrivning av åtgärden.
resultValue Objekt Valfri En JSON-schemadefinition av den typ av objekt som den associerade åtgärden kan returnera.
type String Obligatoriskt Aktivitetstypen. Måste vara "meddelande".
värde Objekt Valfri En JSON-schemadefinition av den typ av objekt som den här åtgärden förväntar sig som indata.

otherActivities-objekt

Beskriver alla andra aktivitetstyper som godkänts eller skickats av färdigheten.

Fält Type Obligatoriskt Beskrivning
type String Obligatoriskt Aktivitetstypen. Måste vara någon av de andra Robot Framework-aktivitetstyperna: "contactRelationUpdate", "conversationUpdate", "deleteUserData", "endOfConversation", "handoff", "installationUpdate", "messageDelete", "messageReaction", "messageUpdate", "suggestion", "trace" eller "typing".

Objektet otherActivities kan innehålla andra egenskaper, men schemat för färdighetsmanifestet definierar inte deras innebörd.

Definitioner

Varje definition beskriver ett underschema som kan användas av andra delar av dokumentet.

Här är ett exempel på ett underschema för flygbokningsinformation.

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

Dispatch-modeller

Sändningsmodellen innehåller en lista över språkmodeller och en lista över avsikter på den översta nivån som stöds av färdigheten. Det är en avancerad funktion som gör det möjligt för utvecklare av en kunskapskonsument att skapa en språkmodell som kombinerar funktionerna i konsumentrobotar och kunskapsrobotar.

Varje språkmodell använder filformatet .lu eller .qna . Mer information om dessa format finns i .lu-filformat och .qna-filformat.

Ett språknamn är en kombination av en ISO 639-kod med två bokstäver som är associerad med ett språk och en valfri ISO 3166-kod med två bokstäver som är associerad med ett land eller en region, till exempel "en" eller "en-US".

Fält Type Obligatoriskt Beskrivning
Avseenden Strängmatris Valfri En lista över de avsikter på den översta nivån som stöds av färdigheten. Varje avsikt måste vara unik.
språk Objekt som innehåller namngivna languageModel-matriser Valfri En lista över de språkmodeller som stöds av färdigheten. Varje namn är språkmodellernas språkvariant och matrisen innehåller språkmodellerna för språket. En sändningsmodell måste ha stöd för minst ett språk. Varje språkspråk i språkfältet måste vara unikt.

Här är ett exempel på en sändningsmodell som innehåller två språkmodeller på tre språk. Den beskriver också två avsikter på toppnivå som kunskapen kan känna igen.

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

Beskriver en språkmodell för en viss kultur. Namnet är ett språknamn.

Fält Typ/format Obligatoriskt Beskrivning
Contenttype String Obligatoriskt Typ av språkmodell.
beskrivning String Valfritt En beskrivning av språkmodellen.
name String Obligatoriskt Namn på språkmodellen.
url Sträng/URI-referens Obligatoriskt URL:en för språkmodellen.

Exempelmanifest

Här är ett fullständigt exempel på v2.2-manifest för en färdighet som exponerar flera aktiviteter.

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

Nästa steg