Schreiben eines Skillmanifests für Version 2.0How to write a v2.0 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.

In diesem Artikel wird Version 2.0.0 des Bot Framework-Skillmanifestschemas beschrieben.This article describes version 2.0.0 of the Bot Framework skill manifest schema. Eine Beschreibung der Version 2,1 finden Sie unter Gewusst wie: Schreiben eines v 2.1-Fähigkeits Manifests.For a description of version 2.1, see how to Write a v2.1 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.
  • Eine optionale Liste der Aktivitäten, die der Skill empfangen kannAn optional list of the activities the the skill can receive.
  • 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.

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

Kategorie/FeldCategory/Field typeType 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 a JSON schema resource that describes the format of the manifest. Für Version 2.0.0 ist der URI https://schemas.botframework.com/schemas/skills/v2.0/skill-manifest.json.For version 2.0.0, the URI is https://schemas.botframework.com/schemas/skills/v2.0/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 mit benannten Aktivitätsobjektenobject 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.
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.

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

FeldField typeType ErforderlichRequired BESCHREIBUNGDescription
descriptiondescription Zeichenfolgestring OptionalOptional Eine Beschreibung des Endpunkts.A description for 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".

activitiesActivities

Jedes Aktivitätsobjekt beschreibt eine Aktivität, die vom Skill akzeptiert wird.Each activity object describes an activity accepted by the skill. Der Skill leitet eine Aktion oder Aufgabe ein, die auf der anfänglich empfangenen Aktivität basiert.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 der Version 2.0.0 zulässigen Aktivitätstypen sind Nachrichten-, Ereignis- und Aufrufaktivitäten.The activity types allowed in the v2.0.0 skill manifest schema are: message, event, and invoke activities.

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 Ereignisaktivität.Describes an event 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 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 Nachrichtenaktivität.Describes a message activity accepted 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.

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

BeispielmanifestSample manifest

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

{
    "$schema": "https://schemas.botframework.com/schemas/skills/v2.0/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"
        }
    ],
    "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"
        }
    },
    "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"
                }
            }
        }
    }
}