Solução de problemas geral para bots do Serviço de Bot de IA do Azure

APLICA-SE A: SDK v4

Essas perguntas frequentes podem ajudá-lo a solucionar problemas comuns de desenvolvimento de bot ou operacionais.

Como é possível solucionar problemas com o bot?

1. Depure o código-fonte do bot com Visual Studio Code ou Visual Studio.
2. Teste o bot usando o Bot Framework Emulator antes de implantá-lo na nuvem.
3. Implante seu bot em uma plataforma de hospedagem na nuvem, como o Azure e, em seguida, teste a conectividade com o bot usando o controle de webchat interno do dashboard do bot no portal do Azure. Se você encontrar problemas com o bot depois de implantá-lo no Azure, considere usar este artigo de blog: Entendendo a solução de problemas e suporte do Azure.
4. Exclua a autenticação como um possível problema.
5. Teste seu bot no Webchat, no Teams ou em qualquer outro canal que você pretende usar com o bot. Isso irá ajudá-lo a validar a experiência do usuário de ponta a ponta.
6. Considere testar o bot em canais que tenham requisitos de autenticação adicionais, como o Direct Line ou o Webchat.
7. Leia as instruções sobre como depurar um bot e outros artigos sobre depuração nesta seção.

Como é possível solucionar problemas issues de autenticação?

Para obter detalhes sobre como solucionar problemas de autenticação com o bot, confira solucionar problemas de autenticação do Bot Framework.

Como fazer para testar a conexão de rede entre bots e um canal?

Você pode usar os endereços IP, gerados pelas etapas abaixo, para verificar se há alguma regra bloqueando a conexão com esses endereços. Confira a seção Verificar rastreamentos de firewall em conexões com falha.

Testar conectividade do bot com o canal

1. No navegador, acesse o portal do Azure.

2. Selecione o Serviço de Aplicativo de bot cuja conexão deseja testar.

3. No painel esquerdo, na seção Ferramentas de Desenvolvimento, selecione Ferramentas Avançadas.

4. No painel direito, selecione Acessar. A página de informações do Kudu é exibida.

5. Na barra de menu superior, selecione Console de Depuração. Depois, no menu suspenso, selecione CMD. O console do aplicativo Web do bot Kudu está aberto. Para obter mais informações, confira Kudu.

   

6. Execute nslookup directline.botframework.com e verifique se a resolução DNS está funcionando. Observe que nslookup (pesquisa de servidor de nomes) é uma ferramenta de linha de comando de administração de rede para consultar o DNS (Sistema de Nomes de Domínio) para obter mapeamento de nome de domínio ou endereço IP ou outros registros DNS. Se a resolução DNS estiver funcionando, a resposta a esse comando conterá as informações relevantes.

   

   A ferramenta de pesquisa de IP WHOIS é útil para obter informações sobre endereços IP.

7. Execute curl -I directline.botframework.com. (A opção -I é usada para obter uma resposta contendo apenas o cabeçalho.) Verifique se um status HTTP de 301 é retornado para verificar se há conectividade.

   

Testar conectividade do bot com o canal

Como o curl não tem acesso ao local de produção e directline.botframework.com está na Internet pública, você deve usar o curl no modo de simulação. Execute as etapas mostradas abaixo fora de uma Rede Virtual Privada (VNET), por exemplo, usando um hotspot de celular. Confira também O que é a Rede Virtual do Azure?.

1. Execute nslookup ivr-sr-bot.botapps.amat.com. A resolução DNS estará funcionando se a resposta a esse comando contiver informações relevantes.

   

2. Execute curl -I https://ivr-sr-bot.botapps.amat.com/api/messages e verifique se um código de status HTTP apropriado é retornado (por exemplo, método 405 não permitido). O método especificado na solicitação não é permitido para o recurso identificado pelo URI especificado. Esta é apenas uma maneira de verificar se há conectividade.

   

3. Se você não receber a resposta do bot, anote o endereço IP do cliente.

Confira os rastreamentos de firewall em conexões com falha

Use os endereços IP de nslookup ivr-sr-bot.botapps.amat.com e nslookup directline.botframework.com e verifique se há uma regra bloqueando a conexão com esses endereços em qualquer direção.

Estou usando o SDK do Bot Framework para .NET. Como é possível solucionar problemas com o bot?

Procure exceções

No Visual Studio 2019, acesse Depurar>Windows>Configurações de Exceção. Na janela Configurações de Exceção, marque a caixa de seleção Interromper Quando Lançado próximo a Exceções do Common Language Runtime. Também é possível ver a saída de diagnóstico na janela Saída quando houver exceções lançadas ou não tratadas.

Verifique a pilha de chamadas

No Visual Studio, é possível escolher se está depurando Apenas Meu Código ou não. Examinar a pilha de chamadas completa pode fornecer insights adicionais sobre quaisquer issues.

Assegure-se de que todos os métodos de diálogo terminem com um plano para manipular a próxima mensagem

