Megosztás a következőn keresztül:

Képességjegyzék írása

  • Cikk

A KÖVETKEZŐKRE VONATKOZIK: SDK v4

A képességjegyzék egy JSON-fájl, amely leírja a képesség által végrehajtható műveleteket, azok bemeneti és kimeneti paramétereit, valamint a képesség végpontjait. A jegyzék géppel olvasható információkat tartalmaz, amelyeket a fejlesztő felhasználhat egy másik robot képességeinek eléréséhez.

Ez a cikk a Bot Framework-képességjegyzék-séma támogatott verzióit ismerteti.

Verzió Jegyzetek
2.2-es verzió Frissített néhány URI-tulajdonságot az URI-hivatkozások elfogadásához.
2.1-es verzió Lehetővé teszi a készség által küldött proaktív tevékenységek leírását, valamint a képesség által használt küldési modelleket.
2.0-s verzió Kezdeti verzió.

A Bot Framework-képességjegyzék sémái a JSON-séma szókincsének 7. vázlatát használják.

Előfeltételek

A készségjegyzék

A képességjegyzék különböző információkategóriákat tartalmaz:

  • A készséget általános szinten leíró metaadatok.
  • A képesség által biztosított végpontok listája.
  • Nem kötelező felsorolni azokat a tevékenységeket, amelyekhez a képesség képes fogadni és proaktív módon küldeni.
  • Választható definícióobjektum, amely a dokumentum más részei által hivatkozott objektumok sémáit tartalmazza.
  • A képesség által támogatott diszpécsermodellek választható listája.

Az alábbi táblázat a Bot Framework-képességjegyzék 2.2-s verziójának teljes sémáját ismerteti.

Kategória/mező Típus/formátum Kötelező Leírás
Metaadatok
$id Sztring Szükséges A képességjegyzék azonosítója.
$schema Sztring/URI Szükséges A jegyzék formátumát leíró JSON-sémaerőforrás HTTPS URI-ja. A 2.2-es verzió esetében az URI a https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json.
Copyright Sztring Lehetséges A képesség szerzői jogi nyilatkozata.
leírás Sztring Lehetséges A képesség ember által olvasható leírása.
iconUrl Sztring/URI-referencia Lehetséges A képességhez megjelenítendő ikon URI-ja.
licenc Sztring Lehetséges A képesség licencszerződése.
név Sztring Szükséges A képesség neve.
privacyUrl Sztring/URI-referencia Lehetséges A képesség adatvédelmi leírásának URI-ja.
publisherName Sztring Szükséges A készség közzétevőjének neve.
tags Sztringtömb Lehetséges A képesség címkéinek készlete. Ha jelen van, minden címkének egyedinek kell lennie.
Verzió Sztring Szükséges A jegyzékben szereplő képesség verziója.
Végpontok
végpontok végponttömb Szükséges A képesség által támogatott végpontok listája. Legalább egy végpontot meg kell határozni. Minden végpontnak egyedinek kell lennie.
Tevékenységek
tevékenységek Elnevezett tevékenységobjektumokat tartalmazó objektum Lehetséges A készség által elfogadott kezdeti tevékenységek készlete.
activitiesSent Elnevezett tevékenységobjektumokat tartalmazó objektum Lehetséges Ismerteti azokat a proaktív tevékenységeket, amelyeket a képesség küldhet.
Meghatározások
Meghatározások Object Lehetséges A jegyzékben használt objektumok alkémáit tartalmazó objektum.
Diszpécsermodellek
dispatchModels dispatchModels objektum Lehetséges A képesség által támogatott nyelvi modelleket és legfelső szintű szándékokat ismerteti. Tekintse meg az objektum sémájának diszpécsermodelljeit .

Endpoints

Minden végpontobjektum a képesség által támogatott végpontot írja le.

Ez a példa két végpontot sorol fel egy képességhez.

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

végpontobjektum

A képesség által támogatott végpontot ismerteti.

Field Típus/formátum Kötelező Leírás
leírás Sztring Lehetséges A végpont leírása.
endpointUrl Sztring/URI Szükséges A képesség URI-végpontja.
msAppId Sztring Szükséges A kérések hitelesítéséhez használt képességhez tartozó Microsoft AppId (GUID) azonosító. Meg kell egyeznie a reguláris kifejezéssel: ^[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}$.
név Sztring Szükséges A végpont egyedi neve.
Protokoll Sztring Lehetséges A támogatott botprotokoll. Az alapértelmezett érték a "BotFrameworkV3", amely a Bot Csatlakozás or API 3-ás verzióját jelöli. Használja az alapértelmezett értéket, kivéve, ha a képesség kifejezetten más protokollt használ.

Tevékenységek

Minden tevékenységobjektum a képesség által elfogadott tevékenységet írja le. A képesség a kapott kezdeti tevékenység alapján elindít egy műveletet vagy feladatot. A tevékenységobjektumhoz társított név azt a műveletet vagy feladatot jelzi, amit a képesség végrehajt.

Egyes tevékenységtípusok értéktulajdonságokkal rendelkeznek, amelyekkel további bemenetet adhat a képességhez. Amikor a képesség befejeződik (befejezi a műveletet), visszaadhat egy értéket a kapcsolódó beszélgetésvégi tevékenység értéktulajdonságában.

