Sdílet prostřednictvím

Napsání manifestu dovednosti

  • Článek

PLATÍ PRO: SDK v4

Manifest dovednosti je soubor JSON, který popisuje akce, které může dovednost provést, její vstupní a výstupní parametry a koncové body dovednosti. Manifest obsahuje strojově čitelné informace, které může vývojář použít pro přístup ke dovednostem z jiného robota.

Tento článek popisuje podporované verze schématu manifestu dovedností služby Bot Framework.

Verze Notes
verze 2.2 Aktualizovali jsme některé vlastnosti identifikátoru URI tak, aby přijímaly odkazy na identifikátor URI.
verze 2.1 Přidává možnost popisovat proaktivní aktivity, které dovednost může posílat, a modely odeslání, které dovednost používá.
verze 2.0 Počáteční verze

Schémata manifestu dovedností služby Bot Framework používají koncept 7 slovníku schématu JSON.

Předpoklady

Manifest dovednosti

Manifest dovednosti obsahuje různé kategorie informací:

  • Metadata, která popisují dovednosti na obecné úrovni.
  • Seznam koncových bodů, které dovednost poskytuje.
  • Volitelné seznamy aktivit, které může dovednost přijímat a aktivně posílat.
  • Volitelný objekt definic, který obsahuje schémata pro objekty odkazované jinými částmi dokumentu.
  • Volitelný seznam modelů odeslání, které dovednost podporuje.

Následující tabulka popisuje úplné schéma manifestu dovedností služby Bot Framework verze 2.2.

Kategorie nebo pole Typ/formát Požadováno Popis
Metadata
$id Řetězec Požaduje se Identifikátor manifestu dovednosti.
$schema Řetězec/identifikátor URI Požaduje se Identifikátor URI HTTPS prostředku schématu JSON, který popisuje formát manifestu. Pro verzi 2.2 je https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.jsonidentifikátor URI .
Copyright Řetězec Volitelné Oznámení o autorských právech pro dovednost.
description Řetězec Volitelné Popis dovednosti čitelný člověkem.
iconUrl Řetězcový/identifikátor URI – referenční dokumentace Volitelné Identifikátor URI ikony, který se má zobrazit pro dovednost.
license Řetězec Volitelné Licenční smlouva pro dovednost.
name Řetězec Požaduje se Název dovednosti.
privacyUrl Řetězcový/identifikátor URI – referenční dokumentace Volitelné Identifikátor URI popisu ochrany osobních údajů pro dovednost.
publisherName Řetězec Požaduje se Název vydavatele dovedností.
značek Pole řetězců Volitelné Sada značek pro dovednost. V případě přítomnosti musí být každá značka jedinečná.
version Řetězec Požaduje se Verze dovednosti, která manifest popisuje.
Koncové body
koncové body pole koncového bodu Požaduje se Seznam koncových bodů podporovaných dovedností Musí být definován alespoň jeden koncový bod. Každý koncový bod musí být jedinečný.
Aktivity
activities Objekt obsahující pojmenované objekty aktivity Volitelné Sada počátečních aktivit přijatých dovedností.
activitiesSent Objekt obsahující pojmenované objekty aktivity Volitelné Popisuje proaktivní aktivity, které může dovednost odeslat.
Definice
Definice Objekt Volitelné Objekt obsahující dílčíschemas pro objekty použité v manifestu.
Modely odesílání
dispatchModels dispatchModels – objekt Volitelné Popisuje jazykové modely a záměry nejvyšší úrovně podporované dovedností. Viz Modely Dispatch pro schéma pro tento objekt.

Koncové body

Každý objekt koncového bodu popisuje koncový bod podporovaný dovedností.

Tento příklad uvádí dva koncové body pro dovednost.

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

objekt koncového bodu

Popisuje koncový bod podporovaný dovedností.

