撰寫技能資訊清單

  • 發行項

適用于： SDK v4

技能資訊清單 是 JSON 檔案，描述技能可採取的動作、其輸入和輸出參數，以及技能的端點。 資訊清單包含開發人員可用來從另一個 Bot 存取技能的電腦可讀取資訊。

本文說明 Bot Framework 技能資訊清單架構的支援版本。

版本 備註
2.2 版 已更新一些 URI 屬性以接受 URI 參考。
2.1 版 新增描述技能可傳送的主動式活動的能力，以及技能所使用的分派模型。
2.0 版 初始版本。

Bot Framework 技能資訊清單架構會使用 JSON 架構詞彙的草稿 7 。

必要條件

技能資訊清單

技能資訊清單包含不同的資訊類別：

  • 描述一般層級技能的中繼資料。
  • 技能所提供的端點清單。
  • 技能可以接收並主動傳送的活動選擇性清單。
  • 選擇性定義物件，其中包含檔其他部分所參考之物件的架構。
  • 技能支援的分派模型選擇性清單。

下表描述 Bot Framework 技能資訊清單 v2.2 的完整架構。

類別/欄位 類型/格式 必要 描述
中繼資料
$id String 必要 技能資訊清單的識別碼。
$schema 字串/URI 必要 描述資訊清單格式的 JSON 架構資源的 HTTPS URI。 針對 2.2 版，URI 為 https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json 。
著作權 String 選擇性 技能的著作權聲明。
description String 選擇性 技能的人類可讀描述。
iconUrl 字串/URI-reference 選擇性 要針對技能顯示之圖示的 URI。
license (授權) String 選擇性 技能的授權合約。
NAME String 必要 技能的名稱。
privacyUrl 字串/URI-reference 選擇性 技能隱私權描述的 URI。
publisherName String 必要 技能發行者的名稱。
tags 字串陣列 選擇性 技能的一組標記。 如果存在，每個標籤都必須是唯一的。
version String 必要 資訊清單描述的技能版本。
端點
端點 端點 陣列 必要 技能支援的端點清單。 至少必須定義一個端點。 每個端點都必須是唯一的。
活動
activities 包含具名 活動物件的物件 選擇性 技能接受的初始活動集。
activitiesSent 包含具名 活動物件的物件 選擇性 描述技能可以傳送的主動式活動。
定義
定義 Object 選擇性 物件，包含資訊清單中使用的物件子化學。
分派模型
dispatchModels dispatchModels 物件 選擇性 描述技能所支援的語言模型和最上層意圖。 如需此物件的架構，請參閱 分派模型 。

端點

每個端點物件描述技能所支援的端點。

此範例會列出技能的兩個端點。

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

描述技能所支援的端點。

欄位 類型/格式 必要 描述
description String 選擇性 端點的描述。
endpointUrl 字串/URI 必要 技能的 URI 端點。
msAppId String 必要 用於驗證要求的技能的 Microsoft AppId （GUID）。 必須符合正則運算式： ^[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 必要 端點的唯一名稱。
protocol String 選擇性 支援的 Bot 通訊協定。 預設值為 「BotFrameworkV3」，代表 Bot 連線or API 第 3 版。 除非您的技能特別使用不同的通訊協定，否則請使用預設值。

活動

每個活動物件描述技能所接受的活動。 技能會根據收到的初始活動開始動作或工作。 與活動物件相關聯的名稱表示技能將執行的動作或工作。

某些活動類型具有值屬性，可用來為技能提供額外的輸入。 技能結束時（完成動作），它可以在相關聯的交談結束活動值屬性中提供傳回值。

允許的活動類型包括：訊息、事件、叫 用和其他 活動。 技能可以接收叫用活動，但無法傳送。

以下是範例活動描述。

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

eventActivity 物件

描述技能接受或傳送的事件活動。 事件活動的意義是由其名稱欄位所定義，這在技能範圍內有意義。

欄位 類型 必填 描述
description String 選擇性 事件應起始之動作的描述。
NAME String 必要 事件活動名稱屬性的值。
resultValue Object 選擇性 動作可以傳回之物件類型的 JSON 架構定義。
type String 必要 活動類型。 必須是 「event」。
value Object 選擇性 此動作預期做為輸入的物件類型的 JSON 架構定義。

invokeActivity 物件

描述技能所接受的叫用活動。 叫用活動的意義是由其名稱欄位所定義，這在技能範圍內有意義。

欄位 類型 必填 描述
description String 選擇性 叫用應起始之動作的描述。
NAME String 必要 叫用活動之 name 屬性的值。
resultValue Object 選擇性 關聯動作可以傳回之物件類型的 JSON 架構定義。
type String 必要 活動類型。 必須是 「invoke」。
value Object 選擇性 此動作預期做為輸入的物件類型的 JSON 架構定義。

messageActivity 物件

描述技能所接受或傳送的訊息活動。 訊息活動的文字屬性包含使用者的或 Bot 語句。

欄位 類型 必填 描述
description String 選擇性 動作的描述。
resultValue Object 選擇性 關聯動作可以傳回之物件類型的 JSON 架構定義。
type String 必要 活動類型。 必須是 「message」。
value Object 選擇性 此動作預期做為輸入的物件類型的 JSON 架構定義。

otherActivities 物件

描述技能接受或傳送的任何其他活動類型。

欄位 類型 必填 描述
type String 必要 活動類型。 必須是其他 Bot Framework 活動類型之一：「contactRelationUpdate」、「conversationUpdate」、「deleteUserData」、「endOfConversation」、「handoff」、「installationUpdate」、「messageDelete」、「messageReaction」、「messageUpdate」、「messageUpdate」、「suggestion」、「trace」 或 「typing」。

otherActivities 物件可以包含其他屬性，但技能資訊清單架構並未定義其意義。

定義

每個定義都會描述檔其他部分可以使用的子架構。

以下是航班預訂資訊的範例子架構。

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

分派模型

分派模型包含語言模型清單，以及技能所支援的最上層意圖清單。 這是一項進階功能，可讓技能取用者的開發人員撰寫語言模型，以結合取用者和技能 Bot 的功能。

每個語言模型都會使用 .lu 或 .qna 檔案格式。 如需這些格式的詳細資訊，請參閱 .lu 檔案格式 和 .qna 檔案格式 。

地區設定名稱是與語言相關聯的 ISO 639 雙字母小寫文化特性代碼組合，以及與國家或地區相關聯的選擇性 ISO 3166 雙字母大寫子文化特性代碼，例如 「en」 或 「en-US」。

欄位 類型 必填 描述
意圖 字串陣列 選擇性 技能所支援的最上層意圖清單。 每個意圖都必須是唯一的。
語言 包含具名 languageModel 陣列的物件 選擇性 技能支援的語言模型清單。 每個名稱都是語言模型所針對的地區設定，而陣列包含該地區設定的語言模型。 分派模型必須至少支援一個地區設定。 語言欄位中的每個地區設定都必須是唯一的。

以下是一個範例分派模型，其中包含三個地區設定的兩種語言模型。 它也會描述技能可辨識的兩個最上層意圖。

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

描述指定文化特性的語言模型。 名稱是地區設定名稱。

欄位 類型/格式 必要 描述
contentType String 必要 語言模型的類型。
description String 選擇性 語言模型的描述。
NAME String 必要 語言模型的名稱。
url 字串/URI-reference 必要 語言模型的 URL。

範例資訊清單

以下是公開多個活動的技能的完整範例 v2.2 資訊清單。

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

下一步