如何撰寫 v2.1 技能資訊清單How to write a v2.1 skill manifest

適用于: SDK v4APPLIES TO: SDK v4

「技能資訊清單」 是 JSON 檔案,描述技能可執行的動作、其輸入和輸出參數,以及技能的端點。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. 資訊清單包含讓開發人員從另一個 Bot 存取技能所需的資訊。The manifest contains the information a developer needs to access the skill from another bot. 在 2.1 版的技能資訊清單結構描述中,資訊清單也可描述技能可以傳送及分派技能所用模型的主動式活動。With v2.1 of the skill manifest schema, the manifest can also describe proactive activities the skill can send and dispatch models the skill uses.

本文描述 Bot Framework 技能資訊清單架構的 2.1 版This article describes version 2.1 of the Bot Framework skill manifest schema. 如需2.0 版的說明,請參閱如何 撰寫 v2.0 技能資訊清單For a description of version 2.0, see how to Write a v2.0 skill manifest.

Bot Framework 技能資訊清單結構描述會使用 JSON 結構描述詞彙的 Draft 7 版。The Bot Framework skill manifest schema uses draft 7 of the JSON schema vocabulary.

PrerequisitesPrerequisites

技能資訊清單The skill manifest

技能資訊清單包含不同類別的資訊:The skill manifest contains different categories of information:

  • 描述一般層級技能的中繼資料。Metadata that describes the skill at a general level.
  • 技能所提供的端點清單。A list of the endpoints that the skill provides.
  • 技能可以接收並主動傳送的選擇性活動清單。Optional lists of the activities the the skill can receive and proactively send.
  • 選擇性的定義物件,其中包含文件其他部分所參考的物件結構描述。An optional definitions object that contains schemas for objects referenced by other parts of the document.
  • 技能支援的分派模型選擇性清單。An optional list of the dispatch models the skill supports.

以下是適用於 Bot Framework 技能資訊清單 v2.1 的完整結構描述。The following is the full schema for v2.1 of the Bot Framework skill manifest.

類別/欄位Category/Field 類型Type 必要Required 描述Description
中繼資料Metadata
$id$id 字串string 必要Required 技能資訊清單的識別碼。The identifier for the skill manifest.
$schema$schema 字串string 必要Required JSON 結構描述資源 (用於描述資訊清單格式) 的 HTTPS URI。The HTTPS URI of a JSON schema resource that describes the format of the manifest. 若為版本 2.1.0,URI 為 https://schemas.botframework.com/schemas/skills/v2.1/skill-manifest.jsonFor version 2.1.0, the URI is https://schemas.botframework.com/schemas/skills/v2.1/skill-manifest.json.
著作權copyright 字串string 選用Optional 技能的著作權注意事項。The copyright notice for the skill.
descriptiondescription 字串string 選用Optional 人類看得懂的技能描述。A human-readable description of the skill.
iconUrliconUrl 字串string 選用Optional 要針對技能顯示的圖示 URI。The URI of the icon to show for the skill.
授權license 字串string 選用Optional 技能的授權合約。The license agreement for the skill.
NAMEname 字串string 必要Required 技能的名稱。The name of the skill.
versionversion 字串string 必要Required 資訊清單所描述的技能版本。The version of the skill the manifest describes.
privacyUrlprivacyUrl 字串string 選用Optional 技能的隱私權描述 URI。The URI of the privacy description for the skill.
publisherNamepublisherName 字串string 必要Required 技能發行者的名稱。The name of the skill publisher.
tagstags 字串陣列string array 選用Optional 技能的一組標記。A set of tags for the skill. 如果有,每個標記都必須是唯一的。If present, each tag must be unique.
端點Endpoints
端點endpoints 端點陣列endpoint array 必要Required 技能所支援的端點清單。The list of endpoints supported by the skill. 至少必須定義一個端點。At least one endpoint must be defined. 每個端點都必須是唯一的。Each endpoint must be unique.
活動Activities
活動activities 包含具名活動物件的物件object containing named activity objects 必要Required 技能所接受的一組初始活動。The set of initial activities accepted by the skill.
activitiesSentactivitiesSent 包含具名活動物件的物件object containing named activity objects 選用Optional 描述技能可以傳送的主動式活動。Describes the proactive activities that the skill can send.
定義Definitions
定義definitions 物件 (object)object 選用Optional 物件會包含資訊清單中所使用物件的次結構描述。An object containing subschemas for objects used in the manifest.
分派模型Dispatch models
dispatchModelsdispatchModels dispatchModels 物件dispatchModels object 選用Optional 描述技能所支援的語言模型和最上層意圖。Describes the language models and top-level intents supported by the skill. 請參閱 下面 的此物件的架構。See below for the schema for this object.