Pole Typ/formát Požadováno Popis
description Řetězec Volitelné Popis koncového bodu
endpointUrl Řetězec/identifikátor URI Požaduje se Koncový bod identifikátoru URI pro dovednost.
msAppId Řetězec Požaduje se Identifikátor GUID (Microsoft AppId) dovednosti, který se používá k ověřování požadavků. Musí odpovídat regulárnímu výrazu: ^[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 Řetězec Požaduje se Jedinečný název koncového bodu.
Protokol Řetězec Volitelné Podporovaný protokol robota. Výchozí hodnota je BotFrameworkV3, která představuje rozhraní API Připojení or verze 3. Pokud vaše dovednost nepoužívá jiný protokol, použijte výchozí hodnotu.

Aktivity

Každý objekt aktivity popisuje aktivitu přijatou dovedností. Dovednost zahájí akci nebo úkol na základě počáteční aktivity, kterou obdrží. Název přidružený k objektu aktivity označuje akci nebo úkol, který bude dovednost provádět.

Některé typy aktivit mají vlastnost hodnoty, kterou lze použít k poskytnutí dodatečného vstupu dovednosti. Když dovednost skončí (dokončí akci), může poskytnout návratovou hodnotu ve vlastnosti hodnoty přidružené aktivity ukončení konverzace.

Povolené typy aktivit jsou: zpráva, událost, vyvolání a další aktivity. Dovednost může obdržet aktivitu vyvolání, ale nemůže ji odeslat.

Tady je popis ukázkové aktivity.

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

eventActivity – objekt

Popisuje aktivitu události přijatou nebo poslanou dovedností. Význam aktivity události je definován jeho polem názvu, což je smysluplné v rámci oboru dovednosti.

Pole Type Požaduje se Popis
description Řetězec Volitelné Popis akce, která má událost zahájit.
name Řetězec Požaduje se Hodnota vlastnosti názvu aktivity události.
resultValue Objekt Volitelné Definice schématu JSON typu objektu, který akce může vrátit.
type Řetězec Požaduje se Typ aktivity. Musí to být událost.
hodnota Objekt Volitelné Definice schématu JSON typu objektu, který tato akce očekává jako vstup.

invokeActivity – objekt

Popisuje aktivitu vyvolání přijatou dovedností. Význam aktivity vyvolání je definován jeho polem názvu, což je smysluplné v rámci oboru dovednosti.

Pole Type Požaduje se Popis
description Řetězec Volitelné Popis akce, která se vyvolá, by měl inicializovat.
name Řetězec Požaduje se Hodnota vlastnosti názvu aktivity vyvolání.
resultValue Objekt Volitelné Definice schématu JSON typu objektu, který může přidružená akce vrátit.
type Řetězec Požaduje se Typ aktivity. Musí se jednat o vyvolání.
hodnota Objekt Volitelné Definice schématu JSON typu objektu, který tato akce očekává jako vstup.

messageActivity – objekt

Popisuje aktivitu zpráv přijatou nebo poslanou dovedností. Textová vlastnost aktivity zprávy obsahuje promluvu uživatele nebo robota.

Pole Type Požaduje se Popis
description Řetězec Volitelné Popis akce.
resultValue Objekt Volitelné Definice schématu JSON typu objektu, který může přidružená akce vrátit.
type Řetězec Požaduje se Typ aktivity. Musí to být zpráva.
hodnota Objekt Volitelné Definice schématu JSON typu objektu, který tato akce očekává jako vstup.

objekt otherActivities

Popisuje jakýkoli jiný typ aktivity, který akceptoval nebo odeslal dovednost.

Pole Type Požaduje se Popis
type Řetězec Požaduje se Typ aktivity. Musí to být jeden z ostatních typů aktivit Bot Frameworku: contactRelationUpdate, conversationUpdate, deleteUserData, endOfConversation, handoff, installationUpdate, messageDelete, messageReaction, messageUpdate, messageUpdate, messageUpdate, suggestion, trace nebo typeing.

Objekt otherActivities může obsahovat další vlastnosti, ale schéma manifestu dovednosti nedefinuje jejich význam.

Definice

Každá definice popisuje subschema, kterou mohou využívat jiné části dokumentu.

Tady je ukázka subschema pro informace o rezervacích letů.

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

Modely odesílání

Model odeslání obsahuje seznam jazykových modelů a seznam záměrů nejvyšší úrovně podporovaných dovedností. Jedná se o pokročilou funkci, která vývojářům dovednosti umožňuje vytvořit jazykový model, který kombinuje funkce robotů uživatelů a dovedností.

Každý jazykový model používá .lu formát nebo .qna formát souboru. Další informace o těchto formátech naleznete ve formátu souboru .lu a formátu souboru .qna.

Název národního prostředí je kombinace dvoumísmenného kódu jazykové verze ISO 639 s malými písmeny asociovaná s jazykem a volitelný dvoumísmenným kódem subculture ISO 3166 přidruženým k zemi nebo oblasti, například "en" nebo "en-US".

Pole Type Požaduje se Popis
Záměry Pole řetězců Volitelné Seznam záměrů nejvyšší úrovně podporovaných dovedností Každý záměr musí být jedinečný.
jazyky Objekt obsahující pole languageModel s názvem Volitelné Seznam jazykových modelů podporovaných dovedností. Každý název je národní prostředí, pro které jsou jazykové modely určené, a pole obsahuje jazykové modely pro dané národní prostředí. Model odeslání musí podporovat alespoň jedno národní prostředí. Každé národní prostředí v poli jazyků musí být jedinečné.

Tady je ukázkový model odeslání, který obsahuje dva jazykové modely napříč třemi národními prostředími. Popisuje také dva záměry nejvyšší úrovně, které dovednost dokáže rozpoznat.

"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

Popisuje jazykový model pro danou jazykovou verzi. Název je název národního prostředí.

Pole Typ/formát Požadováno Popis
Contenttype Řetězec Požaduje se Typ jazykového modelu
description Řetězec Volitelné Popis jazykového modelu
name Řetězec Požaduje se Název jazykového modelu.
url Řetězcový/identifikátor URI – referenční dokumentace Požaduje se Adresa URL jazykového modelu.

Ukázkový manifest

Tady je kompletní ukázka manifestu verze 2.2 pro dovednost, která zveřejňuje více aktivit.

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

Další kroky