Schreiben eines Skillmanifests für Version 2.1How to write a v2.1 skill manifest

gilt für: SDK v4APPLIES TO: SDK v4

Ein Skillmanifest ist eine JSON-Datei, in der die ausführbaren Aktionen, die Ein- und Ausgabeparameter und die Endpunkte des Skills beschrieben werden.A skill manifest is a JSON file that describes the actions the skill can perform, its input and output parameters, and the skill's endpoints. Das Manifest enthält die Informationen, die ein Entwickler für den Zugriff auf den Skill in einem anderen Bot benötigt.The manifest contains the information a developer needs to access the skill from another bot. Mit Version 2.1 des Skillmanifestschemas kann das Manifest auch proaktive Aktivitäten, die der Skill senden kann, und Dispatchmodelle beschreiben, die der Skill verwendet.With v2.1 of the skill manifest schema, the manifest can also describe proactive activities the skill can send and dispatch models the skill uses.

Dieser Artikel beschreibt Version 2,1 des bot Framework-Fähigkeits manifest-Schemas.This article describes version 2.1 of the Bot Framework skill manifest schema. Eine Beschreibung der Version 2,0 finden Sie unter How to Write a v 2.0 Skills Manifest.For a description of version 2.0, see how to Write a v2.0 skill manifest.

Das Bot Framework-Skillmanifestschema verwendet Entwurf 7 des JSON-Schemavokabulars.The Bot Framework skill manifest schema uses draft 7 of the JSON schema vocabulary.

VoraussetzungenPrerequisites

Das SkillmanifestThe skill manifest

Das Skillmanifest enthält verschiedene Informationskategorien:The skill manifest contains different categories of information:

  • Metadaten, die den Skill auf allgemeiner Ebene beschreibenMetadata that describes the skill at a general level.
  • Eine Liste der Endpunkte, die der Skill bereitstelltA list of the endpoints that the skill provides.
  • Optionale Listen der Aktivitäten, die der Skill empfangen und proaktiv senden kannOptional lists of the activities the the skill can receive and proactively send.
  • Ein optionales Definitionsobjekt, das Schemas für Objekte enthält, auf die von anderen Teilen des Dokuments verwiesen wirdAn optional definitions object that contains schemas for objects referenced by other parts of the document.
  • Eine optionale Liste der vom Skill unterstützten DispatchmodelleAn optional list of the dispatch models the skill supports.

Es folgt das vollständige Schema für Version 2.1 des Bot Framework-Skillmanifests.The following is the full schema for v2.1 of the Bot Framework skill manifest.

Kategorie/FeldCategory/Field TypType ErforderlichRequired BeschreibungDescription
MetadatenMetadata
$id$id Zeichenfolgestring ErforderlichRequired Der Bezeichner des Skillmanifests.The identifier for the skill manifest.
$schema$schema Zeichenfolgestring ErforderlichRequired Die HTTPS-URI einer JSON-Schemaressource, die das Format des Manifests beschreibt.The HTTPS URI of a JSON schema resource that describes the format of the manifest. Für Version 2.1.0 ist der URI https://schemas.botframework.com/schemas/skills/v2.1/skill-manifest.json.For version 2.1.0, the URI is https://schemas.botframework.com/schemas/skills/v2.1/skill-manifest.json.
copyrightcopyright Zeichenfolgestring OptionalOptional Der Urheberrechtshinweis zum Skill.The copyright notice for the skill.
descriptiondescription Zeichenfolgestring OptionalOptional Eine von Menschen lesbare Beschreibung des Skills.A human-readable description of the skill.
iconUrliconUrl Zeichenfolgestring OptionalOptional Die URI des Symbols, das für den Skill angezeigt wird.The URI of the icon to show for the skill.
licenselicense Zeichenfolgestring OptionalOptional Die Lizenzbedingungen des Skills.The license agreement for the skill.
namename Zeichenfolgestring ErforderlichRequired Der Name des Skills.The name of the skill.
versionversion Zeichenfolgestring ErforderlichRequired Die Version des Skills, die im Manifest beschrieben wird.The version of the skill the manifest describes.
privacyUrlprivacyUrl Zeichenfolgestring OptionalOptional Der URI der Beschreibung der Datenschutzeinstellungen des Skills.The URI of the privacy description for the skill.
publisherNamepublisherName Zeichenfolgestring ErforderlichRequired Der Name des Herausgebers des Skills.The name of the skill publisher.
tagstags Zeichenfolgenarraystring array OptionalOptional Eine Gruppe von Tags für den Skill.A set of tags for the skill. Falls vorhanden, muss jedes Tag eindeutig sein.If present, each tag must be unique.
EndpunkteEndpoints
-Endpunkteendpoints Endpunktarrayendpoint array ErforderlichRequired Die Liste der vom Skill unterstützten Endpunkte.The list of endpoints supported by the skill. Mindestens ein Endpunkt muss definiert werden.At least one endpoint must be defined. Jeder Endpunkt muss eindeutig sein.Each endpoint must be unique.
AktivitätenActivities
activitiesactivities Objekt, das benannte Aktivitätsobjekte enthältobject containing named activity objects ErforderlichRequired Die Gruppe der anfänglichen Aktivitäten, die vom Skill akzeptiert werden.The set of initial activities accepted by the skill.
activitiesSentactivitiesSent Objekt mit benannten Aktivitätsobjektenobject containing named activity objects OptionalOptional Beschreibt die proaktiven Aktivitäten, die der Skill senden kann.Describes the proactive activities that the skill can send.
DefinitionenDefinitions
definitionsdefinitions Objekt (object)object OptionalOptional Ein Objekt, das Unterschemas für im Manifest verwendete Objekte enthält.An object containing subschemas for objects used in the manifest.
DispatchmodelleDispatch models
dispatchModelsdispatchModels dispatchModels-ObjektdispatchModels object OptionalOptional Beschreibt die vom Skill unterstützten Sprachmodelle und Absichten auf oberster Ebene.Describes the language models and top-level intents supported by the skill. Siehe unten für das Schema für dieses Objekt.See below for the schema for this object.

