Teste e depure com o emulador
APLICA-SE A: SDK v4
Bot Framework Emulator é um aplicativo de desktop que permite aos desenvolvedores de bots testar e depurar bots, local ou remotamente. Usando o emulador, você pode conversar com seu bot e inspecionar as mensagens que seu bot envia e recebe. O emulador exibe as mensagens como elas apareceriam em uma interface do usuário de bate-papo da Web e registra solicitações e respostas JSON enquanto você troca mensagens com seu bot. Antes de implantar seu bot na nuvem, execute-o localmente e teste-o usando o emulador. Você pode testar seu bot usando o Emulador, mesmo que ainda não o tenha criado com o Serviço de Bot do Azure AI ou configurado para ser executado em qualquer canal.
Nota
Os SDKs JavaScript, C# e Python do Bot Framework continuarão a ser suportados, no entanto, o Java SDK está sendo desativado com suporte final de longo prazo terminando em novembro de 2023. Apenas segurança crítica e correções de bugs dentro deste repositório serão realizadas.
Os bots existentes construídos com o Java SDK continuarão a funcionar.
Para a criação de novos bots, considere usar o Power Virtual Agents e leia sobre como escolher a solução de chatbot certa.
Para obter mais informações, consulte O futuro da criação de bots.
Pré-requisitos
- Instalar Bot Framework Emulator
Executar um bot localmente
Antes de conectar seu bot ao Bot Framework Emulator, você precisa executar seu bot localmente. Você pode usar o Visual Studio ou o Visual Studio Code para executar seu bot ou usar a linha de comando. Para executar um bot usando a linha de comando, faça o seguinte:
Vá para o prompt de comando e altere o diretório para o diretório do projeto do bot.
Inicie o bot executando o seguinte comando:
dotnet runCopie o número da porta na linha antes de o aplicativo ser iniciado. Pressione CTRL+C para desligar.
Neste ponto, seu bot deve estar sendo executado localmente.
Conectar-se a um bot em execução no localhost
Definir configurações de proxy
Quando você estiver desenvolvendo atrás de um proxy corporativo, o emulador usará as variáveis HTTP_PROXY de ambiente configuradas e , que especificam a rota de URL do proxy para solicitações HTTP e HTTPS_PROXYHTTPs, respectivamente.
Se você estiver se conectando a um bot em execução no localhost, o emulador primeiro tentará rotear através do proxy antes de se conectar ao localhost. Normalmente, o proxy bloqueará a conexão, a menos que você especifique que ela deve ser ignorada para localhost.
Para ignorar as HTTP_PROXY configurações e e HTTPS_PROXY permitir que o emulador se conecte ao localhost, em sua máquina local, você deve definir a seguinte variável de ambiente:
NO_PROXY=localhost
Configurar o emulador para autenticação
Se um bot requer autenticação, exibindo uma caixa de diálogo de login, você deve configurar o emulador como mostrado abaixo.
Utilizar um código de verificação de início de sessão
- Inicie o emulador.
- No emulador, selecione Configurações (o ícone de engrenagem) no painel esquerdo.
- Habilite Bypass ngrok para endereços locais.
- Habilite Usar um código de verificação de entrada para OAuthCards.
- Selecione Guardar.
Quando você seleciona o botão de login exibido pelo bot, um código de validação será gerado. Você inserirá o código na caixa de chat de entrada do bot para que a autenticação ocorra. Depois disso, você pode executar as operações permitidas.
Como alternativa, você pode executar as etapas descritas abaixo.
Usando tokens de autenticação
- Inicie o emulador.
- No emulador, selecione Configurações (o ícone de engrenagem) no painel esquerdo.
- Digite o caminho local para ngrok. Para obter mais informações sobre ngrok, consulte ngrok.
- Habilite Executar ngrok quando o emulador for iniciado.
- Habilite Usar tokens de autenticação da versão 1.0.
- Selecione Guardar.
Ao selecionar o botão de login exibido pelo bot, você será solicitado a inserir suas credenciais. Um token de autenticação é gerado. Depois disso, você pode executar as operações permitidas.
Para se conectar a um bot em execução localmente, selecione Abrir bot. Adicione o número da porta copiado anteriormente no seguinte URL e cole o URL atualizado na barra de URL do Bot:
http://localhost:<port number>/api/messages
Se o bot estiver sendo executado com credenciais da Conta da Microsoft (MSA), insira essas credenciais também.
Usar credenciais de bot
Ao abrir o bot, defina a ID do Aplicativo Microsoft e a senha do Aplicativo Microsoft se o bot estiver sendo executado com credenciais. Se você criou seu bot com o Serviço de Bot do Azure AI, as credenciais estarão disponíveis no Serviço de Aplicativo do bot, na seção Configurações -> Configuração . Se você não souber os valores, poderá removê-los do arquivo de configuração do bot em execução local e, em seguida, executar o bot no emulador. Se o bot não estiver sendo executado com essas configurações, você também não precisará executar o emulador com as configurações.
Ao criar um aplicativo de provedor de identidade do AD, lembre-se do seguinte:
- Quando o tipo de conta suportada é definido como locatário único, se você usar uma assinatura pessoal em vez de uma conta da Microsoft, o emulador emitirá o erro: A ID do aplicativo Microsoft ou a senha do aplicativo Microsoft do bot está incorreta.
- Nesse caso, os tipos de conta suportados devem ser definidos como Contas em qualquer diretório organizacional (Qualquer diretório ID do Microsoft Entra - Multilocatário) e contas pessoais da Microsoft (por exemplo, Xbox).
Para obter mais informações, consulte Criar um aplicativo de provedor de identidade do Microsoft Entra ID e Registrar um novo aplicativo usando o portal do Azure.
Exibir atividades detalhadas de mensagens com o inspetor
Envie uma mensagem ao bot. O bot deverá responder. Pode selecionar o balão da mensagem na janela da conversa e inspecionar a atividade JSOM não processada com a funcionalidade INSPETOR do lado direito da janela. Quando selecionado, o balão da mensagem ficará amarelo e o objeto JSON da atividade será apresentado à esquerda da janela de conversa. As informações JSON incluem metadados da chave, incluindo o ID do canal, o tipo de atividade, o ID da conversa, a mensagem de texto, o URL do ponto final e assim sucessivamente. Você pode inspecionar as atividades enviadas pelo usuário e as atividades com as quais o bot responde.
Gorjeta
Você pode depurar alterações de estado em um bot conectado a um canal adicionando o Middleware de Inspeção ao bot.
Inspecionar serviços
Nota
O Azure AI QnA Maker será desativado em 31 de março de 2025. A partir de 1º de outubro de 2022, você não poderá criar novos recursos ou bases de conhecimento do QnA Maker. Uma versão mais recente do recurso de perguntas e respostas agora está disponível como parte da Linguagem de IA do Azure.
A resposta a perguntas personalizadas, um recurso do Azure AI Language, é a versão atualizada do serviço QnA Maker. Para obter mais informações sobre o suporte a perguntas e respostas no SDK do Bot Framework, consulte Compreensão de linguagem natural.
Nota
O Language Understanding (LUIS) será aposentado em 1 de outubro de 2025. A partir de 1 de abril de 2023, não será possível criar novos recursos LUIS. Uma versão mais recente do entendimento de idiomas agora está disponível como parte do Azure AI Language.
O entendimento de linguagem conversacional (CLU), um recurso do Azure AI Language, é a versão atualizada do LUIS. Para obter mais informações sobre o suporte à compreensão de linguagem no SDK do Bot Framework, consulte Compreensão de linguagem natural.
Com o emulador, você também pode inspecionar as respostas JSON do LUIS e do QnA Maker. Ao utilizar um bot com um serviço de linguagem ligado, pode selecionar rastreio na janela do REGISTO na parte inferior direita. Esta nova ferramenta também fornece recursos para atualizar seus serviços de idioma diretamente do emulador.
Com um serviço LUIS conectado, o link de rastreamento especifica Luis Trace. Quando selecionada, a resposta bruta do seu serviço LUIS é exibida, o que inclui intenções e entidades, juntamente com suas pontuações especificadas. Você pode reatribuir intenções para suas declarações de usuário.
Com um serviço QnA Maker conectado, o log exibirá o QnA Trace. Quando selecionado, você pode visualizar o par de perguntas e respostas associado a essa atividade, juntamente com uma pontuação de confiança. A partir daqui, pode adicionar formulações alternativas de perguntas para uma resposta.
Iniciar sessão no Azure
Você pode usar o emulador para entrar em sua conta do Azure. Isso é útil para você adicionar e gerenciar serviços dos quais seu bot depende. Para iniciar sessão:
Selecione Arquivo e entre com o Azure.
No ecrã de boas-vindas , selecione Iniciar sessão com a sua conta do Azure. Opcionalmente, você pode fazer com que o emulador mantenha você conectado nas reinicializações do aplicativo do emulador.
Desativando a coleta de dados
Se você decidir que não deseja mais permitir que o emulador colete dados de uso, poderá desabilitar facilmente a coleta de dados seguindo estas etapas:
No emulador, selecione Configurações (o ícone de engrenagem) no painel esquerdo.
Em Coleta de dados, desmarque Ajudar a melhorar o emulador, permitindo-nos coletar dados de uso.
Selecione Guardar.
Se mudar de ideias, pode reativar a recolha de dados mais tarde.
Recursos adicionais
O Bot Framework Emulator é de código aberto. Você pode contribuir para o desenvolvimento e enviar bugs e sugestões.
Para solucionar problemas, consulte solucionar problemas gerais e os outros artigos de solução de problemas nessa seção.
Próximo passo
Use middleware de inspeção para depurar um bot conectado a um canal.