Udostępnij za pośrednictwem

Pisanie manifestu umiejętności

  • Artykuł

DOTYCZY: ZESTAW SDK w wersji 4

Manifest umiejętności to plik JSON, który opisuje akcje, które może wykonać umiejętność, jego parametry wejściowe i wyjściowe oraz punkty końcowe umiejętności. Manifest zawiera informacje czytelne dla komputera, których deweloper może użyć do uzyskania dostępu do umiejętności innego bota.

W tym artykule opisano obsługiwane wersje schematu manifestu umiejętności platformy Bot Framework.

Wersja Uwagi
wersja 2.2 Zaktualizowano niektóre właściwości identyfikatora URI, aby akceptowały odwołania do identyfikatora URI.
wersja 2.1 Dodaje możliwość opisywania proaktywnych działań, które umiejętności mogą wysyłać i wysyłać modele używane przez umiejętności.
wersja 2.0 Wersja początkowa.

Schematy manifestu umiejętności platformy Bot Framework używają wersji roboczej 7 słownictwa schematu JSON.

Wymagania wstępne

Manifest umiejętności

Manifest umiejętności zawiera różne kategorie informacji:

  • Metadane opisujące umiejętności na poziomie ogólnym.
  • Lista punktów końcowych zapewnianych przez umiejętności.
  • Opcjonalne listy działań, które umiejętności mogą odbierać i proaktywnie wysyłać.
  • Opcjonalny obiekt definicji, który zawiera schematy obiektów, do których odwołuje się inne części dokumentu.
  • Opcjonalna lista modeli wysyłania, które obsługuje umiejętność.

W poniższej tabeli opisano pełny schemat manifestu umiejętności platformy Bot Framework w wersji 2.2.

Kategoria/pole Typ/format Wymagania opis
Metadane
$id Ciąg Wymagania Identyfikator manifestu umiejętności.
$schema Ciąg/identyfikator URI Wymagania Identyfikator URI HTTPS zasobu schematu JSON opisujący format manifestu. W przypadku wersji 2.2 identyfikator URI to https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json.
informacji o prawach autorskich, Ciąg Opcjonalnie Powiadomienie o prawach autorskich do umiejętności.
opis Ciąg Opcjonalnie Czytelny dla człowieka opis umiejętności.
iconUrl Odwołanie do ciągu/identyfikatora URI Opcjonalnie Identyfikator URI ikony, który ma być wyświetlany dla umiejętności.
license (licencja) Ciąg Opcjonalnie Umowa licencyjna dotycząca umiejętności.
nazwa String Wymagania Nazwa umiejętności.
privacyUrl Odwołanie do ciągu/identyfikatora URI Opcjonalnie Identyfikator URI opisu prywatności dla umiejętności.
publisherName Ciąg Wymagania Nazwa wydawcy umiejętności.
tags Tablica ciągów Opcjonalnie Zestaw tagów umiejętności. Jeśli jest obecny, każdy tag musi być unikatowy.
version String Wymagania Wersja umiejętności opisanej w manifeście.
Punkty końcowe
punkty końcowe tablica punktów końcowych Wymagania Lista punktów końcowych obsługiwanych przez umiejętności. Należy zdefiniować co najmniej jeden punkt końcowy. Każdy punkt końcowy musi być unikatowy.
Działania
activities Obiekt zawierający nazwane obiekty działania Opcjonalnie Zestaw początkowych działań przyjętych przez umiejętności.
activitiesSent Obiekt zawierający nazwane obiekty działania Opcjonalnie Opisuje aktywne działania, które mogą wysyłać umiejętności.
Definicje
Definicje Obiekt Opcjonalnie Obiekt zawierający podsieci dla obiektów używanych w manifeście.
Wysyłanie modeli
dispatchModels dispatchModels , obiekt Opcjonalnie Opisuje modele językowe i intencje najwyższego poziomu obsługiwane przez umiejętności. Zobacz Wysyłanie modeli schematu dla tego obiektu.

Punkty końcowe

Każdy obiekt punktu końcowego opisuje punkt końcowy obsługiwany przez tę umiejętność.

W tym przykładzie wymieniono dwa punkty końcowe dla umiejętności.

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

obiekt punktu końcowego

Opisuje punkt końcowy obsługiwany przez umiejętności.

Pole Typ/format Wymagania opis
opis Ciąg Opcjonalnie Opis punktu końcowego.
endpointUrl Ciąg/identyfikator URI Wymagania Punkt końcowy identyfikatora URI dla umiejętności.
identyfikator msAppId Ciąg Wymagania Identyfikator GUID (Microsoft AppId) dla umiejętności używany do uwierzytelniania żądań. Musi być zgodne z wyrażeniem regularnym: ^[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}$.
nazwa String Wymagania Unikatowa nazwa punktu końcowego.
Protokół Ciąg Opcjonalnie Obsługiwany protokół bota. Wartość domyślna to "BotFrameworkV3", która reprezentuje interfejs API bota Połączenie or w wersji 3. Użyj wartości domyślnej, chyba że umiejętności będą używać innego protokołu.

Działania

Każdy obiekt działania opisuje działanie zaakceptowane przez umiejętności. Umiejętność rozpoczyna akcję lub zadanie na podstawie początkowego odbieranego działania. Nazwa skojarzona z obiektem działania wskazuje akcję lub zadanie, które wykona umiejętność.

Niektóre typy działań mają właściwość wartości, która może służyć do zapewnienia dodatkowych danych wejściowych umiejętności. Gdy umiejętność kończy (kończy akcję), może ona podać wartość zwracaną we skojarzonej właściwości wartości końca konwersacji.