EndpunkteEndpoints

Jedes Endpunktobjekt beschreibt einen Endpunkt, der vom Skill unterstützt wird.Each endpoint object describes an endpoint supported by the skill.

Dieses Beispiel listet zwei Endpunkte für einen Skill auf.This example lists two endpoints for a skill.

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

Endpunktobjektendpoint object

Beschreibt einen vom Skill unterstützten Endpunkt.Describes an endpoint supported by the skill.

FeldField typeType ErforderlichRequired BESCHREIBUNGDescription
descriptiondescription Zeichenfolgestring OptionalOptional Eine Beschreibung des Endpunkts.A description of the endpoint.
endpointUrlendpointUrl Zeichenfolgestring ErforderlichRequired Der URI-Endpunkt des Skills.The URI endpoint for the skill.
msAppIdmsAppId Zeichenfolgestring ErforderlichRequired Die Microsoft AppId (GUID) des Skills zur Authentifizierung von Anforderungen.The Microsoft AppId (GUID) for the skill, used to authenticate requests.
namename Zeichenfolgestring ErforderlichRequired Der eindeutige Name des Endpunkts.The unique name for the endpoint.
Protokollprotocol Zeichenfolgestring OptionalOptional Das unterstützte Protokoll.The supported protocol. Standard ist BotFrameworkV3.Default is "BotFrameworkV3".

AktivitätenActivities

Jedes Aktivitätsobjekt beschreibt eine Aktivität, die vom Skill akzeptiert wird oder die der Skill proaktiv senden kann.Each activity object describes an activity accepted by the skill or one the skill can send proactively. Bei eingehenden Aktivitäten leitet der Skill eine Aktion oder Aufgabe ein, die auf der anfänglich empfangenen Aktivität basiert.For incoming activities, the skill will initiate an action or task based on the initial activity received. Der mit dem Aktivitätsobjekt verbundene Name gibt die Aktion oder Aufgabe an, die der Skill ausführt.The name associated with the activity object indicates the action or task the skill will perform.

Einige Aktivitätstypen haben eine Werteigenschaft, mit der dem Skill zusätzliche Eingaben bereitgestellt werden können.Some activity types have a value property that can be used to provide additional input to the skill. Wenn der Skill endet (die Aktion abschließt), kann er in der Werteigenschaft der zugehörigen Aktivität am Ende der Konversation einen Rückgabewert bereitstellen.When the skill ends (completes the action) it can provide a return value in the associated end-of-conversation activity's value property.

