Conectar um bot à Linha Direta

Este artigo descreve como conectar um bot ao canal Direct Line . Use esse canal para se comunicar com um bot por meio do seu aplicativo cliente.

Nota

Direct Line é um canal padrão sobre o protocolo HTTPS para permitir a comunicação entre um aplicativo cliente e um bot. Se, em vez disso, você precisar de isolamento de rede, use a Extensão do Serviço de Aplicativo de Linha Direta sobre WebSockets.

Pré-requisitos

  • Uma conta do Azure. Se ainda não tiver uma, crie uma conta gratuita antes de começar.
  • Um bot existente publicado no Azure.

Adicionar o canal Direct Line

A primeira coisa que você precisa fazer é adicionar o canal Direct Line ao seu bot.

  1. Aceda ao portal do Azure.
  2. Vá para seu recurso de Bot do Azure. Em Configurações de Bot, selecione Canais.
  3. Selecione Linha Direta na lista de Canais Disponíveis.

Seu bot agora está configurado para usar a Linha Direta usando o site Padrão.

Como alternativa, você pode adicionar um novo site em vez de usar o site padrão. Selecione o botão Novo site na página do canal Linha Direta para criar um novo site. Direct Line new site button in Azure portal

Gerenciar chaves secretas

Quando você adiciona o Canal Direto, o Bot Framework gera chaves secretas. Seu aplicativo cliente usa essas chaves para autenticar as solicitações de API de Linha Direta que ele emite para se comunicar com um bot. Para obter mais informações, veja Autenticação.

  1. Para visualizar o segredo da Linha Direta de um site em texto simples, vá para a página do canal Linha Direta .

  2. Selecione a guia Linha Direta e, em seguida, o site para o qual você deseja obter a chave, como Default_Site. O Azure abrirá um painel Configurar o site .

  3. Em Teclas secretas, selecione o ícone de olho ao lado da tecla correspondente.

    Show Direct Line keys

  4. Copie e armazene a chave com segurança. Use a chave para autenticar as solicitações de API de Linha Direta que seu aplicativo cliente emite para se comunicar com um bot.

    Nota

    Os segredos não devem ser expostos ou incorporados em aplicativos cliente. Veja o próximo passo.

  5. A prática recomendada é usar a API de Linha Direta para trocar a chave por um token. O aplicativo cliente usará o token para autenticar suas solicitações dentro do escopo de uma única conversa.

Configurar definições

Para definir as configurações do site:

  1. Na página Canal da Linha Direta, selecione o site que deseja configurar na lista Sites . O painel Configurar o site será aberto, mostrado abaixo: Configure site pane

  2. Selecione a versão do protocolo de linha direta que seu aplicativo cliente usará para se comunicar com um bot.

    Gorjeta

    Se você estiver criando uma nova conexão entre seu aplicativo cliente e o bot, use a API de Linha Direta 3.0.

  3. Quando terminar, selecione Aplicar para salvar a configuração do site. Repita esse processo, começando com um novo site, para cada aplicativo cliente que você deseja conectar ao seu bot.

Configurar autenticação avançada

Uma das configurações de site disponíveis são as opções de autenticação avançada, que ajudam a reduzir os riscos de segurança ao se conectar a um bot (usando o controle de bate-papo da Web, por exemplo). Para obter mais informações, consulte Autenticação avançada de linha direta.

Para adicionar autenticação avançada:

  1. Habilite as opções de autenticação Aprimorar. Uma mensagem que diz "Você deve ter pelo menos uma origem confiável." aparecerá com um link Adicionar uma origem confiável. Se você habilitar a autenticação avançada, deverá especificar pelo menos uma origem confiável.

    Uma origem confiável é um domínio usado pelo sistema para autenticar usuários. Nesse caso, a Linha Direta usa o domínio para gerar um token.

    • Se você configurar origens confiáveis como parte da página da interface do usuário de configuração, essas configurações sempre serão usadas como o único conjunto para a geração de um token. O envio de origens confiáveis adicionais (ou a definição de origens confiáveis como nenhuma) ao gerar um token ou iniciar uma conversa será ignorado (elas não são anexadas à lista ou validadas cruzadamente).
    • Se você não habilitou a autenticação avançada, qualquer URL de origem enviado como parte das chamadas de API será usado. Add trusted origin
  2. Depois de adicionar um URL de domínio confiável, selecione Aplicar.

Bot de exemplo de linha direta

Você pode baixar um exemplo .NET deste local: Direct Line Bot Sample.

O exemplo contém dois projetos:

  • DirectLineBot. Ele cria um bot para se conectar através de um canal de Linha Direta.
  • DirectLineClient. Este é um aplicativo de console que conversa com o bot anterior via canal Direct Line.

API de Linha Direta

  • As credenciais para a API de Linha Direta devem ser obtidas do registro do Bot do Azure e só permitirão que o chamador se conecte ao bot para o qual foram geradas. No projeto bot, atualize o appsettings.json arquivo com esses valores.

    {
    "MicrosoftAppId": "",
    "MicrosoftAppPassword": ""
    }
    
  • No portal do Azure, habilite Linha Direta na lista de canais e configure o segredo da Linha Direta. Verifique se a caixa de seleção da versão 3.0 está marcada. No projeto do cliente de console, atualize o arquivo com a chave secreta da Linha Direta e o App.config identificador do bot (ID do Bot).

    <appSettings>
        <add key="DirectLineSecret" value="YourBotDirectLineSecret" />
        <add key="BotId" value="YourBotHandle" />
    </appSettings>
    

As mensagens do usuário são enviadas para o bot usando o método Direct Line Client Conversations.PostActivityAsync usando o ConversationId gerado anteriormente.

while (true)
{
    string input = Console.ReadLine().Trim();

    if (input.ToLower() == "exit")
    {
        break;
    }
    else
    {
        if (input.Length > 0)
        {
            Activity userMessage = new Activity
            {
                From = new ChannelAccount(fromUser),
                Text = input,
                Type = ActivityTypes.Message
            };

            await client.Conversations.PostActivityAsync(conversation.ConversationId, userMessage);
        }
    }
}