Azure Bot Service 채널에 Power Virtual Agents 봇 추가

[This topic is pre-release documentation and is subject to change.]

봇을 기존Azure Bot Service 채널에 연결할 수 있습니다. 이는 봇을 Azure Bot Service 채널의 최종 사용자에게 연결하려는 경우 유용합니다.

봇을 Azure Bot Service 채널에 추가하려면 상당한 개발자 전문 지식이 필요합니다. 이 항목은 코드 개발 및 작성 경험이 있는 IT 관리자 또는 개발자를 위해 작성되었습니다.

Power Virtual Agents 봇을 웹 사이트, Facebook 또는 Microsoft Teams에 추가하기 위해 이 문서를 따를 필요가 없습니다. 사용자 지정 웹 기반 또는 기본 앱에 연결하는 것이 목표인 경우 개발자는 모바일 및 사용자 지정 앱에 봇 추가에서 자세한 내용을 알아볼 수 있습니다.

중요

이 섹션의 지침에는 사용자 또는 개발자의 소프트웨어 개발이 필요합니다. 개발자 도구, 유틸리티 및 IDE에 대해 잘 알고 있는 IT 관리자나 개발자와 같은 숙련된 IT 전문가를 대상으로 합니다.

필수 구성 요소

이 항목의 지침을 따르기 전에 또한 모바일 및 사용자 지정 앱에 봇 연결을 읽어야 합니다.

샘플 코드

이 문서에 사용된 코드 조각은 릴레이 봇 샘플 코드의 것입니다.

참조

이 문서의 지침은 다음을 참조합니다.

기존 Azure Bot Service 봇 만들기 또는 사용

Power Virtual Agents 봇과 Azure Bot Service 채널 사이에 대화를 전달할 수 있는 Azure Bot Service 봇이 필요합니다.

릴레이 봇 다이어그램

릴레이 봇 샘플 코드는 기존 Azure Bot Service 봇이 없는 경우 좋은 출발점입니다. 그것은 Microsoft Bot Framework 봇 샘플 코드에서 빌드되며 컴파일하여 Azure Bot Service에 배포할 수 있습니다. 샘플 코드는 시작점으로 사용하기 위한 것이며 프로덕션 환경에서 직접 사용할 수 없습니다. 비즈니스 요구에 맞게 코드와 최적화를 추가해야 합니다.

Azure Bot Service 봇이 이미 있는 경우 대화 세션을 관리하기 위해 Power Virtual Agents 커넥터 및 코드를 추가해야 합니다. 그런 다음 봇을 Azure Bot Service에 배포하고 Azure Portal을 사용하여 채널에 연결할 수 있습니다.

Power Virtual Agents 봇 매개 변수 가져오기

Power Virtual Agents로 빌드한 봇에 연결하려면 봇 이름, 봇 ID 및 테넌트 ID를 검색하여 식별해야 합니다.

  1. Power Virtual Agents에서 봇 이름을 복사합니다.

    봇 이름 얻기

  2. 측면 탐색 창에서 관리를 선택하고 채널로 이동합니다.

  3. 연결하려는 채널을 선택하십시오. 이 항목은 Slack을 예로 사용합니다.

    Slack 채널

  4. 복사를 선택하여 봇 ID테넌트 ID 값을 복사하여 저장합니다. 봇을 Azure Bot Service 채널에 연결할 때 이것들이 필요합니다.

    봇 매개 변수 가져오기

Power Virtual Agents 봇과의 대화 세션 관리

Azure Bot Service 채널과 Direct Line 연결 간에 Power Virtual Agents 봇을 통한 여러 대화가 있을 수 있습니다.

Azure Bot Service 봇은 Azure Bot Service 채널에서 Direct Line 대화로 Power Virtual Agents 봇을 통해 또는 그 반대로 대화를 매핑하고 릴레이해야 할 수 있습니다.

샘플 코드 예

