모바일 및 맞춤형 앱에 봇 추가

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

봇을 사용자 지정 앱에 연결하여 앱 사용자가 앱 내에서 봇과 직접 상호 작용할 수 있습니다.

대부분의 경우 사용자 지정 앱은 웹 기반 앱이거나 기본 앱이거나 비즈니스에 필요한 다른 서비스에 대한 어댑터인 모바일 장치 앱입니다.

앱이 웹 기반 앱인지 기본 앱인지에 따라 모바일 앱에 연결하는 절차는 다릅니다.

봇을 웹 기반 앱에 연결하려면 코드 조각을 앱에 복사하면 되므로 비교적 간단합니다. 그러나 웹 기반 앱과 기본 또는 사용자 지정 앱 모두 봇을 앱에 완전히 통합하려면 상당한 개발자 전문 지식이 필요합니다. 두 절차 다 이 문서에 설명되어 있습니다.

필수 구성 요소

봇을 웹 기반 앱에 연결

  1. Power Virtual Agents의 측면 탐색 창에서 관리를 선택하고 채널 탭으로 이동합니다.

  2. 모바일 앱 타일을 선택하여 구성 창을 엽니다.

  3. 웹 기반 앱 섹션 아래 코드를 복사하고 앱 개발자에게 제공하여 웹 기반 앱에 추가하십시오.

    웹 기반 애플리케이션에 봇 추가

봇을 기본 또는 맞춤형 앱에 연결

이 섹션에서는 모바일 앱에 연결하는 방법에 대해 설명하지만 IoT(사물 인터넷) 앱과 같은 사용자 지정 또는 기본 앱에 동일한 프로세스를 적용할 수 있습니다.

목표가 Azure Bot Service 채널에 연결하는 것이라면 여기 지침을 따르는 것 외에도 개발자는 Azure Bot Service 채널에 봇 연결에서 자세한 내용을 알아볼 수 있습니다.

중요

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

필수 구성 요소

샘플 코드

이 문서에 사용된 코드 조각의 출처는 다음과 같습니다.

참조

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

Power Virtual Agents 봇 매개 변수 검색

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

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

    봇 이름 얻기

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

  3. 모바일 앱을 선택합니다.

    모바일 앱 채널

  4. 복사를 클릭하여 봇 ID테넌트 ID 값을 복사하여 저장합니다. Direct Line 토큰 획득 단계에서 다음이 필요합니다.

    봇 매개 변수 가져오기

Direct Line 토큰 획득

Power Virtual Agents 봇과 대화를 시작하려면 Direct Line 토큰이 필요합니다. 봇 ID테넌트 ID로 이전 섹션에서 앱으로 Direct Line 토큰을 가져오는 코드를 추가해야 합니다.

Direct Line 토큰을 요청하려면 아래 끝점에 GET 요청을 발행합니다.

GET /api/botmanagement/v1/directline/directlinetoken
쿼리 매개 변수 필수 참석자
botId
tenantId

예제:

GET https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=<ENTER-YOUR-BOTID>&tenantId=<ENTER-YOUR-TENANTID>

요청이 성공하면 Direct Line 토큰이 요청된 봇에 대해 반환됩니다.

샘플 코드 예

다음은 커넥터 샘플 코드의 샘플을 사용하여 Power Virtual Agents 봇에 대한 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; }
}

응답은 다음과 같습니다.

{
  "token": "<token>"
}

Direct Line을 사용하여 봇과 통신하기

Direct Line 토큰을 가져온 후 Direct Line을 사용하여 Power Virtual Agents 봇과 대화할 수 있습니다. Bot Framework Direct Line API의 지침에 따라 대화를 시작하고 메시지를 보내고 받을 수 있습니다.

샘플 코드 예

