Configurar o bot do Node.js para a extensão

  • Artigo

A partir de 1º de setembro de 2023, é altamente recomendável empregar o método de Marca de Serviço do Azure para isolamento de rede. A utilização do DL-ASE deve ser limitada a cenários altamente específicos. Antes de implementar essa solução em um ambiente de produção, recomendamos consultar sua equipe de suporte para obter orientação.

APLICA-SE A: SDK v4

Este artigo descreve como atualizar um bot Node.js para trabalhar com pipes nomeados e como habilitar a extensão de serviço de aplicativo do Direct Line no recurso de Serviço de Aplicativo do Azure em que o bot está hospedado.

Pré-requisitos

  • Uma conta do Azure. Se ainda não tiver uma, crie uma conta gratuita antes de começar.
  • Um bot Node.js implantado no Azure.
  • SDK do Bot Framework para Node.js 4.7 ou posterior.

Habilitar a Extensão de Serviço de Aplicativo do Direct Line

Esta seção descreve como habilitar a extensão do serviço de aplicativo do Direct Line usando a chave de extensão do serviço de aplicativo da configuração de canal do Direct Line do seu bot.

Atualizar o código do bot

Para permitir que seu aplicativo use o Pipe nomeado da Extensão do Serviço de Aplicativo do Direct Line:

  1. Edite o arquivo de seu bot index.js.

    1. Localize a linha onde você cria o adaptador do bot.

    2. Depois que o adaptador for criado, adicione a instrução a seguir, que extrairá o nome do Serviço de Aplicativo do ambiente e instruirá o adaptador a se conectar ao pipe nomeado apropriado.

      • Se o bot usar o CloudAdapter (recomendado):

        adapter.connectNamedPipe(
    process.env.APPSETTING_WEBSITE_SITE_NAME + '.directline',
    async (context) => {
        await myBot.run(context);
    },
    process.env.MicrosoftAppId,
    AuthenticationConstants.ToChannelFromBotOAuthScope);

      • Se o bot usar o BotFrameworkAdapter preterido:

        adapter.useNamedPipe(async (context) => {
    await myBot.run(context);
    },
    process.env.APPSETTING_WEBSITE_SITE_NAME + '.directline'
);

    3. Salve suas alterações.

  2. Edite o arquivo web.config do seu bot para adicionar o manipulador AspNetCore necessário para a Extensão do Serviço de Aplicativo do Direct Line para solicitações de serviço.

    1. Edite o arquivo de seu bot web.config.

    2. Altere o atributo webSocket da tag enabled para true.

      <webSocket enabled="true" />

    3. Na seção <handlers>, adicione um registro para o manipulador a seguir.

      <add name="aspNetCore" path="*/.bot/*" verb="*" modules="AspNetCoreModule" resourceType="Unspecified" />

    4. Na seção <rewrite>, adicione a seguinte regra à lista de regras.

      <!-- Do not interfere with Direct Line App Service extension requests. (This rule should be as high in the rules section as possible to avoid conflicts.) -->
<rule name ="DLASE" stopProcessing="true">
  <conditions>
    <add input="{REQUEST_URI}" pattern="^/.bot"/>
  </conditions>
</rule>

    5. Salve suas alterações.

  3. Implantar novamente seu bot atualizado no Azure.

Habilite a Extensão de Serviço de Aplicativo do Direct Line do bot

  1. No portal do Azure, acesse o recurso Bot do Azure.

    1. Em Configurações, selecione Canais para configurar os canais dos quais o bot aceita mensagens.
    2. Se ainda não estiver habilitado, selecione o canal do Direct Line na lista de Canais disponíveis para habilitar o canal.
    3. Depois de habilitar o Direct Line, selecione-o novamente na página Canais.
    4. Selecione a guia Extensão do Serviço de Aplicativo.
    5. Em Chaves de Extensão do Serviço de Aplicativo, selecione o ícone de olho ao lado da chave correspondente.

  2. Acesse a home page e selecione Serviços de Aplicativo na parte superior da página. Como alternativa, exiba o menu do portal e selecione o item de menu Serviços de Aplicativo. O Azure exibirá a página Serviços de Aplicativo.

  3. Na caixa de pesquisa, digite o nome do recurso do Bot do Azure. Seu recurso estará listado.

    Observe que, se você passar o mouse sobre o ícone ou o item de menu, obterá uma lista dos últimos recursos visualizados. Seu recurso de Bot do Azure provavelmente estará listado.

  4. Selecione o link de recursos.

    1. Na seção Configurações, selecione o item de menu Configuração.

    2. No painel à direita, adicione as seguintes configurações:

      Nome Valor
      DirectLineExtensionKey O valor da chave de extensão do Serviço de Aplicativo que você copiou anteriormente.
      DIRECTLINE_EXTENSION_VERSION mais recente

    3. Se o bot estiver hospedado em uma nuvem do Azure soberana ou restrita, onde você não acessa o Azure por meio do portal público, você também precisará adicionar a seguinte configuração:

      Nome Valor
      DirectLineExtensionABSEndpoint O ponto de extremidade específico para a nuvem do Azure em que seu bot está hospedado. Para a nuvem USGov, por exemplo, o ponto de extremidade é https://directline.botframework.azure.us/v3/extension.

    4. Na seção Configuração, selecione a seção de configurações Gerais e ative os Webs sockets.

    5. Clique em Salvar para salvar as configurações. Isso reinicia o Serviço de Aplicativo do Azure.

Confirme a extensão do Direct Line e que o bot estão configurados

No navegador, vá para https://<your_app_service>.azurewebsites.net/.bot. Se tudo estiver correto, a página retornará o seguinte conteúdo JSON:

    {"v":"123","k":true,"ib":true,"ob":true,"initialized":true}
  • v exibe a versão de build da Extensão de Serviço de Aplicativo do Direct Line.
  • k indica se a extensão foi capaz de ler uma chave de extensão em sua configuração.
  • initialized indica se a extensão foi capaz de fazer download dos metadados de bot do Serviço de Bot de IA do Azure.
  • ib indica se a extensão foi capaz de estabelecer uma conexão de entrada com o bot.
  • ob indica se a extensão foi capaz de estabelecer uma conexão de saída com o bot.

Solução de problemas

  • Se os valores ib e ob exibidos pelo ponto de extremidade .bot forem false, o bot e a extensão do Serviço de Aplicativo do Direct Line não poderão se conectar um ao outro.

    1. Verifique se o código para usar pipes nomeados foi adicionado ao bot.
    2. Confirme se o bot está em funcionamento. As ferramentas úteis são Testar no Webchat, conectar um canal adicional, depuração remota ou registro em log.
    3. Reinicie todo o Serviço de Aplicativo do Azure no qual o bot está hospedado para garantir uma inicialização limpa de todos os processos.

  • Se o valor inicializado do ponto de extremidade do .bot for false, a extensão do Serviço de Aplicativo do Direct Line não poderá validar a chave de extensão do Serviço de Aplicativo adicionada às Configurações de Aplicativo do bot acima.

    1. Confirme se o valor foi digitado corretamente.
    2. Alterne para a chave de extensão alternativa mostrada na página Configurar o Direct Line do bot.

Próximas etapas

Usar o Webchat com a extensão de serviço de aplicativo do Direct Line