기술 매니페스트 작성

  • 아티클

적용 대상: SDK v4

기술 매니페스트는 기술이 수행할 수 있는 작업, 입력 및 출력 매개 변수 및 기술의 엔드포인트를 설명하는 JSON 파일입니다. 매니페스트에는 개발자가 다른 봇의 기술에 액세스하는 데 사용할 수 있는 컴퓨터 읽기 가능한 정보가 포함되어 있습니다.

이 문서에서는 지원되는 버전의 Bot Framework 기술 매니페스트 스키마에 대해 설명합니다.

버전 주의
버전 2.2 URI 참조를 허용하도록 일부 URI 속성을 업데이트했습니다.
버전 2.1 기술이 보낼 수 있는 사전 대응 활동과 기술이 사용하는 디스패치 모델을 설명하는 기능을 추가합니다.
버전 2.0 초기 버전입니다.

Bot Framework 기술 매니페스트 스키마는 JSON 스키마 어휘 초안 7을 사용합니다.

필수 조건

기술 매니페스트

스킬 매니페스트에는 다음과 같은 다양한 범주의 정보가 포함되어 있습니다.

  • 일반 수준에서 스킬을 설명하는 메타데이터
  • 스킬에서 제공하는 엔드포인트의 목록
  • 기술이 받고 사전에 보낼 수 있는 활동의 선택적 목록입니다.
  • 문서의 다른 부분에서 참조하는 개체에 대한 스키마를 포함하는 선택적 정의 개체입니다.
  • 기술이 지원하는 디스패치 모델의 선택적 목록입니다.

다음 표에서는 Bot Framework 기술 매니페스트의 v2.2에 대한 전체 스키마를 설명합니다.

범주/필드 형식/형식 필수 설명
메타데이터
$id 문자열 Required 기술 매니페스트의 식별자입니다.
$schema 문자열/URI Required 매니페스트의 형식을 설명하는 JSON 스키마 리소스의 HTTPS URI입니다. 버전 2.2의 경우 URI는 https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json.
저작권 문자열 선택 사항 기술에 대한 저작권 고지입니다.
description 문자열 선택 사항 기술에 대한 사람이 읽을 수 있는 설명입니다.
iconUrl 문자열/URI 참조 선택 사항 기술에 대해 표시할 아이콘의 URI입니다.
license 문자열 선택 사항 기술에 대한 사용권 계약입니다.
name 문자열 Required 기술의 이름입니다.
privacyUrl 문자열/URI 참조 선택 사항 스킬에 대한 프라이버시 설명의 URI
publisherName 문자열 Required 스킬 게시자의 이름
tags 문자열 배열 선택 사항 기술에 대한 태그 집합입니다. 있는 경우 각 태그는 고유해야 합니다.
version 문자열 Required 매니페스트에서 설명하는 기술의 버전입니다.
엔드포인트
엔드포인트 엔드포인트 배열 Required 기술에서 지원하는 엔드포인트 목록입니다. 하나 이상의 엔드포인트를 정의해야 합니다. 각 엔드포인트는 고유해야 합니다.
활동
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 문자열 선택 사항 엔드포인트에 대한 설명입니다.
endpointUrl 문자열/URI Required 기술에 대한 URI 엔드포인트입니다.
msAppId 문자열 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}$과 일치해야 합니다.
name 문자열 Required 엔드포인트의 고유한 이름입니다.
프로토콜 문자열 선택 사항 지원되는 봇 프로토콜입니다. 기본값은 봇 커넥트 또는 API 버전 3을 나타내는 "BotFrameworkV3"입니다. 기술이 특별히 다른 프로토콜을 사용하지 않는 한 기본값을 사용합니다.

활동

각 활동 개체는 기술에서 허용하는 활동을 설명합니다. 기술은 받은 초기 활동에 따라 작업 또는 작업을 시작합니다. 작업 개체와 연결된 이름은 스킬에서 수행할 동작 또는 작업을 나타냅니다.

일부 활동 형식에는 기술에 추가 입력을 제공하는 데 사용할 수 있는 값 속성이 있습니다. 기술이 종료되면(작업을 완료) 연결된 대화 종료 작업의 값 속성에 반환 값을 제공할 수 있습니다.

허용되는 활동 유형은 메시지, 이벤트, 호출 및 기타 활동입니다. 기술은 호출 작업을 받을 수 있지만 보낼 수는 없습니다.