Az engedélyezett tevékenységtípusok a következők: üzenet, esemény, meghívás és egyéb tevékenységek. Egy képesség meghívhat egy tevékenységet, de nem tud küldeni egyet.

Íme egy mintatevékenység leírása.

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

eventActivity objektum

A képesség által elfogadott vagy elküldött eseménytevékenységet ismerteti. Az eseménytevékenységek jelentését a névmező határozza meg, amely a képesség hatókörén belül értelmezhető.

Field Típus Kötelező Leírás
leírás Sztring Lehetséges Az esemény által kezdeményezett művelet leírása.
név Sztring Szükséges Az eseménytevékenység névtulajdonságának értéke.
resultValue Object Lehetséges A művelet által visszaadható objektumtípus JSON-sémadefiníciója.
típus Sztring Szükséges A tevékenység típusa. "eseménynek" kell lennie.
Érték Object Lehetséges A művelet által bemenetként várt objektumtípus JSON-sémadefiníciója.

invokeActivity objektum

A képesség által elfogadott meghívási tevékenységet ismerteti. A meghívási tevékenység jelentését a névmező határozza meg, amely a képesség hatókörén belül értelmezhető.

Field Típus Kötelező Leírás
leírás Sztring Lehetséges A meghívandó művelet leírása.
név Sztring Szükséges A meghívási tevékenység névtulajdonságának értéke.
resultValue Object Lehetséges A társított művelet által visszaadható objektumtípus JSON-sémadefiníciója.
típus Sztring Szükséges A tevékenység típusa. "meghívásnak" kell lennie.
Érték Object Lehetséges A művelet által bemenetként várt objektumtípus JSON-sémadefiníciója.

messageActivity objektum

A képesség által elfogadott vagy elküldött üzenettevékenységet ismerteti. Az üzenettevékenység szöveges tulajdonsága tartalmazza a felhasználó vagy a robot kimondott szövegét.

Field Típus Kötelező Leírás
leírás Sztring Lehetséges A művelet leírása.
resultValue Object Lehetséges A társított művelet által visszaadható objektumtípus JSON-sémadefiníciója.
típus Sztring Szükséges A tevékenység típusa. "üzenetnek" kell lennie.
Érték Object Lehetséges A művelet által bemenetként várt objektumtípus JSON-sémadefiníciója.

otherActivities objektum

A képesség által elfogadott vagy elküldött egyéb tevékenységtípusokat ismerteti.

Field Típus Kötelező Leírás
típus Sztring Szükséges A tevékenység típusa. A Bot Framework egyéb tevékenységtípusainak egyike kell, hogy legyen: "contactRelationUpdate", "conversationUpdate", "deleteUserData", "endOfConversation", "handoff", "installationUpdate", "messageDelete", "messageReaction", "messageUpdate", "suggestion", "trace", vagy "gépelés".

Az otherActivities objektum tartalmazhat más tulajdonságokat is, de a képességjegyzék-séma nem határozza meg a jelentésüket.

Definíciók

Minden definíció egy alkémát ír le, amelyet a dokumentum más részei is felhasználhatnak.

Íme egy minta alkéma a járatfoglalási információkhoz.

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

Diszpécsermodellek

A küldési modell tartalmazza a nyelvi modellek listáját és a képesség által támogatott legfelső szintű szándékok listáját. Ez egy speciális funkció, amely lehetővé teszi, hogy egy készségfelhasználó fejlesztője olyan nyelvi modellt írjon, amely egyesíti a fogyasztó és a készségrobotok funkcióit.

Minden nyelvi modell a .lu fájlformátumot használja .qna . További információ ezekről a formátumokról: .lu fájlformátum és .qna fájlformátum.

A területi név egy nyelvhez társított ISO 639 kétbetűs kisbetűs kulturális kód és egy országhoz vagy régióhoz társított opcionális ISO 3166 kétbetűs nagybetűs szubkultúrakód kombinációja, például "en" vagy "en-US".

Field Típus Kötelező Leírás
Cél Sztringtömb Lehetséges A képesség által támogatott legfelső szintű szándékok listája. Minden szándéknak egyedinek kell lennie.
nyelv Elnevezett languageModel-tömböket tartalmazó objektum Lehetséges A képesség által támogatott nyelvi modellek listája. Minden név a nyelvi modellek területi beállítása, a tömb pedig az adott területi beállításhoz tartozó nyelvi modelleket tartalmazza. A küldési modellnek legalább egy területi beállításnak támogatnia kell. A nyelvek mezőn belüli területi beállításoknak egyedinek kell lenniük.

Íme egy mintaküldési modell, amely két nyelvi modellt tartalmaz három területi beállítás között. Emellett két legfelső szintű szándékot is ismertet, amelyeket a képesség képes felismerni.

"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 objektum

Egy adott kultúra nyelvi modelljét ismerteti. A név területi név.

Field Típus/formátum Kötelező Leírás
contentType Sztring Szükséges A nyelvi modell típusa.
leírás Sztring Lehetséges A nyelvi modell leírása.
név Sztring Szükséges A nyelvi modell neve.
url Sztring/URI-referencia Szükséges A nyelvi modell URL-címe.

Mintajegyzék

Íme egy teljes minta v2.2 jegyzék egy olyan képességhez, amely több tevékenységet tesz elérhetővé.

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

Következő lépések