Publicar um copiloto aos canais do Serviço de Bot do Azure

Você pode conectar seu copiloto a canais existentes do Azure Serviço de Bot , o que pode ser útil se você quiser conectar seu copiloto a usuários finais em canais do Azure Serviço de Bot.

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

Pré-requisitos

• Uma assinatura do Serviço de Bot do Azure.
• Um bot do Serviço de Bot do Azure usando o SDK v4.
• .NET Core SDK versão 2.1.
• Pacote de NuGet Microsoft.Bot.Connector.DirectLine.
• Um copiloto criado no Copilot Studio que você deseja conectar a um canal do Serviço de Bot do Azure.
• Publique um copiloto em aplicativos móveis ou 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 aos seguintes documentos:

• Implante seu bot no Azure para obter instruções sobre como implantar o Azure Serviço de Bot bot.
• Canais do Azure Serviço de Bot para se conectar a qualquer canal com suporte do serviço Azure bot.
• Depuração do Azure Serviço de Bot com o emulador para obter instruções sobre como depurar o Azure Serviço de Bot bot.

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 copiloto do Copilot Studio e canais do Serviço de Bot do Azure.

O código de exemplo do relay bot é um bom ponto de partida se você não tiver um Azure Serviço de Bot bot. existente Ele foi criado a partir de Microsoft Bot Framework bot código de exemplo que pode ser compilado e implantado no Azure Serviço de Bot. A intenção é usar o exemplo de código como ponto de partida, e não deve ser usado diretamente na produção. Você precisa adicionar código e otimização para atender às necessidades do seu negócio.

Se você já possui um bot do Serviço de Bot do Azure, precisará adicionar um conector do Copilot Studio 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 copiloto do Copilot Studio

Para se conectar ao copiloto que você criou com Copilot Studio, você precisa recuperar o nome do seu copiloto e o ponto de extremidade do token.

1. Copie o nome do seu copiloto no Copilot Studio.

   

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

3. Selecione o canal ao qual você deseja se conectar. Este cenário usa Slack como um exemplo.

   

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

   

Gerenciar sessões de conversa com seu copiloto do Copilot Studio

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 copiloto do Copilot Studio.

Seu Azure Serviço de Bot bot precisa mapear e retransmitir a conversa do canal Azure Serviço de Bot para a Direct Line conversa com o Copilot Studio copiloto 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 copiloto do Copilot Studio. Consulte Obter token da Direct Line e Usar a Direct Line para se comunicar com o copiloto 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 do copiloto correspondentes do Copilot Studio. Uma conversa do copiloto do Copilot Studio 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. Uma conversa de copiloto para dar suporte à atualização de tokens é definida da seguinte forma: Copilot Studio Direct Line

   /// <summary>
   /// Data model class for Copilot Studio copilot conversation
   /// </summary>
   public class PowerVirtualAgentsConversation
   {
       public string ConversationtId { get; set; } // The Copilot Studio copilot 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 copilot
   }
   

3. Quando uma nova conversa do copiloto do Copilot Studio começar, adicione um par de chave/valor (external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation) à tabela de mapeamento.

   // After new Copilot Studio copilot 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 copiloto do Copilot Studio 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 Copilot Studio copilot and get response
   protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
   {
       // Retrieve copilot conversation from mapping table
       // If not exists for the given external conversation ID, start a new Copilot Studio copilot 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 copiloto para saber como obter resposta do copiloto do Copilot Studio. Quando a resposta do copiloto do Copilot Studio for recebida, consulte Analisar o conteúdo da conversa do copiloto 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 efetuando login no portal do Azure e selecionando o grupo de recursos do Azure Serviço de Bot no qual você implantou. Veja as instruções específicas para cada canal em Canais do Serviço de Bot do Azure.