다음은 샘플 활동 설명입니다.

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

eventActivity 개체

기술에서 수락하거나 보낸 이벤트 활동을 설명합니다. 이벤트 활동의 의미는 기술 범위 내에서 의미 있는 이름 필드에 의해 정의됩니다.

필드 Type 필요함 설명
description 문자열 선택 사항 이벤트가 시작해야 하는 작업에 대한 설명입니다.
name 문자열 Required 이벤트 활동의 이름 속성 값입니다.
resultValue Object 선택 사항 작업이 반환할 수 있는 개체 형식의 JSON 스키마 정의입니다.
type 문자열 Required 작업 유형이며, "event"여야 합니다.
value Object 선택 사항 이 작업에서 입력으로 예상하는 개체 형식의 JSON 스키마 정의입니다.

invokeActivity 개체

기술에서 허용하는 호출 활동을 설명합니다. 호출 활동의 의미는 기술 범위 내에서 의미 있는 이름 필드에 의해 정의됩니다.

필드 Type 필요함 설명
description 문자열 선택 사항 호출이 시작해야 하는 작업에 대한 설명입니다.
name 문자열 Required 호출 작업의 이름 속성 값입니다.
resultValue Object 선택 사항 연결된 작업이 반환할 수 있는 개체 형식의 JSON 스키마 정의입니다.
type 문자열 Required 작업 유형이며, "invoke"여야 합니다.
value Object 선택 사항 이 작업에서 입력으로 예상하는 개체 형식의 JSON 스키마 정의입니다.

messageActivity 개체

기술에서 수락하거나 보낸 메시지 활동을 설명합니다. 메시지 활동의 텍스트 속성에는 사용자 또는 봇의 발화가 포함됩니다.

필드 Type 필요함 설명
description 문자열 선택 사항 작업에 대한 설명입니다.
resultValue Object 선택 사항 연결된 작업이 반환할 수 있는 개체 형식의 JSON 스키마 정의입니다.
type 문자열 Required 작업 유형이며, "message"여야 합니다.
value Object 선택 사항 이 작업에서 입력으로 예상하는 개체 형식의 JSON 스키마 정의입니다.

otherActivities 개체

기술에 의해 수락되거나 전송된 다른 모든 활동 유형에 대해 설명합니다.

필드 Type 필요함 설명
type 문자열 Required 작업 유형이며, 다른 Bot Framework 작업 유형 중 하나여야 합니다. "contactRelationUpdate", "conversationUpdate", "deleteUserData", "endOfConversation", "handoff", "installationUpdate", "messageDelete", "messageReaction", "messageUpdate", "suggestion", "trace" 또는 "typing".

다른Activities 개체에는 다른 속성이 포함될 수 있지만 기술 매니페스트 스키마는 해당 의미를 정의하지 않습니다.

정의

각 정의는 문서의 다른 부분에서 사용할 수 있는 하위 스키마를 설명합니다.

다음은 항공편 예약 정보에 대한 샘플 하위 스키마입니다.

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

디스패치 모델

디스패치 모델에는 언어 모델 목록과 기술에서 지원하는 최상위 의도 목록이 포함됩니다. 기술 소비자 개발자가 소비자와 기술 봇의 기능을 결합하는 언어 모델을 작성할 수 있도록 하는 고급 기능입니다.

각 언어 모델은 또는 .qna 파일 형식을 .lu 사용합니다. 이러한 형식에 대한 자세한 내용은 .lu 파일 형식 및 .qna 파일 형식을 참조하세요.

로캘 이름은 언어와 연결된 ISO 639 2자 소문자 문화권 코드와 국가 또는 지역과 연결된 선택적 ISO 3166 2자 대문자 하위 문화권 코드(예: "en" 또는 "en-US")의 조합입니다.

필드 Type 필요함 설명
의도 문자열 배열 선택 사항 기술에서 지원하는 최상위 의도 목록입니다. 각 의도는 고유해야 합니다.
언어 명명된 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 문자열 Required 언어 모델의 형식입니다.
description 문자열 선택 사항 언어 모델에 대한 설명입니다.
name 문자열 Required 언어 모델의 이름입니다.
url 문자열/URI 참조 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"
                    }
                }
            }
        }
    }
}

다음 단계