기술 구현Implement a skill

적용 대상: SDK v4APPLIES TO: SDK v4

기술을 사용하여 다른 봇을 확장할 수 있습니다.You can use skills to extend another bot. 기술 은 다른 봇에 대한 작업 세트를 수행할 수 있는 봇입니다.A skill is a bot that can perform a set of tasks for another bot.

  • 기술의 인터페이스는 매니페스트에서 설명합니다.A skill's interface is described by a manifest. 기술의 소스 코드에 액세스할 수 없는 개발자는 매니페스트의 정보를 사용하여 기술 소비자를 설계할 수 있습니다.Developers who don't have access to the skill's source code can use the information in the manifest to design their skill consumer.
  • 기술 소비자는 클레임 유효성 검사를 사용하여 액세스할 수 있는 봇 또는 사용자를 관리할 수 있습니다.A skill can use claims validation to manage which bots or users can access it.

이 문서에서는 사용자의 입력을 에코하는 기술을 구현하는 방법을 보여 줍니다.This article demonstrates how to implement a skill that echoes the user's input.

필수 구성 요소Prerequisites

참고

버전 4.11부터 에뮬레이터에서 로컬로 기술을 테스트하기 위해 앱 ID와 암호가 필요하지 않습니다.Starting with version 4.11, you do not need an app ID and password to test a skill locally in the Emulator. Azure 구독은 여전히 Azure에 기술을 배포하는 데 필요합니다.An Azure subscription is still required to deploy your skill to Azure.

이 샘플 정보About this sample

skills simple bot-to-bot 샘플에는 두 개의 봇에 대한 프로젝트가 포함되어 있습니다.The skills simple bot-to-bot sample includes projects for two bots:

  • 에코 기술 봇 - 기술을 구현합니다.The echo skill bot, which implements the skill.
  • 단순 루트 봇 - 기술을 사용하는 루트 봇을 구현합니다.The simple root bot, which implements a root bot that consumes the skill.

이 문서에서는 봇 및 어댑터의 지원 논리를 포함하는 기술에 중점을 둡니다.This article focuses on the skill, which includes support logic in its bot and adapter.

단순 루트 봇에 대한 자세한 내용은 기술 소비자 구현 방법을 참조하세요.For information about the simple root bot, see how to Implement a skill consumer.

리소스Resources

배포된 봇의 경우 봇-봇 인증을 사용하려면 참여하는 각 봇에 유효한 앱 ID와 암호가 있어야 합니다.For deployed bots, bot-to-bot authentication requires that each participating bot has a valid app ID and password. 그러나 앱 ID 및 암호 없이 에뮬레이터를 통해 기술 및 기술 소비자를 로컬로 테스트할 수 있습니다.However, you can test skills and skill consumers locally with the Emulator without an app ID and password.

사용자용 봇에서 기술을 사용할 수 있도록 하려면 Azure에 기술을 등록합니다.To make the skill available to user-facing bots, register the skill with Azure. 봇 채널 등록을 사용할 수 있습니다.You can use a Bot Channels Registration. 자세한 내용은 Azure Bot Service에 봇을 등록하는 방법을 참조하세요.For more information, see how to register a bot with Azure Bot Service.

애플리케이션 구성Application configuration

필요에 따라 기술의 앱 ID 및 암호를 기술의 구성 파일에 추가합니다.Optionally, add the skill's app ID and password to the skill's configuration file. (기술 또는 기술 소비자 중 하나가 앱 ID와 암호를 사용하는 경우 둘 다 여야 합니다.)(If either the skill or skill consumer uses an app ID and password, both must.)

허용되는 호출자 배열은 기술에 액세스할 수 있는 기술 소비자를 제한할 수 있습니다.The allowed callers array can restrict which skill consumers can access the skill. 기술 소비자의 호출을 수락하려면 "*" 요소를 추가합니다.Add an "*" element, to accept calls from any skill consumer.

참고

앱 ID 및 암호 없이 로컬로 기술을 테스트하는 경우 기술이나 기술 소비자는 코드를 실행하여 클레임 유효성 검사를 수행하지 않습니다.If you are testing your skill locally without an app ID and password, neither the skill nor the skill consumer run the code to perform claims validation.

EchoSkillBot\appsettings.jsonEchoSkillBot\appsettings.json

기술의 앱 ID와 암호를 appsettings.json 파일에 추가합니다.Add the skill's app ID and password to the appsettings.json file.