端點Endpoints

每個端點物件都會描述技能所支援的端點。Each endpoint object describes an endpoint supported by the skill.

此範例會列出技能的兩個端點。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"
    }
],

端點物件endpoint object

描述技能所支援的端點。Describes an endpoint supported by the skill.

欄位Field 類型Type 必要Required 描述Description
descriptiondescription 字串string 選用Optional 端點的描述。A description of the endpoint.
endpointUrlendpointUrl 字串string 必要Required 技能的 URI 端點。The URI endpoint for the skill.
msAppIdmsAppId 字串string 必要Required 技能的 Microsoft AppId (GUID),用於驗證要求。The Microsoft AppId (GUID) for the skill, used to authenticate requests.
NAMEname 字串string 必要Required 端點的唯一名稱。The unique name for the endpoint.
protocolprotocol 字串string 選用Optional 支援的通訊協定。The supported protocol. 預設值為 "BotFrameworkV3"。Default is "BotFrameworkV3".

活動Activities

每個活動物件都會描述技能所接受的活動,或是技能可以主動傳送的活動。Each activity object describes an activity accepted by the skill or one the skill can send proactively. 針對傳入活動,技能將根據收到的初始活動起始動作或工作。For incoming activities, the skill will initiate an action or task based on the initial activity received. 與活動物件相關聯的名稱會指出技能將執行的動作或工作。The name associated with the activity object indicates the action or task the skill will perform.

某些活動類型具有值屬性,可用來提供技能的額外輸入。Some activity types have a value property that can be used to provide additional input to the skill. 當技能結束時 (完成動作),其可以在相關聯的結束交談活動值屬性中提供傳回值。When the skill ends (completes the action) it can provide a return value in the associated end-of-conversation activity's value property.

v2.1.preview-1 技能資訊清單結構描述中允許的活動類型為:訊息、事件、叫用和「其他」活動。The activity types allowed in the v2.1.preview-1 skill manifest schema are: message, event, invoke, and other activities. 技能可以接收叫用活動,但無法傳送叫用活動。A skill can receive an invoke activity, but can't send one.

這是活動描述範例。This is a sample activity description.

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

eventActivity 物件eventActivity object

描述技能所接受或傳送的事件活動。Describes an event activity accepted or sent by the skill.

欄位Field 類型Type 必要Required 描述Description
descriptiondescription 字串string 選用Optional 動作的描述。A description of the action.
NAMEname 字串string 必要Required 事件活動的名稱屬性值。The value of the event activity's name property.
resultValueresultValue 物件 (object)object 選用Optional 相關聯動作所傳回物件類型的 JSON 結構描述定義。A JSON schema definition of the type of object that the associated action can return.
typetype 字串string 必要Required 活動類型。The activity type. 必須是 "event"。Must be "event".
valuevalue 物件 (object)object 選用Optional JSON 結構描述定義,用於定義此動作預期作為輸入的物件類型。A JSON schema definition of the type of object that this action expects as input.

invokeActivity 物件invokeActivity object

描述技能所接受的叫用活動。Describes an invoke activity accepted by the skill.

欄位Field 類型Type 必要Required 描述Description
descriptiondescription 字串string 選用Optional 動作的描述。A description of the action.
NAMEname 字串string 必要Required 叫用活動名稱屬性的值。The value of the invoke activity's name property.
resultValueresultValue 物件 (object)object 選用Optional 相關聯動作所傳回物件類型的 JSON 結構描述定義。A JSON schema definition of the type of object that the associated action can return.
typetype 字串string 必要Required 活動類型。The activity type. 必須是 "invoke"。Must be "invoke".
valuevalue 物件 (object)object 選用Optional JSON 結構描述定義,用於定義此動作預期作為輸入的物件類型。A JSON schema definition of the type of object that this action expects as input.

messageActivity 物件messageActivity object

描述技能所接受或傳送的訊息活動。Describes a message activity accepted or sent by the skill. 訊息活動文字屬性會包含使用者的語句。The message activity's text property contains the user's utterance.