Todas as etapas do diálogo precisam alimentar a próxima etapa da cascata, ou encerrar o diálogo atual para retirá-lo na pilha. Se uma etapa não for tratada corretamente, a conversa não continuará como você espera. Dê uma olhada no artigo de conceito sobre diálogos para saber mais sobre diálogos.

O que causa um erro com o código de status HTTP 429 "Muitas solicitações"?

Uma resposta de erro com o código de status HTTP 429 indica que muitas solicitações foram emitidas em um determinado período de tempo. O corpo da resposta deve incluir uma explicação do problema e também especificar o intervalo mínimo requerido entre as solicitações.

Por que as mensagens do meu bot não estão sendo recebidas pelo usuário?

A atividade de mensagem gerada na resposta deve ser encaminhada corretamente, caso contrário, não chegará ao destino pretendido. Na grande maioria dos casos, você não precisará lidar com isso explicitamente. O SDK se encarrega do endereçamento da atividade de mensagem para você.

Endereçar corretamente uma atividade significa incluir os detalhes apropriados da ID de conversa juntamente com os detalhes sobre o remetente. Na maioria dos casos, a atividade de mensagem é enviada em resposta a uma que chegou. Portanto, os detalhes de encaminhamento podem ser retirados da atividade de entrada.

Se você examinar os rastreamentos ou logs de auditoria, poderá verificar se as mensagens foram encaminhadas corretamente. Se não tiverem sido, defina um ponto de interrupção em seu bot e veja onde as IDs estão sendo definidas para a mensagem.

Como é possível executar tarefas em segundo plano no ASP.NET?

Em alguns casos, convém iniciar uma tarefa assíncrona que aguarda alguns segundos e, em seguida, executa algum código para limpar o perfil do usuário ou redefinir o estado de diálogo/conversa. Para obter detalhes sobre como realizar isso, confira Como executar tarefas em segundo plano no ASP.NET. Em particular, considere o uso de HostingEnvironment.QueueBackgroundWorkItem.

O bot demora a responder à primeira mensagem que recebe. Como é possível torná-lo mais rápido?

Os bots são serviços Web e algumas plataformas de hospedagem, incluindo o Azure, colocam automaticamente o serviço em suspensão se não receberem tráfego por um determinado período. Se isso acontecer com o bot, ele deverá reiniciar a partir do zero na próxima vez em que receber uma mensagem, o que tornará a resposta muito mais lenta do que se já estivesse em execução.

Algumas plataformas de hospedagem permitem que você configure o serviço para que não seja colocado em suspensão. Se o bot estiver hospedado nos Aplicativos Web do Serviço de Bot de IA do Azure, acesse o serviço do bot no portal do Azure, selecione Configurações do aplicativo e, em seguida, selecione Sempre ativado. Essa opção está disponível na maioria dos planos de serviço, mas não em todos.

Como é possível garantir a ordem de entrega da mensagem?

O Bot Framework irá preservar a ordem das mensagens, tanto quanto possível. Por exemplo, se você enviar mensagem A e aguardar a conclusão dessa operação HTTP antes de iniciar outra operação HTTP para enviar a mensagem B. Alguns canais, como SMS e email, não garantem a ordem em que o usuário receberá as mensagens.

Por que partes do texto da mensagem estão sendo removidas?

O Bot Framework e muitos canais interpretam o texto como se estivesse formatado com Markdown. Verifique se o texto contém caracteres que podem ser interpretados como sintaxe de Markdown.

Como oferecer suporte a vários bots no mesmo ponto de extremidade de serviço de bot?

Esse exemplo mostra como configurar o Conversation.Container com o MicrosoftAppCredentials correto e usar um MultiCredentialProvider simples para autenticar várias IDs do Aplicativo e senhas.

Como os identificadores funcionam no Bot Framework?

Para mais detalhes sobre os identificadores no Bot Framework, confira o guia para identificadores do Bot Framework.

Como é possível obter acesso à ID de usuário?

Os canais do Bot Framework apresentam a ID do usuário no campo from.Id de qualquer Atividade enviada pelo usuário. SMS e mensagens de email fornecerão a ID de usuário bruta nessa propriedade. Alguns canais ocultam a propriedade from.Id, portanto, ela contém uma ID exclusiva para o usuário que difere da ID do usuário no canal. Se for necessário conectar uma conta existente, você poderá usar um cartão de entrada e implementar seu próprio fluxo do OAuth para conectar a ID de usuário à ID de usuário do seu próprio serviço.

Por que meus nomes de usuário do Facebook não estão mais sendo exibidos?

Você alterou a senha do Facebook? Isso invalidará o token de acesso e será necessário atualizar as configurações do seu bot para o canal do Facebook Messenger no portal do Azure.

Como é possível usar serviços autenticados do meu bot?

Para autenticação do Microsoft Entra ID, confira o tutorial Adicionar autenticação ao bot.

Observação

Se você adicionar a funcionalidade de autenticação e segurança ao bot, certifique-se de que os padrões implementados no código estejam em conformidade com os padrões de segurança apropriados ao aplicativo.

Como é possível limitar o acesso ao bot para uma lista predeterminada de usuários?

