Conectar um bot ao Direct Line

Artigo
12/29/2023

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

Observação

O Direct Line é um canal padrão sobre protocolo HTTPS para permitir a comunicação entre um aplicativo cliente e um bot. Se você precisar de isolamento de rede, use a Extensão de Serviço de Aplicativo do Direct Line em 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 de linha direta

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

Acesse o Portal do Azure.
Acesse o recurso de Bot do Azure. Em Configurações do bot, selecione Canais.
Selecione Direct Line na lista de Canais disponíveis.

Seu bot agora está configurado para usar o Direct Line via 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 do Direct Line para criar um 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 do Direct Line API emitidas para se comunicar com um bot. Para obter mais informações, confira Autenticação.

Para exibir o segredo do Direct Line de um site em texto sem formatação, vá para a página do canal do Direct Line.
Selecione aguia Direct Line, e, em seguida, o site para o qual você deseja obter a chave, como Default_Site. O Azure abrirá um painel Configurar o site.
Em Chaves secretas, selecione o ícone de olho ao lado da chave correspondente.
Copie e armazene com segurança a chave. Use a chave para autenticar as solicitações do Direct Line API que o seu aplicativo cliente emitiu para se comunicar com um bot.

Observação

Os segredos não devem ser expostos ou incorporados em aplicativos cliente. Confira as próximas etapas.
A melhor prática é usar o Direct Line API para trocar a chave por um token. O aplicativo cliente, em seguida, usará o token para autenticar suas solicitações dentro do escopo de uma única conversa.

Definir configurações

Para definir as configurações do site:

Na página do canal do Direct Line, selecione o site que deseja configurar na lista de Sites. O painel Configurar o site será aberto, mostrado abaixo de:
Selecione a versão do protocolo Direct Line que seu aplicativo cliente usará para se comunicar com seu bot.

Dica

Se você estiver criando uma nova conexão entre seu aplicativo cliente e o bot, use o Direct Line API 3.0.
Quando terminar, clique em Concluído para salvar a configuração do site. Você pode repetir esse processo, começando com Adicionar 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 do WebChat, por exemplo). Para obter mais informações, confira Autenticação avançada do Direct Line.

Para adicionar autenticação avançada:

Habilite Aprimorar opções de autenticação. 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 Direct Line 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, elas sempre serão usadas como o único conjunto para a geração de um token. Enviar origens confiáveis adicionais (ou definir origens confiáveis como nenhuma) ao gerar um token ou iniciar uma conversa será ignorado (ou seja, não serão acrescentadas à lista nem terão validação cruzada).
- Se você não habilitou a autenticação avançada, qualquer URL de origem enviada como parte das chamadas de API será usada.
Depois de adicionar uma URL de domínio confiável, selecione Aplicar.

Exemplo de Bot do Direct Line

Você pode fazer download de um exemplo .NET deste local: Amostra do Direct Line Bot.

Este exemplo contém dois projetos:

DirectLineBot. Ele cria um bot para se conectar por meio de um canal do Direct Line.
DirectLineClient. Este é um aplicativo de console que conversa com o bot anterior via canal Direct Line.

Direct Line API

As credenciais para o Direct Line API 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 do bot, atualize o arquivo appsettings.json com esses valores.
```
{
"MicrosoftAppId": "",
"MicrosoftAppPassword": ""
}
```
No portal do Azure, habilite o Direct Line na lista de canais e configure o segredo do Direct Line. Verifique se a caixa de seleção da versão 3.0 está marcada. No projeto de cliente de console, atualize o arquivo App.config com a chave secreta do Direct Line e o identificador do bot (ID do Bot).
```
<appSettings>
    <add key="DirectLineSecret" value="YourBotDirectLineSecret" />
    <add key="BotId" value="YourBotHandle" />
</appSettings>
```

As mensagens de usuário são enviadas ao bot por meio do método Cliente Conversations.PostActivityAsync do Direct Line 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);
        }
    }
}

Share via