{
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",

  // This is a comma separate list with the App IDs that will have access to the skill.
  // This setting is used in AllowedCallersClaimsValidator.
  // Examples: 
  //    [ "*" ] allows all callers.
  //    [ "AppId1", "AppId2" ] only allows access to parent bots with "AppId1" and "AppId2".
  "AllowedCallers": [ "*" ]
}

활동 처리기 논리Activity handler logic

입력 매개 변수를 허용하려면To accept input parameters

기술 소비자는 정보를 기술에 보낼 수 있습니다.The skill consumer can send information to the skill. 이러한 정보를 수락하는 한 가지 방법은 들어오는 메시지의 value 속성을 통해 해당 정보를 수락하는 것입니다.One way to accept such information is to accept them via the value property on incoming messages. 또 다른 방법은 이벤트를 처리하고 활동을 호출하는 것입니다.Another way is to handle event and invoke activities.

이 예제의 기술은 입력 매개 변수를 허용하지 않습니다.The skill in this example doesn't accept input parameters.

대화를 계속하거나 완료하려면To continue or complete a conversation

기술에서 활동을 보내면 기술 소비자에서 사용자에게 해당 활동을 전달해야 합니다.When the skill sends an activity, the skill consumer should forward the activity on to the user.

그러나 기술이 완료되면 endOfConversation 활동을 보내야 합니다. 그렇지 않으면 기술 소비자에서 사용자 활동을 기술에 계속 전달합니다.However, you need to send an endOfConversation activity when the skill finishes; otherwise, the skill consumer will continue to forward user activities to the skill. 필요한 경우 활동의 value 속성을 사용하여 반환 값을 포함시키고, 활동의 code 속성을 사용하여 기술이 종료되는 이유를 표시합니다.Optionally, use the activity's value property to include a return value, and use the activity's code property to indicate why the skill is ending.

EchoSkillBot\Bots\EchoBot.csEchoSkillBot\Bots\EchoBot.cs

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    if (turnContext.Activity.Text.Contains("end") || turnContext.Activity.Text.Contains("stop"))
    {
        // Send End of conversation at the end.
        var messageText = $"ending conversation from the skill...";
        await turnContext.SendActivityAsync(MessageFactory.Text(messageText, messageText, InputHints.IgnoringInput), cancellationToken);
        var endOfConversation = Activity.CreateEndOfConversationActivity();
        endOfConversation.Code = EndOfConversationCodes.CompletedSuccessfully;
        await turnContext.SendActivityAsync(endOfConversation, cancellationToken);
    }
    else
    {
        var messageText = $"Echo: {turnContext.Activity.Text}";
        await turnContext.SendActivityAsync(MessageFactory.Text(messageText, messageText, InputHints.IgnoringInput), cancellationToken);
        messageText = "Say \"end\" or \"stop\" and I'll end the conversation and back to the parent.";
        await turnContext.SendActivityAsync(MessageFactory.Text(messageText, messageText, InputHints.ExpectingInput), cancellationToken);
    }
}

기술을 취소하려면To cancel the skill

다중 턴 기술의 경우 기술 소비자로부터 받은 endOfConversation 활동을 수락하여 소비자가 현재 대화를 취소할 수도 있습니다.For multi-turn skills, you would also accept endOfConversation activities from a skill consumer, to allow the consumer to cancel the current conversation.

이 기술에 대한 논리는 차례로 변경되지 않습니다.The logic for this skill doesn't change from turn to turn. 대화 리소스를 할당하는 기술을 구현하는 경우 리소스 정리 코드를 대화 끝 처리기에 추가합니다.If you implement a skill that allocates conversation resources, add resource cleanup code to the end-of-conversation handler.

EchoSkillBot\Bots\EchoBot.csEchoSkillBot\Bots\EchoBot.cs

protected override Task OnEndOfConversationActivityAsync(ITurnContext<IEndOfConversationActivity> turnContext, CancellationToken cancellationToken)
{
    // This will be called if the root bot is ending the conversation.  Sending additional messages should be
    // avoided as the conversation may have been deleted.
    // Perform cleanup of resources if needed.
    return Task.CompletedTask;
}

클레임 유효성 검사기Claims validator

이 샘플에서는 클레임 유효성 검사에 허용되는 호출자 목록을 사용합니다.This sample uses an allowed callers list for claims validation. 이 목록은 기술의 구성 파일에 정의되어 있으며, 만들어질 때 유효성 검사기 개체로 읽어들입니다.The list is defined in the skill's configuration file and is read into the validator object when it's created.

