Webex 어댑터를 사용하여 Webex Teams에 봇 연결Connect a bot to Webex Teams using the Webex adapter

적용 대상: SDK v4APPLIES TO: SDK v4

이 문서에서는 SDK에서 사용할 수 있는 어댑터를 사용하여 봇을 Webex에 연결하는 방법에 대해 알아봅니다.In this article you will learn how to connect a bot to Webex using the adapter available in the SDK. 이 문서는 EchoBot 샘플을 수정하여 Webex 앱에 연결하는 과정을 안내합니다.This article will walk you through modifying the EchoBot sample to connect it to a Webex app.

참고

아래 지침에서는 Webex 어댑터의 C# 구현을 다루고 있습니다.The instructions below cover the C# implementation of the Webex adapter. BotKit 라이브러리의 일부인 JavaScript 구현을 사용하는 방법에 대한 지침은 BotKit Webex 설명서를 참조하세요.For instructions on using the JavaScript implementation, part of the BotKit libraries, see the BotKit Webex documentation.

사전 요구 사항Prerequisites

Webex 봇 앱 만들기Create a Webex bot app

  1. Webex 개발자 대시보드에 로그인한 다음, '새 앱 만들기' 단추를 클릭합니다.Log into the Webex developer dashboard and then click the 'Create a new app' button.

  2. 다음 화면에서 'Create a bot'(봇 만들기)을 클릭하여 Webex 봇을 만들도록 선택합니다.On the next screen choose to create a Webex Bot by clicking 'Create a bot'.

  3. 다음 화면에서 봇에 대한 적절한 이름, 사용자 이름 및 설명을 입력하고, 아이콘을 선택하거나 사용자 고유의 이미지를 업로드합니다.On the next screen, enter an appropriate name, username and description for your bot, as well as choosing an icon or uploading an image of your own.

    봇 설정

    'Add bot'(봇 추가) 단추를 클릭합니다.Click the 'Add bot' button.

  4. 다음 페이지에는 새 Webex 앱에 대한 액세스 토큰이 제공됩니다. 봇을 구성할 때 필요하므로 이 토큰을 적어 두세요.On the next page you will be provided with an access token for your new Webex app, please make a note of this token as you will require it when configuring your bot.

    액세스 토큰

봇에서 Webex 어댑터 연결Wiring up the Webex adapter in your bot

Webex 앱의 구성을 완료하려면 먼저 Webex 어댑터를 봇에 연결해야 합니다.Before you can complete the configuration of our Webex app, you need to wire up the Webex adapter into your bot.

Webex 어댑터 NuGet 패키지 설치Install the Webex adapter NuGet package

Microsoft.Bot.Builder.Adapters.Webex NuGet 패키지를 추가합니다.Add the Microsoft.Bot.Builder.Adapters.Webex NuGet package. NuGet을 사용하는 방법에 대한 자세한 내용은 Visual Studio에서 패키지 설치 및 관리를 참조하세요.For more information on using NuGet, see Install and manage packages in Visual Studio

Webex 어댑터 클래스 만들기Create a Webex adapter class

*Webexadapter _ 클래스에서 상속 되는 새 클래스를 만듭니다.Create a new class that inherits from the *WebexAdapter _ class. 이 클래스는 Webex 채널의 어댑터 역할을 합니다.This class will act as our adapter for the Webex channel. 여기에는 Azure Bot Service에서 요청을 처리 하는 데 사용 되는 샘플에 이미 있는 BotFrameworkAdapterWithErrorHandler 클래스와 매우 유사한 오류 처리 기능이 포함 되어 있습니다.It includes error handling capabilities (much like the BotFrameworkAdapterWithErrorHandler class already in the sample, used for handling requests from Azure Bot Service).

public class WebexAdapterWithErrorHandler : WebexAdapter
{
    public WebexAdapterWithErrorHandler(IConfiguration configuration, ILogger<WebexAdapter> logger)
        : base(configuration, null, logger)
    {
        OnTurnError = async (turnContext, exception) =>
        {
            // Log any leaked exception from the application.
            logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

            // Send a message to the user
            await turnContext.SendActivityAsync("The bot encountered an error or bug.");
            await turnContext.SendActivityAsync("To continue to run this bot, please fix the bot source code.");

            // Send a trace activity, which will be displayed in the Bot Framework Emulator
            await turnContext.TraceActivityAsync("OnTurnError Trace", exception.Message, "https://www.botframework.com/schemas/error", "TurnError");
        };
    }
}

Webex 요청을 처리하는 새 컨트롤러 만들기Create a new controller for handling Webex requests

