スキル マニフェストを作成する

  • [アーティクル]

この記事の対象: SDK v4

スキル マニフェスト とは、スキルが実行できるアクション、その入出力パラメーター、およびスキルのエンドポイントが記述された JSON ファイルです。 マニフェストには、開発者が別のボットからスキルにアクセスするために使用できる機械可読形式の情報が含まれます。

この記事では、Bot Framework スキル マニフェスト スキーマのサポート対象バージョンについて説明します。

バージョン メモ
version 2.2 URI 参照を受け入れるように一部の URI プロパティを更新しました。
バージョン 2.1 スキルが送信できるプロアクティブ アクティビティと、スキルが使用するディスパッチ モデルを記述する機能を追加します。
バージョン 2.0 初期バージョン。

Bot Framework スキル マニフェスト スキーマでは、JSON スキーマ ボキャブラリの draft 7 が使用されています。

前提条件

スキル マニフェスト

スキルマニフェストには、さまざまなカテゴリの情報が含まれます。

  • 一般的なレベルのスキルを記述するメタデータ。
  • スキルが提供するエンドポイントの一覧。
  • スキルが受信してプロアクティブに送信できるアクティビティの省略可能な一覧。
  • ドキュメントの他の部分から参照されるオブジェクトのスキーマを含むオプションの定義オブジェクト。
  • スキルがサポートするディスパッチ モデルの省略可能な一覧。

次の表で、Bot Framework スキル マニフェストの v2.2 の完全なスキーマを示します。

カテゴリまたはフィールド 種類 / 形式 必須 説明
Metadata
$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 参照 省略可能 スキルについて表示するアイコンの URI。
ライセンス String 省略可能 スキルの使用許諾契約書。
name String 必須 スキルの名前。
privacyUrl 文字列 / URI 参照 省略可能 スキルのプライバシーに関する説明の URI。
publisherName String 必須 スキルの発行元の名前。
tags 文字列配列 省略可能 スキルのタグのセット。 存在する場合、各タグは一意である必要があります。
version String 必須 マニフェストに記述するスキルのバージョン。
エンドポイント
エンドポイント エンドポイント配列 必須 スキルによってサポートされるエンドポイントの一覧。 少なくとも 1 つのエンドポイントを定義する必要があります。 各エンドポイントは一意である必要があります。
活動
activities 名前付きアクティビティ オブジェクトを格納するオブジェクト 省略可能 スキルによって受け入れられる初期アクティビティのセット。
activitiesSent 名前付きアクティビティ オブジェクトを格納するオブジェクト 省略可能 スキルで送信できるプロアクティブなアクティビティについて説明します。
定義
定義 オブジェクト 省略可能 マニフェストで使用されるオブジェクトのサブスキーマを格納するオブジェクト。
ディスパッチ モデル
dispatchModels dispatchModels オブジェクト 省略可能 言語モデルと、スキルによってサポートされる最上位の意図を記述します。 このオブジェクトのスキーマについては、ディスパッチ モデルをご覧ください。

エンドポイント

各エンドポイント オブジェクトには、そのスキルでサポートされているエンドポイントを記述します。

この例では、スキルの 2 つのエンドポイントが一覧で示されます。

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

エンドポイント オブジェクト

スキルでサポートされているエンドポイントを記述します。

フィールド 種類 / 形式 必須 説明
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 Connector API バージョン 3 を表す "BotFrameworkV3" です。 スキルで別のプロトコルが特に使用されている場合を除き、既定値を使用します。

活動

各アクティビティ オブジェクトには、スキルによって受け入れられるアクティビティが記述されます。 スキルは、受け取った最初のアクティビティに基づいてアクションまたはタスクを開始します。 アクティビティ オブジェクトに関連付けられている名前は、スキルによって実行されるアクションまたはタスクを示します。

一部のアクティビティの種類には、スキルに追加の入力を提供するために使用できる値プロパティがあります。 スキルが終了する (アクションを完了する) と、関連付けられている会話終了アクティビティの値プロパティで戻り値を提供できます。

使用できるアクティビティの種類は、メッセージ、イベント、呼び出し、およびその他のアクティビティです。 スキルでは呼び出しアクティビティを受信できますが、それを送信することはできません。