Die im Skillmanifestschema von v2.1.preview-1 zulässigen Aktivitätstypen sind Nachrichten-, Ereignis-, Aufruf- und andere Aktivitäten.The activity types allowed in the v2.1.preview-1 skill manifest schema are: message, event, invoke, and other activities. Ein Skill kann eine Aufrufaktivität empfangen, aber nicht senden.A skill can receive an invoke activity, but can't send one.

Dies ist eine Beispielbeschreibung einer Aktivität.This is a sample activity description.

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

eventActivity-ObjekteventActivity object

Beschreibt eine vom Skill akzeptierte oder gesendete Ereignisaktivität.Describes an event activity accepted or sent by the skill.

FeldField typeType ErforderlichRequired BESCHREIBUNGDescription
descriptiondescription Zeichenfolgestring OptionalOptional Eine Beschreibung der Aktion.A description of the action.
namename Zeichenfolgestring ErforderlichRequired Der Wert der Namenseigenschaft der Ereignisaktivität.The value of the event activity's name property.
resultValueresultValue Objekt (object)object OptionalOptional Eine JSON-Schemadefinition des Objekttyps, den die zugeordnete Aktion zurückgeben kann.A JSON schema definition of the type of object that the associated action can return.
typetype Zeichenfolgestring ErforderlichRequired Der Aktivitätstyp.The activity type. Muss „event“ sein.Must be "event".
valuevalue Objekt (object)object OptionalOptional Eine JSON-Schemadefinition des Objekttyps, den diese Aktion als Eingabe erwartet.A JSON schema definition of the type of object that this action expects as input.

invokeActivity-ObjektinvokeActivity object

Beschreibt eine Aufrufaktivität, die vom Skill akzeptiert wird.Describes an invoke activity accepted by the skill.

FeldField typeType ErforderlichRequired BESCHREIBUNGDescription
descriptiondescription Zeichenfolgestring OptionalOptional Eine Beschreibung der Aktion.A description of the action.
namename Zeichenfolgestring ErforderlichRequired Der Wert der Namenseigenschaft der Aufrufaktivität.The value of the invoke activity's name property.
resultValueresultValue Objekt (object)object OptionalOptional Eine JSON-Schemadefinition des Objekttyps, den die zugeordnete Aktion zurückgeben kann.A JSON schema definition of the type of object that the associated action can return.
typetype Zeichenfolgestring ErforderlichRequired Der Aktivitätstyp.The activity type. Muss „invoke“ sein.Must be "invoke".
valuevalue Objekt (object)object OptionalOptional Eine JSON-Schemadefinition des Objekttyps, den diese Aktion als Eingabe erwartet.A JSON schema definition of the type of object that this action expects as input.

messageActivity-ObjektmessageActivity object

Beschreibt eine vom Skill akzeptierte oder gesendete Nachrichtenaktivität.Describes a message activity accepted or sent by the skill. Die Texteigenschaft der Nachrichtenaktivität enthält die Äußerung des Benutzers.The message activity's text property contains the user's utterance.

FeldField typeType ErforderlichRequired BESCHREIBUNGDescription
descriptiondescription Zeichenfolgestring OptionalOptional Eine Beschreibung der Aktion.A description of the action.
resultValueresultValue Objekt (object)object OptionalOptional Eine JSON-Schemadefinition des Objekttyps, den die zugeordnete Aktion zurückgeben kann.A JSON schema definition of the type of object that the associated action can return.
typetype Zeichenfolgestring ErforderlichRequired Der Aktivitätstyp.The activity type. Muss „message“ sein.Must be "message".
valuevalue Objekt (object)object OptionalOptional Eine JSON-Schemadefinition des Objekttyps, den diese Aktion als Eingabe erwartet.A JSON schema definition of the type of object that this action expects as input.

otherActivities-ObjektotherActivities object

Beschreibt eine vom Skill akzeptierte oder gesendete Aktivität.Describes an activity accepted or sent by the skill.

FeldField typeType ErforderlichRequired BESCHREIBUNGDescription
typetype Zeichenfolgestring ErforderlichRequired Der Aktivitätstyp.The activity type. Muss einer der anderen Bot Framework-Aktivitätstypen sein: „contactRelationUpdate“, „conversationUpdate“, „deleteUserData“, „endOfConversation“, „handoff“, „installationUpdate“, „messageDelete“, „messageUpdate“, „messageReaction“, „suggestion“, „trace“ oder „typing“.Must be one of the other Bot Framework activity types: "contactRelationUpdate", "conversationUpdate", "deleteUserData", "endOfConversation", "handoff", "installationUpdate", "messageDelete", "messageUpdate", "messageReaction", "suggestion", "trace", or "typing".

