Создание манифеста навыков

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: ПАКЕТ SDK версии 4

Манифест навыка — это JSON-файл, описывающий действия, которые могут предпринять навык, его входные и выходные параметры, а также конечные точки навыка. Манифест содержит сведения, доступные для чтения компьютером, разработчик может использовать для доступа к навыку из другого бота.

В этой статье описываются поддерживаемые версии схемы манифеста навыка Bot Framework.

Версия Примечания.
версия 2.2 Обновлены некоторые свойства URI, чтобы принимать ссылки на URI.
Версия 2.1 Добавляет возможность описать упреждающие действия, которые навык может отправлять, и модели отправки, которые использует навык.
Версия 2.0 Начальная версия.

Схемы манифеста навыка Bot Framework используют черновик 7 словаря схемы JSON.

Необходимые компоненты

Манифест навыка

Манифест навыка содержит разные категории информации:

  • метаданные, описывающие навык на общем уровне;
  • список конечных точек, предоставляемых навыком;
  • Необязательные списки действий, которые навык может получать и заранее отправлять.
  • необязательный объект определений, содержащий схемы для объектов, на которые ссылаются другие части документа;
  • необязательный список моделей отправки, поддерживаемых навыком.

В следующей таблице описана полная схема манифеста навыка Bot Framework версии 2.2.

Категория или поле Тип или формат Обязательное поле Description
Метаданные
$id Строка Обязательное поле Идентификатор манифеста навыка.
$schema Строковый/универсальный код ресурса (URI) Обязательное поле Универсальный код ресурса (URI) схемы JSON в формате HTTPS, описывающий формат манифеста. Для версии 2.2 универсальный код ресурса (URI) имеет значение https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json.
copyright Строка Необязательно Уведомление об авторских правах на этот навык.
description Строка Необязательно Понятное описание навыка.
iconUrl String/URI-reference Необязательно Универсальный код ресурса (URI) значка, отображаемого для навыка.
лицензия Строка Необязательно Лицензионное соглашение для навыка.
имя Строка Обязательное поле Имя навыка.
privacyUrl String/URI-reference Необязательно Универсальный код ресурса (URI) сведений о конфиденциальности для навыка.
publisherName Строка Обязательное поле Имя издателя навыка.
tags Массив строк Необязательно Набор тегов для навыка. Если он есть, каждый тег должен быть уникальным.
версия Строка Обязательное поле Версия навыка, который описывает манифест.
Конечные точки
конечные точки Массив элементов endpoint. Обязательное поле Список конечных точек, поддерживаемых навыком. Необходимо определить хотя бы одну конечную точку. Имя каждой конечной точки должно быть уникальным.
Действия
activities Объект, содержащий именованные объекты действия Необязательно Набор начальных действий, принимаемых навыком.
activitiesSent Объект, содержащий именованные объекты действия Необязательно Описывает упреждающие действия, которые могут быть отправлены навыком.
Определения
политики Объект Необязательно Объект, содержащий вложенные схемы для объектов, используемых в манифесте.
Модели отправки
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
description Строка Необязательно Описание конечной точки.
endpointUrl Строковый/универсальный код ресурса (URI) Обязательное поле Универсальный код ресурса (URI) конечной точки для навыка.
msAppId Строка Обязательное поле Идентификатор 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}$.
имя Строка Обязательное поле Уникальное имя конечной точки.
protocol Строка Необязательно Поддерживаемый протокол Bot. Значение по умолчанию — BotFrameworkV3, представляющее API бота Подключение or версии 3. Используйте значение по умолчанию, если навык не использует другой протокол.

Процедуры

Каждый объект действия описывает действие, принимаемое навыком. Навык начинает действие или задачу на основе начального действия, которое он получает. Имя, связанное с объектом действия, указывает действие или задачу, которая будет выполнена навыком.

Некоторые типы действий имеют свойство value, которое можно использовать для предоставления дополнительных входных данных навыку. Когда навык заканчивается (завершает действие), он может предоставить возвращаемое значение в связанном свойстве значения действия завершения беседы.

Допустимые типы действий: сообщение, событие, вызов и другие действия. Навык может получать действие вызова, но не может его отправлять.

Ниже приведено описание действия.

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