これは、アクティビティの記述のサンプルです。

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

eventActivity オブジェクト

スキルによって受け入れられるか、または送信されるイベント アクティビティを記述します。 イベント アクティビティの意味は、そのスキルの範囲内で理解しやすい名前フィールドによって定義されます。

フィールド Type Required 説明
description String 省略可能 イベントによって開始する必要があるアクションの説明。
name String 必須 イベント アクティビティの name プロパティの値。
resultValue オブジェクト 省略可能 アクションで返すことができるオブジェクトの型の JSON スキーマ定義。
型 String 必須 活動の種類。 "event" である必要があります。
値 オブジェクト 省略可能 このアクションで入力として期待されるオブジェクトの型の JSON スキーマ定義。

invokeActivity オブジェクト

スキルによって受け入れられる呼び出しアクティビティを記述します。 呼び出しアクティビティの意味は、そのスキルの範囲内で理解しやすい名前フィールドによって定義されます。

フィールド Type Required 説明
description String 省略可能 呼び出しによって開始する必要があるアクションの説明。
name String 必須 呼び出しアクティビティの name プロパティの値。
resultValue オブジェクト 省略可能 関連付けられたアクションで返すことができるオブジェクトの型の JSON スキーマ定義。
型 String 必須 活動の種類。 "invoke" である必要があります。
値 オブジェクト 省略可能 このアクションで入力として期待されるオブジェクトの型の JSON スキーマ定義。

messageActivity オブジェクト

スキルによって受け入れられるか、または送信されるメッセージ アクティビティを記述します。 メッセージ アクティビティの text プロパティには、ユーザーまたはボットの発話が含まれます。

フィールド Type Required 説明
description String 省略可能 アクションの説明。
resultValue オブジェクト 省略可能 関連付けられたアクションで返すことができるオブジェクトの型の JSON スキーマ定義。
型 String 必須 活動の種類。 "message" である必要があります。
値 オブジェクト 省略可能 このアクションで入力として期待されるオブジェクトの型の JSON スキーマ定義。

otherActivities オブジェクト

スキルによって受け入れられるか、または送信されるその他のアクティビティの種類を記述します。

フィールド Type Required 説明
type String 必須 活動の種類。 次の Bot Framework のその他のアクティビティの種類のいずれかである必要があります: "contactRelationUpdate"、"conversationUpdate"、"deleteUserData"、"endOfConversation"、"handoff"、"installationUpdate", "messageDelete", "messageReaction", "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"
        }
    }
},

ディスパッチ モデル

ディスパッチ モデルには、言語モデルの一覧と、スキルによってサポートされる最上位の意図の一覧が格納されます。 これは、スキル コンシューマーの開発者がコンシューマーとスキル ボットの機能を組み合わせた言語モデルを作成できるようにする、高度な機能です。

各言語モデルでは、.lu または .qna のファイル形式が使用されます。 これらの形式の詳細については、.lu ファイル形式と .qna ファイル形式をご覧ください。

ロケール名は、言語に関連付けられた ISO 639 の 2 文字の小文字カルチャ コードと、国または地域に関連付けられた省略可能な ISO 3166 の 2 文字の大文字サブカルチャ コードを組み合わせたものです ("en" や "en-US" など)。

フィールド Type Required 説明
意図 文字列配列 省略可能 スキルによってサポートされる最上位の意図の一覧。 各意図は一意である必要があります。
languages 名前付き languageModel 配列を格納するオブジェクト 省略可能 スキルによってサポートされている言語モデルの一覧。 各名前は言語モデルのロケールであり、配列にはそのロケールの言語モデルが格納されます。 ディスパッチ モデルでは、少なくとも 1 つのロケールをサポートしている必要があります。 言語フィールド内の各ロケールは一意である必要があります。

これは、3 つのロケールにまたがる 2 つの言語モデルを格納するサンプル ディスパッチ モデルです。 また、スキルで認識できる 2 つの最上位の意図についても記述しています。

"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 参照 必須 言語モデルの 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"
                    }
                }
            }
        }
    }
}

次のステップ