다음 예는 릴레이 봇 샘플 코드의 샘플을 사용합니다.

  1. 새로운 외부 Azure Bot Service 채널 대화가 시작될 때마다 Power Virtual Agents 대화가 시작됩니다. Direct Line 토큰 획득Direct Line을 사용하여 봇과 대화하기를 참조하여 봇과 새로운 대화를 시작하는 지침을 확인합니다.

    using (var httpRequest = new HttpRequestMessage())
    {   
        httpRequest.Method = HttpMethod.Get;
        UriBuilder uriBuilder = new UriBuilder(TokenEndPoint);
        uriBuilder.Query = $"botId={BotId}&tenantId={TenantId}";
        httpRequest.RequestUri = uriBuilder.Uri;
        using (var response = await s_httpClient.SendAsync(httpRequest))
        {
            var responseString = await response.Content.ReadAsStringAsync();
            string token = SafeJsonConvert.DeserializeObject<DirectLineToken>(responseString).Token;
        }
    }
    
    /// <summary>
    /// class for serialization/deserialization DirectLineToken
    /// </summary>
    public class DirectLineToken
    {
        public string Token { get; set; }
    }
    
     // Use the retrieved token to create a DirectLineClient instance
     using (var directLineClient = new DirectLineClient(token))
     {
         var conversation = await directLineClient.Conversations.StartConversationAsync();
         string conversationtId = conversation.ConversationId;
     }
    
  2. 여러 세션을 관리하려면 외부 Azure Bot Service 채널 대화와 해당 Power Virtual Agents 대화의 매핑을 유지해야 합니다. Power Virtual Agents 대화는 ConversationtIdToken이라는 두 가지 속성으로 식별 및 연결할 수 있습니다.

    Dictionary<string, PowerVirtualAgentsConversation> ConversationRouter = new Dictionary<string, PowerVirtualAgentsConversation>();  
    
    

    대화 수명주기를 관리하기 위해 Direct Line 토큰을 새로 고치거나 비활성화된 대화를 정리합니다. 토큰 새로 고침에 대한 자세한 내용은 Direct Line 토큰 새로 고침을 참조 바랍니다. 이를 지원하기 위한 Power Virtual Agents 대화는 다음과 같이 정의됩니다.

    /// <summary>
    /// Data model class for Power Virtual Agents conversation
    /// </summary>
    public class PowerVirtualAgentsConversation
    {
        public string ConversationtId { get; set; } // The Power Virtual Agents conversation ID retrieved from step 1
    
        public string Token { get; set; } // The DirectLine token retrieved from step 1
    
        public string WaterMark { get; set; } // Identify turn in a conversation
    
        public DateTime LastTokenRefreshTime { get; set; } = DateTime.Now; // Timestamp of last token refresh
    
        public DateTime LastConversationUpdateTime { get; set; } = DateTime.Now; // Timestamp of last active user message sent to bot
    }
    
  3. 새로운 Power Virtual Agents 대화가 시작되면 키 값 쌍(external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation)을 매핑 테이블에 추가하십시오.

    // After new Power Virtual Agents conversation starts
    ConversationRouter[external_Azure_Bot_Service_channel_conversationID] = new PowerVirtualAgentsConversation()
      {
        Token = token,
        ConversationtId = conversationId,
        WaterMark = null,
        LastConversationUpdateTime = DateTime.Now,
        LastTokenRefreshTime = DateTime.Now,
      }; 
    
  4. 기존 대화를 계속하려면 새 외부 Azure Bot Service 채널 메시지가 수신되었을 때 매핑 테이블에서 기존 대화를 검색하고 외부 대화 활동을 Power Virtual Agents 봇에 릴레이하여 응답을 얻습니다.

    다음 샘플은 ActivityHandler.OnMessageActivityAsync((ITurnContext, CancellationToken) 메서드를 재정의함으로써 대화 릴레이를 보여줍니다.

    // Invoked when a message activity is received from the user
    // Send the user message to Power Virtual Agents bot and get response
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        // Retrieve bot conversation from mapping table
        // If not exists for the given external conversation ID, start a new Power Virtual Agents conversation
        ConversationRouter.TryGetValue(externalCID, out PowerVirtualAgentsConversation currentConversation) ?
                currentConversation : /*await StartBotConversationAsync(externalCID)*/;
    
        // Create DirectLine client with the token associated to current conversation
        DirectLineClient client = new DirectLineClient(currentConversation.Token);
    
        // Send user message using directlineClient
        await client.Conversations.PostActivityAsync(currentConversation.ConversationtId, new DirectLineActivity()
        {
          Type = DirectLineActivityTypes.Message,
          From = new ChannelAccount { Id = turnContext.Activity.From.Id, Name = turnContext.Activity.From.Name },
          Text = turnContext.Activity.Text,
          TextFormat = turnContext.Activity.TextFormat,
          Locale = turnContext.Activity.Locale,
        });
    
        // Update LastConversationUpdateTime for session management
        currentConversation.LastConversationUpdateTime = DateTime.Now;
    }  
    
  5. Direct Line을 사용하여 봇과 대화하기를 참조하여 Power Virtual Agents 봇의 응답을 얻는 방법을 확인합니다. Power Virtual Agents 봇의 응답이 수신되면 외부 Azure Bot Service 채널 응답에 대한 응답을 구문 분석하는 방법을 위해 봇의 대화 페이로드 구문 분석을 참조하세요.

응답 구문 분석의 예는 릴레이 봇 샘플 코드 ResponseConverter.cs에서 찾을 수 있습니다.

Azure Bot Service에 배포

Azure Bot Service 릴레이 봇이 준비되었으면 봇을 Azure Bot Service에 배포해야 합니다.

Azure Bot Service 채널 설정

Azure Portal에 로그인하고 배포한 Azure Bot Service 리소스 그룹을 선택하여 연결하려는 채널을 설정할 수 있습니다. Azure Bot Service 채널에서 각 채널에 대한 특정 지침을 봅니다.