Schreiben eines Skillmanifests

  • Artikel

GILT FÜR: SDK v4

Ein Skillmanifest ist eine JSON-Datei, die die Aktionen, die ein Skill ausführen kann, seine Eingabe- und Ausgabeparameter sowie die Endpunkte des Skills beschreibt. Das Manifest enthält maschinenlesbare Informationen, die ein Entwickler verwenden kann, um von einem anderen Bot auf den Skill zuzugreifen.

Dieser Artikel beschreibt die unterstützten Versionen des Skillmanifest-Schemas von Bot Framework.

Version Hinweise
Version 2.2 Einige URI-Eigenschaften wurden aktualisiert, um URI-Verweise zu akzeptieren.
Version 2.1 Bietet die Möglichkeit, proaktive Aktivitäten zu beschreiben, die der Skill senden kann und die Versandmodelle, die der Skill verwendet.
Version 2.0 Ursprüngliche Version.

Das Bot Framework-Skillmanifestschema verwendet Entwurf 7 des JSON-Schemavokabulars.

Voraussetzungen

Das Skillmanifest

Das Skillmanifest enthält verschiedene Informationskategorien:

  • Metadaten, die den Skill auf allgemeiner Ebene beschreiben
  • Eine Liste der Endpunkte, die der Skill bereitstellt
  • Optionale Listen der Aktivitäten, die der Skill empfangen und proaktiv senden kann.
  • Ein optionales Definitionsobjekt, das Schemas für Objekte enthält, auf die von anderen Teilen des Dokuments verwiesen wird
  • Eine optionale Liste der vom Skill unterstützten Dispatchmodelle

In der folgenden Tabelle wird das vollständige Schema für Version 2.2 des Bot Framework-Skillmanifests beschrieben.

Kategorie/Feld Typ/Format Erforderlich Beschreibung
Metadaten
$id String Erforderlich Der Bezeichner des Skillmanifests.
$schema Zeichenkette/URI Erforderlich Die HTTPS-URI einer JSON-Schemaressource, die das Format des Manifests beschreibt. Für Version 2.2 ist der URI https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json.
copyright String Optional Der Urheberrechtshinweis zum Skill.
Beschreibung String Optional Eine von Menschen lesbare Beschreibung des Skills.
iconUrl Zeichenketten/URI-Referenz Optional Die URI des Symbols, das für den Skill angezeigt wird.
Lizenz String Optional Die Lizenzbedingungen des Skills.
name String Erforderlich Der Name des Skills.
privacyUrl Zeichenketten/URI-Referenz Optional Der URI der Beschreibung der Datenschutzeinstellungen des Skills.
publisherName String Erforderlich Der Name des Herausgebers des Skills.
Tags Zeichenfolgenarray Optional Eine Gruppe von Tags für den Skill. Falls vorhanden, muss jedes Tag eindeutig sein.
version String Erforderlich Die Version des Skills, die im Manifest beschrieben wird.
Endpunkte
-Endpunkte Endpunktarray Erforderlich Die Liste der vom Skill unterstützten Endpunkte. Mindestens ein Endpunkt muss definiert werden. Jeder Endpunkt muss eindeutig sein.
Aktivitäten
activities Objekt mit benannten Aktivitätsobjekten Optional Die Gruppe der anfänglichen Aktivitäten, die vom Skill akzeptiert werden.
activitiesSent Objekt mit benannten Aktivitätsobjekten Optional Beschreibt die proaktiven Aktivitäten, die der Skill senden kann.
Definitionen
definitions Object Optional Ein Objekt, das Unterschemas für im Manifest verwendete Objekte enthält.
Dispatchmodelle
dispatchModels dispatchModels-Objekt Optional Beschreibt die vom Skill unterstützten Sprachmodelle und Absichten auf oberster Ebene. Informationen zu Versandmodellen zu diesem Schema finden Sie unter:

Endpunkte

Jedes Endpunktobjekt beschreibt einen Endpunkt, der vom Skill unterstützt wird.

Dieses Beispiel listet zwei Endpunkte für einen Skill auf.

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

Endpunktobjekt

Beschreibt einen vom Skill unterstützten Endpunkt.

