Adicionar bot do Power Virtual Agents a canais do Serviço de Bot do Azure

Você pode conectar seu bot a canais existentes do Serviço de Bot do Azure. Isso pode ser útil se você deseja conectar seu bot aos usuários finais nos canais do Serviço de Bot do Azure.

Adicionar seu bot aos canais do Serviço de Bot do Azure requer um conhecimento considerável de desenvolvedor. Este tópico foi escrito para administradores ou desenvolvedores de TI com experiência no desenvolvimento e gravação de código.

Gorjeta

Você não precisa seguir este documento para adicionar seu bot do Power Virtual Agents ao seu site, Facebook ou Microsoft Teams. Se seu objetivo é conectar-se a um aplicativo personalizado nativo ou baseado na Web, seus desenvolvedores podem aprender mais em Adicionar bot a aplicativos móveis e personalizados.

Importante

De acordo com as instruções nesta seção, seus desenvolvedores ou você precisam desenvolver um software. Elas são direcionadas a profissionais de TI experientes, como administradores ou desenvolvedores de TI que tenham um sólido entendimento de utilitários, IDEs e ferramentas para desenvolvedores.

Pré-requisitos

• Saiba mais sobre o que você pode fazer com o Power Virtual Agents.
• Uma assinatura do Serviço de Bot do Azure.
• Um bot do Serviço de Bot do Azure usando o SDK v4.
• SDK do .NET Core versão 2.1.
• Pacote de NuGet Microsoft.Bot.Connector.DirectLine.
• Um bot criado no Power Virtual Agents que você deseja conectar a um canal do Serviço de Bot do Azure.
• Conectar seu bot a aplicativos móveis e personalizados.

Exemplos de códigos

Os trechos de código usados neste documento são do exemplo de código do bot de retransmissão.

Referências

As instruções neste documento fazem referência a estes tópicos:

• Implantar seu bot no Azure para obter instruções sobre a implantação do Serviço de Bot do Azure.
• Canais do Serviço de Bot do Azure para conectar-se a qualquer canal com suporte pelo Serviço de Bot do Azure.
• Depuração do Serviço de Bot do Azure com o emulador para obter instruções sobre depuração do bot do Serviço de Bot do Azure.

Criar ou usar um bot existente do Serviço de Bot do Azure

Você precisa de um bot do Serviço de Bot do Azure que possa retransmitir conversas entre seu bot do Power Virtual Agents e canais do Serviço de Bot do Azure.

O exemplo de código do bot de retransmissão é um bom ponto de partida se você não tem um bot existente do Serviço de Bot do Azure. Ele é criado por meio do bot do Microsoft Bot Framework exemplo de código que pode ser compilado e implementado no Serviço de Bot do Azure. A intenção é usar o exemplo de código como ponto de partida, e não deve ser usado diretamente na produção. Você precisará adicionar código e otimização para atender às suas necessidades de negócios.

Se você já possui um bot do Serviço de Bot do Azure, precisará adicionar um conector do Power Virtual Agents e código para gerenciar sessões de conversa. Em seguida, você pode implantar o bot no Serviço de Bot do Azure e conectar-se aos canais com o portal do Azure.

Obter parâmetros do seu bot do Power Virtual Agents

Para se conectar ao bot que você criou com o Power Virtual Agents, é necessário recuperar o ponto de extremidade do token e o nome do bot.

1. Copie o nome do seu bot no Power Virtual Agents.

   

2. No menu de navegação, em Configurações, selecione Canais.

3. Selecione o canal ao qual você deseja se conectar. Este tópico usa Slack como um exemplo.

   

4. Para copiar e salvar o valor Ponto de Extremidade do Token, selecione Copiar. Você precisa do ponto de extremidade para conectar o bot ao canal do Serviço de Bot do Azure.

   

Gerenciar sessões de conversa com seu bot do Power Virtual Agents

Pode haver várias conversas entre os canais do Serviço de Bot do Azure e a conexão da Direct Line com o seu bot do Power Virtual Agents.

O bot do Serviço de Bot do Azure precisará mapear e retransmitir a conversa do canal do Serviço de Bot do Azure para a conversa da Direct Line com o bot do Power Virtual Agents e vice-versa.

Exemplo de código

O exemplo a seguir usa partes do exemplo de código do bot de retransmissão.

1. Em cada novo início de conversa do canal externo do Serviço de Bot do Azure, inicie uma conversa do Power Virtual Agents. Consulte Obter token da Direct Line e Usar a Direct Line para se comunicar com o bot para obter instruções sobre como iniciar uma nova conversa com o bot.

   using (var httpRequest = new HttpRequestMessage())
   {   
       httpRequest.Method = HttpMethod.Get;
       UriBuilder uriBuilder = new UriBuilder(TokenEndPoint);
       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. Para gerenciar várias sessões, você precisa manter um mapeamento de conversas do canal externo do Serviço de Bot do Azure com as conversas correspondentes do Power Virtual Agents. Uma conversa do Power Virtual Agents pode ser identificada e conectada a duas propriedades: ConversationtId e Token.

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

   Para gerenciar o ciclo de vida da conversa, atualize os tokens do Direct Line ou limpe as conversas inativas. Saiba mais sobre a atualização de token em Atualizar o token do Direct Line. A seguir, definimos uma conversa do Power Virtual Agents para dar suporte a isso:

   /// <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. Quando uma nova conversa do Power Virtual Agents começar, adicione um par de chave/valor (external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation) à tabela de mapeamento.

   // 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. Para continuar em uma conversa existente, quando uma nova mensagem do canal externo do Serviço de Bot do Azure é recebida, recupere a conversa existente da tabela de mapeamento, retransmita a atividade de conversa externa para o bot do Power Virtual Agents e obtenha uma resposta.

   O exemplo a seguir mostra a retransmissão da conversa, substituindo o método ActivityHandler.OnMessageActivityAsync((ITurnContext<IMessageActivity>, 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. Consulte Usar a Direct Line para se comunicar com o bot para saber como obter resposta do bot do Power Virtual Agents. Quando a resposta do bot do Power Virtual Agents for recebida, consulte Analisar o conteúdo da conversa do bot para saber como analisar a resposta do canal externo do Serviço de Bot do Azure.

Um exemplo de análise de resposta pode ser encontrado em ResponseConverter.cs do exemplo de código do bot de retransmissão.

Implantar no Serviço de Bot do Azure

Quando o bot de retransmissão do Serviço de Bot do Azure estiver pronto, você precisará implantar o bot no seu Serviço de Bot do Azure.

Configurar canais do Serviço de Bot do Azure

Você pode configurar os canais aos quais deseja se conectar entrando no portal do Azure e selecionando o grupo de recursos do Serviço de Bot do Azure no qual você implantou. Veja as instruções específicas para cada canal em Canais do Serviço de Bot do Azure.