Azure Bot Service 채널의 요청에 사용되는 기본 'api/messages' 엔드포인트 대신 새 'api/webex' 엔드포인트에서 Webex 앱의 요청을 처리하는 새 컨트롤러를 만듭니다.We create a new controller which will handle requests from your Webex app, on a new endpoint 'api/webex' instead of the default 'api/messages' used for requests from Azure Bot Service Channels. 봇에 추가 엔드포인트를 추가하면 동일한 봇을 사용하여 Bot Service 채널(또는 추가 어댑터) 및 Webex의 요청을 모두 수락할 수 있습니다.By adding an additional endpoint to your bot, you can accept requests from Bot Service channels (or additional adapters), as well as from Webex, using the same bot.

[Route("api/webex")]
[ApiController]
public class WebexController : ControllerBase
{
    private readonly WebexAdapter _adapter;
    private readonly IBot _bot;

    public WebexController(WebexAdapter adapter, IBot bot)
    {
        _adapter = adapter;
        _bot = bot;
    }

    [HttpPost]
    public async Task PostAsync()
    {
        // Delegate the processing of the HTTP POST to the adapter.
        // The adapter will invoke the bot.
        await _adapter.ProcessAsync(Request, Response, _bot, default(CancellationToken));
    }
}

봇 Startup.cs에 Webex 어댑터 삽입Inject Webex Adapter In Your Bot Startup.cs

Startup.cs 파일 내의 ConfigureServices 메서드에 다음 줄을 추가 하 여 Webex 어댑터를 등록 하 고 새 컨트롤러 클래스에 사용할 수 있도록 합니다.Add the following line into the ConfigureServices method within your Startup.cs file, which will register your Webex adapter and make it available for your new controller class. 다음 단계에서 설명하는 구성 설정은 어댑터에서 자동으로 사용됩니다.The configuration settings, described in the next step, will be automatically used by the adapter.

services.AddSingleton<WebexAdapter, WebexAdapterWithErrorHandler>();

일단 추가 되 면 ConfigureServices 메서드는 다음과 같이 표시 됩니다.Once added, your ConfigureServices method should look like this.

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    services.AddHttpClient().AddControllers().AddNewtonsoftJson();

    // Create the default Bot Framework Adapter.
    services.AddSingleton<IBotFrameworkHttpAdapter, BotFrameworkAdapterWithErrorHandler>();

    // Create the default Bot Framework Adapter.
    services.AddSingleton<WebexAdapter, WebexAdapterWithErrorHandler>();

    // Create the bot as a transient. In this case the ASP Controller is expecting an IBot.
    services.AddTransient<IBot, EchoBot>();
}

봇의 구성 파일에 Webex 어댑터 설정 추가Add Webex adapter settings to your bot's configuration file

  1. 아래에 표시된 4개의 설정을 봇 프로젝트의 appSettings.json 파일에 추가합니다.Add the 4 settings shown below to your appSettings.json file in your bot project.
{
  "WebexPublicAddress": "",
  "WebexAccessToken": "",
  "WebexSecret": "",
  "WebexWebhookName": ""
}
  1. 이전 단계에서 Webex 봇 앱을 만들 때 생성 된 Webex Bot Access Token 내의 _ WebexAccessToken* 설정을 채웁니다.Populate the _ WebexAccessToken* setting within the Webex Bot Access Token, that was generated when creating your Webex bot app in the earlier steps. 이후 단계에서 필요한 정보를 수집할 때까지 다른 세 개의 설정은 비워 둡니다.Leave the other 3 settings empty at this time, until we gather the information needed for them in later steps.

Webex 앱 및 봇의 구성 완료Complete configuration of your Webex app and bot

Webex 웹후크 만들기 및 업데이트Create and update a Webex webhook