Dozwolone typy działań to: komunikat, zdarzenie, wywołanie i inne działania. Umiejętność może odbierać działanie wywołania, ale nie może go wysłać.

Oto przykładowy opis działania.

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

eventActivity, obiekt

Opisuje działanie zdarzenia zaakceptowane lub wysłane przez umiejętności. Znaczenie działania zdarzenia jest definiowane przez jego pole nazwy, które ma znaczenie w zakresie umiejętności.

Pole Type Wymagani opis
opis Ciąg Opcjonalnie Opis akcji, która powinna zostać zainicjowana przez zdarzenie.
nazwa String Wymagania Wartość właściwości name działania zdarzenia.
resultValue Obiekt Opcjonalnie Definicja schematu JSON typu obiektu, który może zwrócić akcja.
type Ciąg Wymagania Typ działania. Musi być "zdarzenie".
wartość Obiekt Opcjonalnie Definicja schematu JSON typu obiektu oczekiwanego przez tę akcję jako dane wejściowe.

invokeActivity, obiekt

Opisuje działanie wywołania zaakceptowane przez umiejętności. Znaczenie działania wywołania jest definiowane przez jego pole nazwy, które ma znaczenie w zakresie umiejętności.

Pole Type Wymagani opis
opis Ciąg Opcjonalnie Opis akcji, która powinna zostać zainicjowana przez wywołanie.
nazwa String Wymagania Wartość właściwości invoke activity's name.
resultValue Obiekt Opcjonalnie Definicja schematu JSON typu obiektu, który może zwrócić skojarzona akcja.
type Ciąg Wymagania Typ działania. Musi być "wywołaj".
wartość Obiekt Opcjonalnie Definicja schematu JSON typu obiektu oczekiwanego przez tę akcję jako dane wejściowe.

messageActivity, obiekt

Opisuje działanie komunikatu zaakceptowane lub wysłane przez umiejętności. Właściwość tekstowa działania komunikatu zawiera wypowiedź użytkownika lub bota.

Pole Type Wymagani opis
opis Ciąg Opcjonalnie Opis akcji.
resultValue Obiekt Opcjonalnie Definicja schematu JSON typu obiektu, który może zwrócić skojarzona akcja.
type Ciąg Wymagania Typ działania. Musi mieć wartość "message".
wartość Obiekt Opcjonalnie Definicja schematu JSON typu obiektu oczekiwanego przez tę akcję jako dane wejściowe.

otherActivities, obiekt

Opisuje dowolny inny typ działania zaakceptowany lub wysłany przez umiejętności.

Pole Type Wymagani opis
type Ciąg Wymagania Typ działania. Musi być jednym z innych typów działań platformy Bot Framework: "contactRelationUpdate", "conversationUpdate", "deleteUserData", "endOfConversation", "handoff", "installationUpdate", "messageDelete", "messageReaction", "messageUpdate", "suggestion", "trace" lub "typing".

Inny obiektActivities może zawierać inne właściwości, ale schemat manifestu umiejętności nie definiuje ich znaczenia.

Definicje

Każda definicja opisuje podschemę, która może być zużywana przez inne części dokumentu.

Oto przykładowa podschema na potrzeby informacji o rezerwacji lotów.

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

Wysyłanie modeli

Model wysyłania zawiera listę modeli językowych i listę intencji najwyższego poziomu obsługiwanych przez umiejętności. Jest to zaawansowana funkcja umożliwiająca deweloperowi konsumenta umiejętności tworzenie modelu językowego, który łączy funkcje botów konsumenckich i umiejętności.

Każdy model językowy używa .lu formatu pliku lub .qna . Aby uzyskać więcej informacji na temat tych formatów, zobacz format pliku lu i format pliku qna.

Nazwa ustawień regionalnych jest kombinacją dwuliterowego kodu kultury iso 639 skojarzonego z językiem i opcjonalnym dwuliterowym kodem subkultury iso 3166 skojarzonym z krajem lub regionem, na przykład "en" lub "en-US".

Pole Type Wymagani opis
Zamiarów Tablica ciągów Opcjonalnie Lista intencji najwyższego poziomu obsługiwanych przez umiejętności. Każda intencja musi być unikatowa.
języki Obiekt zawierający nazwane tablice languageModel Opcjonalnie Lista modeli językowych obsługiwanych przez umiejętności. Każda nazwa to ustawienia regionalne, dla których znajdują się modele językowe, a tablica zawiera modele językowe dla tych ustawień regionalnych. Model wysyłania musi obsługiwać co najmniej jedno ustawienia regionalne. Każde ustawienia regionalne w polu języków musi być unikatowe.

Oto przykładowy model wysyłania zawierający dwa modele języków w trzech ustawieniach regionalnych. Opisano w nim również dwie intencje najwyższego poziomu, które mogą rozpoznać umiejętności.

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

Opisuje model językowy dla danej kultury. Nazwa jest nazwą ustawień regionalnych.

Pole Typ/format Wymagania opis
Contenttype Ciąg Wymagania Typ modelu językowego.
opis Ciąg Opcjonalnie Opis modelu językowego.
nazwa String Wymagania Nazwa modelu językowego.
Adres URL Odwołanie do ciągu/identyfikatora URI Wymagania Adres URL modelu językowego.

Przykładowy manifest

Oto pełny przykładowy manifest w wersji 2.2 dla umiejętności, która uwidacznia wiele działań.

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

Następne kroki