인증 구성에 클레임 유효성 검사기를 추가해야 합니다.You must add a claims validator to the authentication configuration. 클레임은 인증 헤더 다음에 평가됩니다.The claims are evaluated after the authentication header. 유효성 검사 코드는 요청을 거부하는 오류 또는 예외를 throw해야 합니다.Your validation code should throw an error or exception to reject the request. 다른 방법으로 인증된 요청을 거부하려는 여러 가지 이유가 있습니다.There are many reasons you may want to reject an otherwise authenticated request. 예를 들면 다음과 같습니다.For example:

  • 기술이 유료 서비스의 일부입니다.The skill is part of a paid-for service. 데이터베이스에 사용자가 없는 경우 액세스 권한이 없어야 합니다.User's not in the database shouldn't have access.
  • 기술에 대한 독점적인 소유권이 있습니다.The skill is proprietary. 특정 기술 소비자만 기술을 호출할 수 있습니다.Only certain skill consumers can call the skill.

중요

클레임 유효성 검사기를 제공하지 않으면 봇은 기술 소비자로부터 활동을 수신할 때 오류 또는 예외를 생성합니다.If you don't provide a claims validator, your bot will generate an error or exception upon receiving an activity from the skill consumer.

SDK는 AllowedCallersClaimsValidator 기술을 호출할 수 있는 애플리케이션의 간단한 ID 목록을 기반으로 애플리케이션 수준 권한 부여를 추가하는 클래스를 제공합니다.The SDK provides an AllowedCallersClaimsValidator class that adds application-level authorization based on a simple list of IDs of the applications that are allowed to call the skill. 목록에 별표(*)가 포함되어 있으면 모든 호출자가 허용됩니다.If the list contains an asterisk (*), then all callers are allowed. 클레임 유효성 검사기는 Startup.cs 에서 구성됩니다.The claims validator is configured in Startup.cs.

기술 어댑터Skill adapter

오류가 발생하면 기술 어댑터에서 기술에 대한 대화 상태를 지우고 endOfConversation 활동을 기술 소비자에 보내야 합니다.When an error occurs, the skill's adapter should clear conversation state for the skill, and it should also send an endOfConversation activity to the skill consumer. 활동의 code 속성을 사용하여 오류로 인해 기술이 종료되었다는 신호를 보냅니다.Use the code property of the activity to signal that the skill ended due to an error.

EchoSkillBot\SkillAdapterWithErrorHandler.csEchoSkillBot\SkillAdapterWithErrorHandler.cs

public SkillAdapterWithErrorHandler(IConfiguration configuration, ICredentialProvider credentialProvider, AuthenticationConfiguration authConfig, ILogger<BotFrameworkHttpAdapter> logger)
    : base(configuration, credentialProvider, authConfig, logger: logger)
{
    _logger = logger ?? throw new ArgumentNullException(nameof(logger));
    OnTurnError = HandleTurnError;
}

private async Task HandleTurnError(ITurnContext turnContext, Exception exception)
{
    // Log any leaked exception from the application.
    _logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

    await SendErrorMessageAsync(turnContext, exception);
    await SendEoCToParentAsync(turnContext, exception);
}

private async Task SendErrorMessageAsync(ITurnContext turnContext, Exception exception)
{
    try
    {
        // Send a message to the user.
        var errorMessageText = "The skill encountered an error or bug.";
        var errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.IgnoringInput);
        await turnContext.SendActivityAsync(errorMessage);

        errorMessageText = "To continue to run this bot, please fix the bot source code.";
        errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.ExpectingInput);
        await turnContext.SendActivityAsync(errorMessage);

        // Send a trace activity, which will be displayed in the Bot Framework Emulator.
        // Note: we return the entire exception in the value property to help the developer;
        // this should not be done in production.
        await turnContext.TraceActivityAsync("OnTurnError Trace", exception.ToString(), "https://www.botframework.com/schemas/error", "TurnError");
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, $"Exception caught in SendErrorMessageAsync : {ex}");
    }
}

private async Task SendEoCToParentAsync(ITurnContext turnContext, Exception exception)
{
    try
    {
        // Send an EndOfConversation activity to the skill caller with the error to end the conversation,
        // and let the caller decide what to do.
        var endOfConversation = Activity.CreateEndOfConversationActivity();
        endOfConversation.Code = "SkillError";
        endOfConversation.Text = exception.Message;
        await turnContext.SendActivityAsync(endOfConversation);
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, $"Exception caught in SendEoCToParentAsync : {ex}");
    }
}