Объект eventActivity

Описывает действие события, принимаемое или отправляемое навыком. Значение действия события определяется его полем имени, которое имеет смысл в область навыка.

Поле Тип Обязательное поле Description
description Строка Необязательно Описание действия, которое должно инициировать событие.
имя Строка Обязательное поле Значение свойства name для действия события.
resultValue Объект Необязательно Определение схемы JSON типа объекта, возвращаемого действием.
type Строка Обязательное поле Тип действия. Ожидается значение event.
значение Объект Необязательно Определение схемы JSON для типа объекта, который это действие ожидает в качестве входных данных.

Объект invokeActivity

Описывает действие вызова, которое навык принимает. Значение действия вызова определяется его полем имени, которое имеет смысл в область навыка.

Поле Тип Обязательное поле Description
description Строка Необязательно Описание действия, который должен инициировать вызов.
имя Строка Обязательное поле Значение свойства name для действия вызова.
resultValue Объект Необязательно Определение схемы JSON для типа объекта, который связанное действие может возвращать.
type Строка Обязательное поле Тип действия. Ожидается значение invoke.
значение Объект Необязательно Определение схемы JSON для типа объекта, который это действие ожидает в качестве входных данных.

Объект messageActivity

Описывает действие сообщения, принимаемое или отправляемое навыком. Текстовое свойство действия сообщения содержит высказывание пользователя или бота.

Поле Тип Обязательное поле Description
description Строка Необязательно Описание действия.
resultValue Объект Необязательно Определение схемы JSON для типа объекта, который связанное действие может возвращать.
type Строка Обязательное поле Тип действия. Ожидается значение message.
значение Объект Необязательно Определение схемы JSON для типа объекта, который это действие ожидает в качестве входных данных.

Объект otherActivities

Описывает любой другой тип действия, принятый или отправленный навыком.

Поле Тип Обязательное поле Description
type Строка Обязательное поле Тип действия. Должен быть одним из других типов действий Bot Framework: contactRelationUpdate, conversationUpdate, deleteUserData, EndOfConversation, Handoff, InstallationUpdate, MessageDelete, MessageReaction, MessageUpdate, Suggestion, Trace или Typeing.

Объект 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"
        }
    }
},

Модели отправки

Модель отправки содержит список языковых моделей и список намерений верхнего уровня, поддерживаемых навыком. Это расширенная функция, позволяющая разработчику навыка создавать языковую модель, которая объединяет функции ботов-потребителей и навыков.

Каждая языковая модель использует .lu формат или .qna формат файла. Дополнительные сведения об этих форматах см. в формате LU-файла и формате QNA.

Имя языкового стандарта представляет собой сочетание двухбуквенного кода ISO 639 языка и региональных параметров в нижнем регистре, связанного с языком, и необязательного двухбуквенного кода ISO 3166 подкатегории языка и региональных параметров в верхнем регистре, связанного со страной или регионом, например "ru" или "ru-RU".

Поле Тип Обязательное поле Description
намерения Массив строк Необязательно Список намерений верхнего уровня, поддерживаемых навыком. Все намерения должны быть уникальными.
languages Объект, содержащий именованные массивы languageModel Необязательно Список языковых моделей, поддерживаемых навыком. Каждое имя является языковым стандартом, для которых предназначены языковые модели, а массив содержит языковые модели для этого языкового стандарта. Модель отправки должна поддерживать по крайней мере один языковой стандарт. Каждый языковой стандарт в поле languages должен быть уникальным.

Ниже приведен пример модели отправки, которая содержит две языковые модели в трех языковых стандартах. В ней также описаны два намерения высшего уровня, которые могут быть распознаны навыком.

"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

Описывает языковую модель для данного языка и региональных параметров. Именем является имя языкового стандарта.

Поле Тип или формат Обязательное поле Description
contentType Строка Обязательное поле Тип языковой модели.
description Строка Необязательно Описание языковой модели.
имя Строка Обязательное поле Имя языковой модели.
url-адрес String/URI-reference Обязательное поле URL-адрес языковой модели.

Пример манифеста

Ниже приведен полный пример манифеста версии 2.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"
                    }
                }
            }
        }
    }
}

Следующие шаги