Feld Typ/Format Erforderlich Beschreibung
Beschreibung String Optional Eine Beschreibung des Endpunkts.
endpointUrl Zeichenkette/URI Erforderlich Der URI-Endpunkt des Skills.
msAppId String Erforderlich Die Microsoft AppId (GUID) des Skills zur Authentifizierung von Anforderungen. Muss mit dem regulären Ausdruck übereinstimmen: ^[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 Erforderlich Der eindeutige Name des Endpunkts.
Protokoll String Optional Das unterstützte Bot-Protokoll. Der Standardwert ist „BotFrameworkV3“, der die Bot-Connector-API Version 3 darstellt. Verwenden Sie den Standardwert, es sei denn, Ihr Skill verwendet speziell ein anderes Protokoll.

Aktivitäten

Jedes Aktivitätsobjekt beschreibt eine Aktivität, die vom Skill akzeptiert wird. Der Skill leitet eine Aktion oder Aufgabe ein, die auf der anfänglich empfangenen Aktivität basiert. Der mit dem Aktivitätsobjekt verbundene Name gibt die Aktion oder Aufgabe an, die der Skill ausführt.

Einige Aktivitätstypen haben eine Werteigenschaft, mit der dem Skill zusätzliche Eingaben bereitgestellt werden können. 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.

Die zulässigen Aktivitätstypen sind: Nachricht, Ereignis, Aufruf und andere Aktivitäten. Ein Skill kann eine Aufrufaktivität empfangen, aber nicht senden.

Hier ist eine Beispielbeschreibung einer Aktivität.

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

eventActivity-Objekt

Beschreibt eine vom Skill akzeptierte oder gesendete Ereignisaktivität. Die Bedeutung einer Ereignisaktivität wird durch das Feld Name definiert, das innerhalb des Bereichs des Skills gilt.

Feld type Erforderlich Beschreibung
Beschreibung String Optional Eine Beschreibung der Aktion, die das Ereignis initiieren soll.
name String Erforderlich Der Wert der Namenseigenschaft der Ereignisaktivität.
resultValue Object Optional Eine JSON-Schemadefinition des Objekttyps, den die Aktion zurückgeben kann.
Typ String Erforderlich Der Aktivitätstyp. Muss „event“ sein.
value Object Optional Eine JSON-Schemadefinition des Objekttyps, den diese Aktion als Eingabe erwartet.

invokeActivity-Objekt

Beschreibt eine Aufrufaktivität, die vom Skill akzeptiert wird. Die Bedeutung einer Aufrufaktivität wird durch das Feld Name definiert, das innerhalb des Bereichs des Skills gilt.

Feld type Erforderlich Beschreibung
Beschreibung String Optional Eine Beschreibung der Aktion, die der Aufruf initiieren soll.
name String Erforderlich Der Wert der Namenseigenschaft der Aufrufaktivität.
resultValue Object Optional Eine JSON-Schemadefinition des Objekttyps, den die zugeordnete Aktion zurückgeben kann.
Typ String Erforderlich Der Aktivitätstyp. Muss „invoke“ sein.
value Object Optional Eine JSON-Schemadefinition des Objekttyps, den diese Aktion als Eingabe erwartet.

messageActivity-Objekt

Beschreibt eine vom Skill akzeptierte oder gesendete Nachrichtenaktivität. Die Texteigenschaft der Nachrichtenaktivität enthält die Äußerung des Benutzers oder des Bots.

Feld type Erforderlich Beschreibung
Beschreibung String Optional Eine Beschreibung der Aktion.
resultValue Object Optional Eine JSON-Schemadefinition des Objekttyps, den die zugeordnete Aktion zurückgeben kann.
Typ String Erforderlich Der Aktivitätstyp. Muss „message“ sein.
value Object Optional Eine JSON-Schemadefinition des Objekttyps, den diese Aktion als Eingabe erwartet.

otherActivities-Objekt

Beschreibt jeden anderen Aktivitätstyp, der von dem Skill akzeptiert oder gesendet wird.

Feld type Erforderlich BESCHREIBUNG
type String Erforderlich Der Aktivitätstyp. Muss einer der anderen Bot Framework-Aktivitätstypen sein: „contactRelationUpdate“, „conversationUpdate“, „deleteUserData“, „endOfConversation“, „handoff“, „installationUpdate“, „messageDelete“, „messageReaction“, „messageUpdate“, „suggestion“, „trace“ oder „typing“.

Das otherActivities-Objekt kann andere Eigenschaften enthalten, aber das Skillmanifestschema definiert deren Bedeutung nicht.

Definitionen

Jede Definition beschreibt ein Unterschema, das von anderen Teilen des Dokuments genutzt werden kann.

Hier ist ein Beispiel eines Unterschemas für Flugbuchungsinformationen.

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

Dispatchmodelle

Das Dispatchmodell enthält eine Liste von Sprachmodellen und eine Liste von Absichten auf oberster Ebene, die vom Skill unterstützt werden. Es 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.

Jedes Sprachmodell verwendet das .lu- oder .qna-Dateiformat. Weitere Informationen zu diesen Formaten finden Sie unter .lu-Dateiformat und .qna-Dateiformat.

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“.

Feld type Erforderlich Beschreibung
Absichten Zeichenfolgenarray Optional Eine Liste der Absichten auf oberster Ebene, die vom Skill unterstützt werden. Jede Absicht muss eindeutig sein.
languages Objekt, das benannte languageModel-Arrays enthält Optional Eine Liste der vom Skill unterstützten Sprachmodelle. Jeder Name ist das Gebietsschema, für das die Sprachmodelle bestimmt sind. Das Array enthält die Sprachmodelle für das jeweilige Gebietsschema. Ein Dispatchmodell muss mindestens ein Gebietsschema unterstützen. Jedes Gebietsschema innerhalb des Sprachenfelds muss eindeutig sein.

Hier ist ein Beispiel eines Dispatchmodells, das zwei Sprachmodelle für drei Gebietsschemas enthält. Es beschreibt auch zwei Absichten auf oberster Ebene, die der Skill erkennen kann.

"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

Beschreibt ein Sprachmodell für eine bestimmte Kultur. Der Name ist ein Gebietsschemaname.

Feld Typ/Format Erforderlich Beschreibung des Dataflows
contentType String Erforderlich Der Typ des Sprachmodells.
Beschreibung String Optional Eine Beschreibung des Sprachmodells.
name String Erforderlich Der Name des Sprachmodells.
url Zeichenketten/URI-Referenz Erforderlich Der URL des Sprachmodells.

Beispielmanifest

Hier ist ein vollständiges Beispiel eines Manifests der Version 2.2 für einen Skill, der mehrere Aktivitäten verfügbar macht.

{
    "$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ächste Schritte