서비스 등록Service registration

Bot Framework 어댑터인증 구성 개체(어댑터를 만들 때 설정됨)를 사용하여 들어오는 요청에서 유효성을 검사합니다.The Bot Framework adapter uses an authentication configuration object (set when the adapter is created) to validate the authentication header on incoming requests.

이 샘플에서는 클레임 유효성 검사를 인증 구성에 추가하고, 이전 섹션에서 설명한 오류 처리기가 있는 기술 어댑터 를 사용합니다.This sample adds claims validation to the authentication configuration and uses the skill adapter with error handler described in the previous section.

EchoSkillBot\Startup.csEchoSkillBot\Startup.cs

// Register AuthConfiguration to enable custom claim validation.
services.AddSingleton(sp => new AuthenticationConfiguration
{
    ClaimsValidator = new AllowedCallersClaimsValidator(new List<string>(sp.GetService<IConfiguration>().GetSection("AllowedCallers").Get<string[]>()))
});

// Create the Bot Framework Adapter with error handling enabled.
services.AddSingleton<IBotFrameworkHttpAdapter, SkillAdapterWithErrorHandler>();

기술 매니페스트Skill manifest

기술 매니페스트 는 기술에서 수행할 수 있는 활동, 해당 입/출력 매개 변수 및 기술의 엔드포인트를 설명하는 JSON 파일입니다.A skill manifest is a JSON file that describes the activities the skill can perform, its input and output parameters, and the skill's endpoints. 매니페스트에는 다른 봇의 기술에 액세스하는 데 필요한 정보가 포함되어 있습니다.The manifest contains the information you need to access the skill from another bot. 최신 스키마 버전은 v 2.1입니다.The latest schema version is v2.1.

EchoSkillBot\wwwroot\manifest\echoskillbot-manifest-1.0.jsonEchoSkillBot\wwwroot\manifest\echoskillbot-manifest-1.0.json

{
  "$schema": "https://schemas.botframework.com/schemas/skills/skill-manifest-2.0.0.json",
  "$id": "EchoSkillBot",
  "name": "Echo Skill bot",
  "version": "1.0",
  "description": "This is a sample echo skill",
  "publisherName": "Microsoft",
  "privacyUrl": "https://echoskillbot.contoso.com/privacy.html",
  "copyright": "Copyright (c) Microsoft Corporation. All rights reserved.",
  "license": "",
  "iconUrl": "https://echoskillbot.contoso.com/icon.png",
  "tags": [
    "sample",
    "echo"
  ],
  "endpoints": [
    {
      "name": "default",
      "protocol": "BotFrameworkV3",
      "description": "Default endpoint for the skill",
      "endpointUrl": "http://echoskillbot.contoso.com/api/messages",
      "msAppId": "00000000-0000-0000-0000-000000000000"
    }
  ]
}

기술 매니페스트 스키마 는 기술 매니페스트의 스키마를 설명하는 JSON 파일입니다.The skill manifest schema is a JSON file that describes the schema of the skill manifest. 현재 스키마 버전은 2.1.0입니다.The current schema version is 2.1.0.

기술 테스트Test the skill

이제 Emulator에서 기술을 표준 봇처럼 테스트할 수 있습니다.At this point, you can test the skill in the Emulator as if it were a normal bot. 그러나 기술로 테스트하려면 기술 소비자를 구현해야 합니다.However, to test it as a skill, you would need to implement a skill consumer.

최신 Bot Framework Emulator를 다운로드하고 설치합니다.Download and install the latest Bot Framework Emulator

  1. 머신에서 에코 기술 봇을 로컬로 실행합니다.Run the echo skill bot locally on your machine. 지침이 필요한 경우 C#, JavaScript 또는 Python 샘플에 대한 추가 정보 파일을 참조하세요.If you need instructions, refer to the README file for the C#, JavaScript, or Python sample.
  2. Emulator를 사용하여 아래와 같이 봇을 테스트합니다.Use the Emulator to test the bot as shown below. "End" 또는 "stop" 메시지를 기술에 보내면 endOfConversation 회신 메시지 외에도 작업이 전송 됩니다.When you send an "end" or "stop" message to the skill, it sends an endOfConversation activity in addition to the reply message. 기술에서 기술이 완료되었음을 나타내는 endOfConversation 활동을 보냅니다.The skill sends the endOfConversation activity to indicate the skill has finished.

에코 기술 테스트

다음 단계Next steps