이제 봇 프로젝트에서 Webex 앱을 만들고 어댑터를 연결했으므로 마지막 단계는 Webex 웹후크를 구성하고, 봇의 올바른 엔드포인트를 가리키며 봇에서 메시지와 첨부 파일을 받도록 앱을 구독하는 것입니다.Now that you have created a Webex app and wired up the adapter in your bot project, the final steps are to configure a Webex webhook, point it to the correct endpoint on your bot, and subscribe your app to ensure your bot receives messages and attachments. 이렇게 하려면 Webex에서 엔드포인트에 대한 URL이 유효한지 확인할 수 있도록 봇이 실행되고 있어야 합니다.To do this your bot must be running, so that Webex can verify the URL to the endpoint is valid.

  1. 이 단계를 완료하려면 봇을 Azure에 배포하고, 배포된 봇의 URL을 적어 두세요.To complete this step, deploy your bot to Azure and make a note of the URL to your deployed bot. Webex 메시징 엔드포인트는 봇에 대한 URL이며, 이는 배포된 애플리케이션(또는 ngrok 엔드포인트)과 '/api/webex'로 구성된 URL(예: https://yourbotapp.azurewebsites.net/api/webex)입니다.Your Webex messaging endpoint is the URL for your bot, which will be the URL of your deployed application (or ngrok endpoint), plus '/api/webex' (for example, https://yourbotapp.azurewebsites.net/api/webex).

    참고

    Azure에 봇을 배포할 준비가 되지 않았거나 Webex 어댑터를 사용할 때 봇을 디버그 하려는 경우 ngrok (이전에는 Bot Framework 에뮬레이터를 사용 하 여 이미 설치 했을 수 있음)와 같은 도구를 사용 하 여 로컬로 실행 되는 bot로 터널링 하 고이에 대해 공개적으로 액세스할 수 있는 URL을 제공할 수 있습니다.If you are not ready to deploy your bot to Azure, or wish to debug your bot when using the Webex adapter, you can use a tool such as ngrok (which you will likely already have installed if you have used the Bot Framework Emulator previously) to tunnel through to your bot running locally and provide you with a publicly accessible URL for this.

    ngrok 터널을 만들고 봇에 대한 URL을 가져오려면 터미널 창에서 다음 명령을 사용합니다. 이 경우 로컬 봇이 3978 포트에서 실행된다고 가정하며, 해당 봇이 이 포트에서 실행되지 않는 경우 명령에서 포트 번호를 변경하세요.If you wish create an ngrok tunnel and obtain a URL to your bot, use the following command in a terminal window (this assumes your local bot is running on port 3978, alter the port numbers in the command if your bot is not).

    ngrok.exe http 3978 -host-header="localhost:3978"
    
  2. https://developer.webex.com/docs/api/v1/webhooks으로 이동합니다.Navigate to https://developer.webex.com/docs/api/v1/webhooks.

  3. POST 메서드의 링크를 클릭 https://webexapis.com/v1/webhooks 합니다 (설명에 webhook 만들기).Click the link for the POST method https://webexapis.com/v1/webhooks (with the description Create a webhook). 그러면 끝점에 요청을 보낼 수 있는 양식이 표시 됩니다.This will display a form that allows you to send a request to the endpoint.

    webhook 끝점

  4. 다음 세부 정보로 폼을 채웁니다.Populate the form with the following details:

    1. 이름 -webhook의 이름입니다 (예: 메시지 webhook).Name - The name for your webhook, for example Messages Webhook.
    2. TargetUrl -봇의 Webex 끝점 (예:)에 대 한 전체 URL https://yourbotapp.azurewebsites.net/api/webex 입니다.TargetUrl - The full URL to your bot's Webex endpoint, such as https://yourbotapp.azurewebsites.net/api/webex).
    3. 리소스 -메시지resource - Messages.
    4. 이벤트 를 만들었습니다.event - Created.
    5. 필터 -비워 둡니다.filter - Leave it blank.
    6. 비밀 -웹 후크를 보호 하기 위해 선택한 암호입니다.secret - A secret of your choice to secure your webhook. 나중에 봇의에 추가 appsettings.json 합니다.Later you will add it to your bot's appsettings.json.

    webhook 폼

  5. Run(실행) 을 클릭합니다. 그러면 웹후크가 만들어지고 성공 메시지가 표시됩니다.Click Run, which should create your webhook and provide you with a success message.

봇 애플리케이션의 나머지 설정 완료Complete the remaining settings in your bot application

봇의 appsettings.json 파일에서 나머지 3개 설정을 완료합니다(WebexAccessToken 은 이전 단계에서 이미 채웠음).Complete the remaining 3 settings in your bot's appsettings.json file (you already populated WebexAccessToken in an earlier step).

  • WebexPublicAddress(봇의 Webex 엔드포인트에 대한 전체 URL)WebexPublicAddress (the full URL to your bot's Webex endpoint)
  • WebexSecret(이전 단계에서 웹후크를 만들 때 제공한 비밀)WebexSecret (the secret you provided when creating your webhook in the previous step)
  • WebexWebhookName(이전 단계에서 제공한 웹후크 이름)WebexWebhookName (the name for your webhook you provided in the previous step)

Webex 팀에서 봇 다시 배포Re-deploy your bot in your Webex team

이제 appsettings.json에서 봇의 설정 구성을 완료했으므로 봇을 다시 배포하거나, ngrok를 사용하여 로컬 엔드포인트로 터널링하는 경우 봇을 다시 시작해야 합니다.Now that you have completed the configuration of your bot's settings in appsettings.json, you should re-deploy your bot (or restart your bot if you are tunnelling to a local endpoint using ngrok). 이제 Webex 앱과 봇의 구성이 완료되었습니다.Configuration of you Webex app and bot are now complete. 이제 https://www.webex.com에서 Webex 팀에 로그인하여 다른 사람에게 연락하는 것과 동일한 방식으로 메시지를 보내 봇과 채팅할 수 있습니다.You can now login to your Webex team at https://www.webex.com and chat with your bot by sending it a message, in the same way you would contact another person.

담당자