다음 예제는 커넥터 샘플 코드의 샘플을 사용하여 대화를 시작하고 Power Virtual Agents 봇과 메시지를 주고 받습니다.

  1. Direct Line을 사용하여 DirectLineClient 인스턴스를 초기화하고 대화를 시작합니다.

      // 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. 시작되면 각 대화는 tokenconversationtId를 조합하여 식별하고 연결할 수 있습니다. 기존 대화에 사용자 메시지를 보냅니다.

      // Use the retrieved token to create a DirectLineClient instance
      // Use the conversationId from above step
      // endConversationMessage is your predefined message indicating that user wants to quit the chat
      while (!string.Equals(inputMessage = /*Get_User_Input()*/, endConversationMessage, StringComparison.OrdinalIgnoreCase))
      {
          using (var directLineClient = new DirectLineClient(token))
          {
              // Send user message using directlineClient
              // Payload is a Microsoft.Bot.Connector.DirectLine.Activity
              await directLineClient.Conversations.PostActivityAsync(conversationtId, new Activity()
              {
                  Type = ActivityTypes.Message,
                  From = new ChannelAccount { Id = "userId", Name = "userName" },
                  Text = inputMessage,
                  TextFormat = "plain",
                  Locale = "en-Us",
              });
          }
      }
    
  3. 동일한 tokenconverstaionId를 사용하여 봇의 응답을 검색합니다. 가져온 Direct Line 응답 활동에는 사용자와 봇의 메시지가 모두 포함됩니다. 봇 이름으로 응답 활동을 필터링하여 봇의 응답 메시지만 받을 수 있습니다.

      // Use the same token to create a directLineClinet
      using (var directLineClient = new DirectLineClient(token))
      {
          // To get the first response set string watermark = null
          // More information about watermark is available at
          // https://docs.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-direct-line-1-1-receive-messages?view=azure-bot-service-4.0
    
          // response from bot is of type Microsoft.Bot.Connector.DirectLine.ActivitySet
          ActivitySet response = await directLineClient.Conversations.GetActivitiesAsync(conversationtId, watermark);
    
          // update watermark from response
          watermark = response?.Watermark;
    
          // response contains set of Activity from both user and bot
          // To display bot response only, filter Activity.From.Name equals to your bot name
          List<Activity> botResponses = response?.Activities?.Where(x =>
                    x.Type == ActivityTypes.Message &&
                      string.Equals(x.From.Name, /*Bot_Name*/, StringComparison.Ordinal)).ToList();
    
          // Display botResponses
      }
    

Direct Line 토큰 새로 고침

앱이 봇과 긴 대화를 가졌다면 Direct Line 토큰을 새로 고치기 위해 코드를 추가해야 할 수도 있습니다. 토큰은 만료되지만 만료되기 전에 새로 고칠 수 있습니다. 자세한 내용은 Direct Line 인증을 참조 바랍니다.

샘플 코드 예

다음 예제는 커넥터 샘플 코드의 샘플을 사용하여 기존 Power Virtual Agents 대화에 대한 토큰을 새로 고칩니다.

  // DirectLine provides a token refresh method
  // Requires the currentToken valid when refreshing
  string refreshToken = new DirectLineClient(currentToken).Tokens.RefreshToken().Token;
  // create a new directline client with refreshToken
  directLineClient = new DirectLineClient(refreshToken);
  // use new directLineClient to communicate to your bot

봇의 대화 페이로드 구문 분석

봇과 대화를 시작한 후 JSON 페이로드 대화는 표준 Microsoft Bot Framework Direct Line 활동을 사용합니다. 자세한 내용은 Bot Framework Direct Line API에서 확인할 수 있습니다.

핸드오프 활동 처리

애플리케이션이 라이브 에이전트 공급자에게 핸드오프해야 하는 경우, 핸드오프 활동을 처리해야 합니다. "에이전트로 전송" 노드에 도달하면 핸드오프 활동이 전송됩니다. 핸드오프 활동의 페이로드에 대해 자세히 알아볼 수 있습니다.

환영 메시지 트리거

사용자가 대화를 시작할 때 봇이 인사말 시스템 토픽을 자동으로 보내려면 Type=eventName=startsConversation으로 활동을 보낼 수 있습니다.