V2.0 のスキル マニフェストを作成する方法How to write a v2.0 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. マニフェストには、開発者が別のボットからスキルにアクセスするために必要な情報が含まれています。The manifest contains the information a developer needs to access the skill from another bot.

この記事では、Bot Framework スキル マニフェスト スキーマのバージョン 2.0.0 について説明します。This article describes version 2.0.0 of the Bot Framework skill manifest schema. バージョン2.1 の説明については、「version 2.1 のスキルマニフェストを記述する方法」を参照してください。For a description of version 2.1, see how to Write a v2.1 skill manifest.

Bot Framework スキル マニフェスト スキーマには、JSON スキーマ ボキャブラリのドラフト 7 が使用されています。The Bot Framework skill manifest schema uses draft 7 of the JSON schema vocabulary.

前提条件Prerequisites

スキル マニフェスト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.
  • スキルで受け取ることができるアクティビティのオプションの一覧。An optional list of the activities the the skill can receive.
  • ドキュメントの他の部分から参照されるオブジェクトのスキーマを含むオプションの定義オブジェクト。An optional definitions object that contains schemas for objects referenced by other parts of the document.

Bot Framework スキル マニフェストの v2.0 の完全なスキーマを次に示します。The following is the full schema for v2.0 of the Bot Framework skill manifest.

カテゴリまたはフィールドCategory/Field TypeType 必須Required 説明Description
MetadataMetadata
$id$id stringstring 必須Required スキル マニフェストの識別子。The identifier for the skill manifest.
$schema$schema stringstring 必須Required マニフェストの形式を記述する JSON スキーマ リソースの HTTPS URI。The HTTPS URI of a a JSON schema resource that describes the format of the manifest. バージョン 2.0.0 の場合、URI は https://schemas.botframework.com/schemas/skills/v2.0/skill-manifest.json です。For version 2.0.0, the URI is https://schemas.botframework.com/schemas/skills/v2.0/skill-manifest.json.
copyrightcopyright stringstring 省略可能Optional スキルの著作権に関する通知。The copyright notice for the skill.
descriptiondescription stringstring 省略可能Optional 人が判読できるスキルの説明。A human-readable description of the skill.
iconUrliconUrl stringstring 省略可能Optional スキルに関して表示するアイコンの URI。The URI of the icon to show for the skill.
licenselicense stringstring 省略可能Optional スキルの使用許諾契約書。The license agreement for the skill.
namename stringstring 必須Required スキルの名前。The name of the skill.
versionversion stringstring 必須Required マニフェストに記述するスキルのバージョン。The version of the skill the manifest describes.
privacyUrlprivacyUrl stringstring 省略可能Optional スキルのプライバシーに関する説明の URI。The URI of the privacy description for the skill.
publisherNamepublisherName stringstring 必須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 配列endpoint array 必須Required スキルによってサポートされるエンドポイントの一覧。The list of endpoints supported by the skill. 少なくとも 1 つのエンドポイントを定義する必要があります。At least one endpoint must be defined. 各エンドポイントは一意である必要があります。Each endpoint must be unique.
アクティビティActivities
activitiesactivities 名前付きアクティビティ オブジェクトを格納するオブジェクトobject containing named activity objects 必須Required スキルによって受け入れられる初期アクティビティのセット。The set of initial activities accepted by the skill.
定義Definitions
definitionsdefinitions objectobject 省略可能Optional マニフェストで使用されるオブジェクトのサブスキーマを格納するオブジェクト。An object containing subschemas for objects used in the manifest.

エンドポイントEndpoints

各エンドポイント オブジェクトには、そのスキルでサポートされているエンドポイントが記述されます。Each endpoint object describes an endpoint supported by the skill.

この例では、スキルの 2 つのエンドポイントが一覧で示されます。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

フィールドField TypeType 必須Required 説明Description
descriptiondescription stringstring 省略可能Optional エンドポイントの説明。A description for the endpoint.
endpointUrlendpointUrl stringstring 必須Required スキルの URI エンドポイント。The URI endpoint for the skill.
msAppIdmsAppId stringstring 必須Required 要求を認証するために使用される、スキルの Microsoft AppId (GUID)。The Microsoft AppId (GUID) for the skill, used to authenticate requests.
namename stringstring 必須Required エンドポイントの一意名。The unique name for the endpoint.
protocolprotocol stringstring 省略可能Optional サポートされるプロトコル。The supported protocol. 既定値は "BotFrameworkV3" です。Default is "BotFrameworkV3".

ActivitiesActivities

各アクティビティ オブジェクトには、スキルによって受け入れられるアクティビティが記述されます。Each activity object describes an activity accepted by the skill. スキルでは、受け取った最初のアクティビティに基づいてアクションまたはタスクが開始されます。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.

一部のアクティビティの種類には、スキルに追加の入力を提供するために使用できる value 値プロパティがあります。Some activity types have a value property that can be used to provide additional input to the skill. スキルが終了すると (アクションを完了すると)、関連する会話終了アクティビティの value プロパティに戻り値を提供できます。When the skill ends (completes the action) it can provide a return value in the associated end-of-conversation activity's value property.

v2.0.0 スキル マニフェスト スキーマで許可されるアクティビティの種類は、メッセージ、イベント、および呼び出しアクティビティです。The activity types allowed in the v2.0.0 skill manifest schema are: message, event, and invoke activities.

これは、アクティビティの記述のサンプルです。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 by the skill.

フィールドField TypeType 必須Required 説明Description
descriptiondescription stringstring 省略可能Optional アクションの説明。A description of the action.
namename stringstring 必須Required イベント アクティビティの name プロパティの値。The value of the event activity's name property.
resultValueresultValue objectobject 省略可能Optional 関連付けられたアクションから返すことができるオブジェクトの型の JSON スキーマ定義。A JSON schema definition of the type of object that the associated action can return.
typetype stringstring 必須Required アクティビティの種類。The activity type. "event" である必要があります。Must be "event".
valuevalue objectobject 省略可能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 TypeType 必須Required 説明Description
descriptiondescription stringstring 省略可能Optional アクションの説明。A description of the action.
namename stringstring 必須Required 呼び出しアクティビティの name プロパティの値。The value of the invoke activity's name property.
resultValueresultValue objectobject 省略可能Optional 関連付けられたアクションから返すことができるオブジェクトの型の JSON スキーマ定義。A JSON schema definition of the type of object that the associated action can return.
typetype stringstring 必須Required アクティビティの種類。The activity type. "invoke" である必要があります。Must be "invoke".
valuevalue objectobject 省略可能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 by the skill. メッセージ アクティビティの text プロパティには、ユーザーの発話が含まれています。The message activity's text property contains the user's utterance.

フィールドField TypeType 必須Required 説明Description
descriptiondescription stringstring 省略可能Optional アクションの説明。A description of the action.
resultValueresultValue objectobject 省略可能Optional 関連付けられたアクションから返すことができるオブジェクトの型の JSON スキーマ定義。A JSON schema definition of the type of object that the associated action can return.
typetype stringstring 必須Required アクティビティの種類。The activity type. "message" である必要があります。Must be "message".
valuevalue objectobject 省略可能Optional このアクションで入力として想定するオブジェクトの型の JSON スキーマ定義。A JSON schema definition of the type of object that this action expects as input.

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

サンプル マニフェストSample manifest

これは、複数のアクティビティを公開するスキルの完全なサンプル v2.0 マニフェストです。This is a full sample v2.0 manifest for a skill that exposes multiple activities.

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