欄位Field 類型Type 必要Required 描述Description
descriptiondescription 字串string 選用Optional 動作的描述。A description of the action.
resultValueresultValue 物件 (object)object 選用Optional 相關聯動作所傳回物件類型的 JSON 結構描述定義。A JSON schema definition of the type of object that the associated action can return.
typetype 字串string 必要Required 活動類型。The activity type. 必須是 "message"。Must be "message".
valuevalue 物件 (object)object 選用Optional JSON 結構描述定義,用於定義此動作預期作為輸入的物件類型。A JSON schema definition of the type of object that this action expects as input.

otherActivities 物件otherActivities object

描述技能接受或傳送的活動。Describes an activity accepted or sent by the skill.

欄位Field 類型Type 必要Required 描述Description
typetype 字串string 必要Required 活動類型。The activity type. 必須是其他 Bot Framework 活動類型的其中一個:"contactRelationUpdate"、"conversationUpdate"、"deleteUserData"、"endOfConversation"、"handoff"、"installationUpdate"、"messageDelete"、"messageUpdate"、"messageReaction"、"suggestion"、"trace" 或 "typing"。Must be one of the other Bot Framework activity types: "contactRelationUpdate", "conversationUpdate", "deleteUserData", "endOfConversation", "handoff", "installationUpdate", "messageDelete", "messageUpdate", "messageReaction", "suggestion", "trace", or "typing".

OtherActivities 物件可以包含其他屬性,但技能資訊清單結構描述不會定義其意義。The otherActivities object can include other properties, but the skill manifest schema does not define their meaning.

定義Definitions

每個定義都會描述可供文件其他部分使用的次結構描述。Each definition describes a subschema that can be consumed by other parts of the document.

這是航班預約資訊的次結構描述範例。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"
        }
    }
},

分派模型Dispatch models

分派模型包含語言模型清單,以及技能所支援的最上層意圖清單。The dispatch model contains a list of language models and a list of top-level intents supported by the skill. 這是一項先進的功能,可讓技能取用者的開發人員撰寫語言模型,以結合取用者與技能 Bot 的功能。This is an advanced feature to enable a developer of a skill consumer to compose a language model that combines the features of the consumer and skill bots.

地區名稱會結合與語言相關聯的 ISO 639 文化特性代碼 (兩個小寫字母),以及與國家或地區相關聯的選用 ISO 3166 子文化特性代碼 (兩個大寫字母),例如 "en" 或 "en-US"。A locale name is a combination of an ISO 639 two-letter lowercase culture code associated with a language and an optional ISO 3166 two-letter uppercase subculture code associated with a country or region, for example "en" or "en-US".

欄位Field 類型Type 必要Required 描述Description
意圖intents 字串陣列string array 選用Optional 技能所支援的最上層意圖清單。A list of the top-level intents supported by the skill. 每個意圖都必須是唯一的。Each intent must be unique.
語言languages 物件,包含具名 languageModel 的陣列object containing named languageModel arrays 必要Required 技能所支援的語言模型清單。A list of the language models supported by the skill. 每個名稱都是語言模型適用的地區,而陣列會包含該地區的語言模組。Each name is the locale the language models are for, and the array contains the language modules for that locale. 分派模型必須支援至少一個地區。A dispatch model must support at least one locale. [語言] 欄位內的每個地區都必須是唯一的。Each locale within the languages field must be unique.

這是一個分派模型範例,其中包含三個地區上的兩種語言模型。This is a sample dispatch model that contains two languages models across three locales. 其也會描述技能可以辨識的兩個最上層意圖。It also describes two top-level intents that the skill can recognize.

"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 物件languageModel object

描述指定文化特性的語言模型。Describes a language model for a given culture. 名稱是地區名稱。The name is a locale name.

欄位Field 類型Type 必要Required 描述Description
ContentTypecontentType 字串string 必要Required 語言模型的類型。Type of the language model.
descriptiondescription 字串string 選用Optional 語言模型的描述。A description of the language model.
NAMEname 字串string 必要Required 語言模型的名稱。Name of the language model.
urlurl 字串string 必要Required 語言模型的 URL。The URL for the language model.

資訊清單範例Sample manifest

這是完整的 v2.1 資訊清單範例,以可公開多個活動的技能為例。This is a full sample v2.1 manifest for a skill that exposes multiple activities.

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