Alguns canais, como SMS e email, fornecem endereços sem escopo. Nesses casos, as mensagens do usuário conterão a ID de usuário bruta na propriedade from.Id.

Outros canais, como Facebook e Slack, fornecem endereços com escopo ou locados de modo a impedir que um bot possa prever a ID de um usuário com antecedência. Nesses casos, você precisará autenticar o usuário por meio de um link de logon ou segredo compartilhado para determinar se estão ou não autorizados a usar o bot.

Por que minha conversa com o Direct Line 1.1 inicia novamente após cada mensagem?

Observação

Estas seções não se aplicam à última versão do protocolo do Direct Line, 3.0

Se a conversa com Direct Line parece iniciar novamente após cada mensagem, a propriedade from provavelmente está ausente ou null nas mensagens que o cliente Direct Line enviou para o bot. Quando um cliente Direct Line enviar uma mensagem com a propriedade from ausente ou null, o serviço Direct Line alocará automaticamente uma ID, portanto, todas as mensagens enviadas pelo cliente parecerão originar de um novo usuário diferente.

Para corrigir isso, defina a propriedade from em cada mensagem que o cliente Direct Line envia para um valor estável que represente exclusivamente o usuário que está enviando a mensagem. Por exemplo, se um usuário já estiver conectado a um aplicativo ou página da Web, será possível usar essa ID de usuário existente como o valor da propriedade from nas mensagens que o usuário enviar. Como alternativa, é possível optar por gerar uma ID de usuário aleatória no carregamento da página ou carregamento do aplicativo, armazenar a ID em um estado do dispositivo ou cookie e usar essa ID como o valor da propriedade from nas mensagens que o usuário enviar.

O que faz com que o serviço do Direct Line 3.0 responda com o código de status HTTP 502 "Gateway Incorreto"?

O Direct Line 3.0 retorna o código de status HTTP 502 quando tenta contatar o seu bot, mas a solicitação não é concluída com êxito. Esse erro indica que o bot retornou um erro ou que a solicitação expirou. Para obter mais informações sobre erros que o bot gera, acesse o dashboard do bot no Portal do Azure e selecione o link "Issues" do canal afetado. Se você tiver o Application Insights configurado para o bot, também poderá procurar informações detalhadas sobre erros nele.

Por que recebo uma exceção Authorization_RequestDenied ao criar um bot?

A permissão para criar bots do Serviço de Bot de IA do Azure é gerenciada por meio do portal do Microsoft Entra ID. Se as permissões não estiverem configuradas corretamente no Centro de Administração do Microsoft Entra ID, os usuários receberão a exceção Authorization_RequestDenied ao tentarem criar um serviço de bot.

Primeiro, verifique se você é um "Convidado" do diretório:

1. Entre no portal do Azure.
2. Selecione Todos os serviços e procure por ativo.
3. Selecione Microsoft Entra ID.
4. Selecione Usuários.
5. Procure o usuário na lista e certifique-se de que o Tipo de Usuário não seja um Convidado.

Após verificar que você não é um Convidado, em seguida, para garantir que os usuários em um diretório ativo possam criar um serviço de bot, o administrador do diretório precisará definir as configurações a seguir:

1. Inicie sessão no Centro de administração do Microsoft Entra ID. Acesse Usuários e grupos e selecione Configurações de usuário.
2. Na seção Registro do aplicativo, defina Os usuários podem registrar aplicativos para Sim. Isso permite que os usuários no diretório criem o serviço de bot.
3. Na seção Usuários externos, defina Permissões de usuários convidados são limitadas para Não. Isso permite que os usuários convidados no diretório criem o serviço de bot.

Por que não consigo migrar o bot?

Se o bot estiver registrado em dev.botframework.com e você quiser migrá-lo para o Azure, mas estiver com problemas para fazer isso, talvez o bot pertença a um diretório diferente do diretório padrão. Experimente estas etapas:

1. No diretório de destino, adicione um novo usuário (via end. email) que não seja membro do diretório padrão, conceda a função Colaborador do usuário nas assinaturas que são o destino da migração.

2. No Portal do Desenvolvedor, adicione o end. email do usuário como coproprietários do bot que deve ser migrado. Em seguida, saia da seção.

3. Entre no Portal do Desenvolvedor como o novo usuário e prossiga para migrar o bot.

Onde é possível obter mais ajuda?

• Pesquise as perguntas respondidas anteriormente no Stack Overflow ou poste suas próprias perguntas usando a tag botframework. Observe que o Stack Overflow tem diretrizes como a exigência de um título descritivo, uma instrução completa e concisa do problema e detalhes suficientes para reproduzi-lo. Solicitações de recursos ou perguntas muito abrangentes não são tópicos pertinentes; os novos usuários devem visitar o Centro de Ajuda do Stack Overflow para obter mais detalhes.
• Confira os Problemas do BotBuilder no GitHub para obter informações sobre problemas conhecidos com o SDK do Bot Framework ou para relatar um novo problema.
• A discussão na comunidade BotBuilder sobre o Gitter.