スキル マニフェストを記述する

適用対象: SDK v4

スキル マニフェストは、スキルが実行できるアクション、入力パラメーターと出力パラメーター、およびスキルのエンドポイントを記述する JSON ファイルです。 マニフェストには、開発者が別のボットからスキルにアクセスするために使用できる、コンピューターが読み取り可能な情報が含まれています。

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

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

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

前提条件

スキル マニフェスト

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

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

次の表では、Bot Framework スキル マニフェストの v2.2 の完全なスキーマについて説明します。

カテゴリ/フィールド 型/書式 Required Description
Metadata
$id String Required スキル マニフェストの識別子。
$schema 文字列/URI Required マニフェストの形式を記述する JSON スキーマ リソースの HTTPS URI。 バージョン 2.2 の場合、URI は https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json。
著作権 String Optional スキルの著作権に関する通知。
description String Optional 人間が読みやすいスキルの説明。
iconUrl String/URI-reference Optional スキルに表示するアイコンの URI。
ライセンス String Optional スキルの使用許諾契約書。
名前 String Required スキルの名前だ。
privacyUrl String/URI-reference Optional スキルのプライバシーの説明の URI。
publisherName String Required スキル発行元の名前。
tags 文字列配列 Optional スキルのタグのセット。 存在する場合、各タグは一意である必要があります。
バージョン String Required マニフェストが記述するスキルのバージョン。
エンドポイント
endpoints endpoint 配列 Required スキルでサポートされているエンドポイントの一覧。 少なくとも 1 つのエンドポイントを定義する必要があります。 各エンドポイントは一意である必要があります。
アクティビティ
activities 名前付きアクティビティ オブジェクトを含むオブジェクト Optional スキルによって受け入れられる初期アクティビティのセット。
activitiesSent 名前付きアクティビティ オブジェクトを含むオブジェクト Optional スキルが送信できるプロアクティブ アクティビティについて説明します。
定義
定義 Object Optional マニフェストで使用されるオブジェクトのサブスケマを含むオブジェクト。
モデルのディスパッチ
dispatchModels dispatchModels オブジェクト Optional スキルでサポートされている言語モデルと最上位の意図について説明します。 このオブジェクトのスキーマについては、「 モデルのディスパッチ 」を参照してください。

Endpoints

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

この例では、スキルの 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"
    }
],

endpoint オブジェクト

スキルでサポートされるエンドポイントについて説明します。

フィールド 型/書式 Required Description
description String Optional エンドポイントの説明。
endpointUrl 文字列/URI Required スキルの URI エンドポイント。
msAppId String Required 要求の認証に使用されるスキルの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}$。
名前 String Required エンドポイントの一意の名前。
プロトコル String Optional サポートされているボット プロトコル。 既定値は 、Bot Connector API バージョン 3 を表す "BotFrameworkV3" です。 スキルで別のプロトコルが特に使用されている場合を除き、既定値を使用します。

アクティビティ

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

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

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

アクティビティの説明の例を次に示します。

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

eventActivity オブジェクト

スキルによって受け入れまたは送信されたイベント アクティビティについて説明します。 イベント アクティビティの意味は、スキルのスコープ内で意味のある名前フィールドによって定義されます。

フィールド タイプ Required Description
description String Optional イベントが開始する必要があるアクションの説明。
名前 String Required イベント アクティビティの name プロパティの値。
resultValue Object Optional アクションが返すことができるオブジェクトの型の JSON スキーマ定義。
型 String Required アクティビティの種類。 "event" にする必要があります。
価値 Object Optional このアクションが入力として必要とするオブジェクトの型の JSON スキーマ定義。

invokeActivity オブジェクト

スキルによって受け入れられる呼び出しアクティビティについて説明します。 呼び出しアクティビティの意味は、スキルのスコープ内で意味のある名前フィールドによって定義されます。

フィールド タイプ Required Description
description String Optional 呼び出しが開始する必要があるアクションの説明。
名前 String Required 呼び出しアクティビティの name プロパティの値。
resultValue Object Optional 関連付けられたアクションが返すことができるオブジェクトの型の JSON スキーマ定義。
型 String Required アクティビティの種類。 "invoke" である必要があります。
価値 Object Optional このアクションが入力として必要とするオブジェクトの型の JSON スキーマ定義。

messageActivity オブジェクト

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

フィールド タイプ Required Description
description String Optional アクションの説明。
resultValue Object Optional 関連付けられたアクションが返すことができるオブジェクトの型の JSON スキーマ定義。
型 String Required アクティビティの種類。 "message" にする必要があります。
価値 Object Optional このアクションが入力として必要とするオブジェクトの型の JSON スキーマ定義。

otherActivities オブジェクト

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

フィールド タイプ Required Description
型 String Required アクティビティの種類。 他の Bot Framework アクティビティの種類 ("contactRelationUpdate"、"conversationUpdate"、"deleteUserData"、"endOfConversation"、"handoff"、"installationUpdate"、"messageDelete"、"messageReaction"、"messageUpdate"、"suggestion"、"trace"、または "typing" のいずれかである必要があります。

otherActivities オブジェクトには他のプロパティを含めることができますが、スキル マニフェスト スキーマではその意味は定義されません。

Definitions

各定義は、ドキュメントの他の部分で使用できるサブスキーマを記述します。

フライト予約情報のサンプル サブスキーマを次に示します。

"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形式の詳細については、ファイル形式を参照してください。

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

フィールド タイプ Required Description
意図 文字列配列 Optional スキルでサポートされている最上位の意図の一覧。 各意図は一意である必要があります。
言語 名前付き languageModel 配列を含むオブジェクト Optional スキルでサポートされている言語モデルの一覧。 各名前は言語モデルのロケールであり、配列にはそのロケールの言語モデルが含まれています。 ディスパッチ モデルでは、少なくとも 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 オブジェクト

特定のカルチャの言語モデルについて説明します。 名前はロケール名です。

フィールド 型/書式 Required Description
contentType String Required 言語モデルの種類。
description String Optional 言語モデルの説明。
名前 String Required 言語モデルの名前。
URL String/URI-reference Required 言語モデルの 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"
                    }
                }
            }
        }
    }
}

次のステップ

  • Last updated on