Das otherActivities-Objekt kann andere Eigenschaften enthalten, aber das Skillmanifestschema definiert deren Bedeutung nicht.The otherActivities object can include other properties, but the skill manifest schema does not define their meaning.

DefinitionenDefinitions

Jede Definition beschreibt ein Unterschema, das von anderen Teilen des Dokuments genutzt werden kann.Each definition describes a subschema that can be consumed by other parts of the document.

Dies ist ein Beispiel eines Unterschemas für Flugbuchungsinformationen.This is a sample subschema for flight booking information.

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

DispatchmodelleDispatch models

Das Dispatchmodell enthält eine Liste von Sprachmodellen und eine Liste von Absichten auf oberster Ebene, die vom Skill unterstützt werden.The dispatch model contains a list of language models and a list of top-level intents supported by the skill. Dies ist ein erweitertes Feature, das es einem Entwickler eines Skillconsumers ermöglicht, ein Sprachmodell zu erstellen, das die Features des Consumers und der Skillbots kombiniert.This is an advanced feature to enable a developer of a skill consumer to compose a language model that combines the features of the consumer and skill bots.

Der Name eines Gebietsschemas ist eine Kombination aus einem aus zwei Kleinbuchstaben bestehenden ISO 639-Kulturcode, der einer Sprache zugeordnet ist, und einem optionalen aus zwei Großbuchstaben bestehenden ISO 3166-Unterkulturcode, der einem Land oder einer Region zugeordnet ist, z. B. „en“ oder „en-US“.A locale name is a combination of an ISO 639 two-letter lowercase culture code associated with a language and an optional ISO 3166 two-letter uppercase subculture code associated with a country or region, for example "en" or "en-US".

FeldField typeType ErforderlichRequired BESCHREIBUNGDescription
Absichtenintents Zeichenfolgenarraystring array OptionalOptional Eine Liste der Absichten auf oberster Ebene, die vom Skill unterstützt werden.A list of the top-level intents supported by the skill. Jede Absicht muss eindeutig sein.Each intent must be unique.
languageslanguages Objekt, das benannte languageModel-Arrays enthältobject containing named languageModel arrays ErforderlichRequired Eine Liste der vom Skill unterstützten Sprachmodelle.A list of the language models supported by the skill. Jeder Name ist das Gebietsschema, für das die Sprachmodelle bestimmt sind. Das Array enthält die Sprachmodule für das jeweilige Gebietsschema.Each name is the locale the language models are for, and the array contains the language modules for that locale. Ein Dispatchmodell muss mindestens ein Gebietsschema unterstützen.A dispatch model must support at least one locale. Jedes Gebietsschema innerhalb des Sprachenfelds muss eindeutig sein.Each locale within the languages field must be unique.

Dies ist ein Beispiel eines Dispatchmodells, das zwei Sprachmodelle für drei Gebietsschemas enthält.This is a sample dispatch model that contains two languages models across three locales. Es beschreibt auch zwei Absichten auf oberster Ebene, die der Skill erkennen kann.It also describes two top-level intents that the skill can recognize.

"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-ObjektlanguageModel object

Beschreibt ein Sprachmodell für eine bestimmte Kultur.Describes a language model for a given culture. Der Name ist ein Gebietsschemaname.The name is a locale name.

FeldField typeType ErforderlichRequired BESCHREIBUNGDescription
contentTypecontentType Zeichenfolgestring ErforderlichRequired Der Typ des Sprachmodells.Type of the language model.
descriptiondescription Zeichenfolgestring OptionalOptional Eine Beschreibung des Sprachmodells.A description of the language model.
namename Zeichenfolgestring ErforderlichRequired Der Name des Sprachmodells.Name of the language model.
urlurl Zeichenfolgestring ErforderlichRequired Der URL des Sprachmodells.The URL for the language model.

BeispielmanifestSample manifest

Dies ist ein vollständiges Beispiel eines Manifests der Version 2.1 für einen Skill, der mehrere Aktivitäten verfügbar macht.This is a full sample v2.1 manifest for a skill that exposes multiple activities.

{
    "$schema": "https://schemas.botframework.com/schemas/skills/v2.1/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": "https://myskill.contoso.com/icon.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"
                    }
                }
            }
        }
    }
}