Solucionar problemas do emulador do Azure Cosmos DB

Artigo
11/20/2024

O emulador do Azure Cosmos DB fornece um ambiente que emula o serviço de nuvem para desenvolvimento. Use as dicas deste artigo para ajudar a solucionar problemas que você pode enfrentar ao instalar ou usar o emulador.

Lista de verificação de solução de problemas

Aqui está uma lista de etapas comuns de solução de problemas a serem seguidas se o emulador do Azure Cosmos DB não estiver funcionando conforme o esperado.

Redefinir dados

Se você instalou uma nova versão do emulador e está enfrentando erros, certifique-se de redefinir os dados. Para redefinir os dados, abra o menu de contexto do emulador do Azure Cosmos DB na bandeja do sistema e selecione Redefinir Dados.

Se a redefinição dos dados não corrigir os erros, você pode:

Desinstale o emulador.
Desinstale versões mais antigas do emulador (se existirem).
Remova a %ProgramFiles%\Azure Cosmos DB Emulator pasta.
Reinstale o emulador.

Como alternativa, se a redefinição dos dados não funcionar, vá para o %LOCALAPPDATA%\CosmosDBEmulator local e exclua a pasta.

Examinar contadores de desempenho corrompidos do Windows

Se o emulador do Azure Cosmos DB parar de responder, colete os arquivos de despejo %LOCALAPPDATA%\CrashDumps da pasta, compacte os arquivos e abra um tíquete de suporte no portal do Azure.
Se Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe parar de responder, essa falha poderá indicar que os contadores de desempenho estão corrompidos. Para verificar o status do contador, execute o seguinte comando:
```
lodctr /R
```

Diagnosticar problemas de conectividade

Se você tiver um problema de conectividade, colete arquivos de rastreamento, compacte os arquivos e abra um tíquete de suporte no portal do Azure.
Se você receber uma mensagem "Serviço indisponível", talvez o emulador não esteja inicializando a pilha de rede. Verifique se você tem o Pulse Secure Client ou o Juniper Networks Client instalados, pois seus drivers de filtro de rede podem estar causando o problema. Você também pode tentar desinstalar outros drivers de filtro de rede para corrigir o problema. Como alternativa, inicie o emulador usando /DisableRIO para alternar a comunicação de rede do emulador para o Winsock regular.
Se você receber uma mensagem de erro de conectividade, como "Forbidden", "message":"Request is being made with a forbidden encryption in transit protocol or cipher. Check account SSL/TLS minimum allowed protocol setting...", essa mensagem de erro poderá indicar alterações globais no sistema operacional (por exemplo, Insider Preview Build 20170) ou alterações nas configurações do navegador que habilitam o TLS 1.3 como o protocolo padrão. Uma mensagem de erro semelhante, como "Microsoft.Azure.Documents.DocumentClientException: a solicitação está sendo feita com uma criptografia proibida no protocolo de trânsito ou criptografia. Verificar a configuração de protocolo mínimo permitido SSL/TLS da conta" poderá ser gerada se você usar o SDK para executar uma solicitação no emulador do Azure Cosmos DB. Esse erro também pode ocorrer porque o emulador do Azure Cosmos DB dá suporte apenas ao protocolo TLS 1.2. A solução alternativa recomendada é definir o TLS 1.2 como padrão.

Por exemplo:
1. No Gerenciador do IIS, vá para Sites>Sites Padrão.
2. Localize as Associações de Site para a porta 8081 e edite-as para desabilitar o TLS 1.3. Você também pode atualizar as configurações do navegador da Web usando a opção Configurações .
  
  Observação
  
  Se o computador entrar no modo de suspensão ou executar atualizações do sistema operacional enquanto o emulador estiver em execução, você poderá ver uma mensagem de erro "O serviço não está disponível no momento".
3. Para redefinir os dados do emulador, clique com o botão direito do mouse no ícone que aparece na bandeja de notificação do Windows e selecione Redefinir Dados.

Coletar arquivos de rastreamento

Para coletar rastreamentos de depuração, execute os seguintes comandos como administrador em uma janela do Prompt de Comando:

Navegue até o caminho no qual o emulador está instalado:
```
cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"
```
Desligue o emulador e observe a bandeja do sistema para garantir que o programa seja desligado:
```
Microsoft.Azure.Cosmos.Emulator.exe /shutdown
```
Observação

Pode levar um minuto para que o processo seja concluído. Você também pode selecionar Sair na interface do usuário do emulador do Azure Cosmos DB.

Inicie o registro executando o seguinte comando:

Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces

Inicie o emulador:
```
Microsoft.Azure.Cosmos.Emulator.exe
```
Reproduza o problema. Se o explorador de dados não estiver funcionando, você terá que esperar apenas alguns segundos para que o navegador seja carregado para poder detectar o erro.

Parar o registro:

Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces

Navegue até o %ProgramFiles%\Azure Cosmos DB Emulator caminho e localize o arquivo docdbemulator_000001.etl .
Abra um tíquete de suporte no portal do Azure e inclua o arquivo .etl junto com as etapas necessárias para reproduzir o problema.

Instalar certificados para aplicativos cliente

Ocasionalmente, talvez seja necessário pegar o certificado do emulador exportado e usá-lo com um aplicativo cliente. O processo exato varia de acordo com o SDK.

Exportar certificado TLS/SLL

Exporte o certificado do emulador para usar com êxito o ponto de extremidade do emulador de linguagens e ambientes de runtime que não se integram ao Repositório de Certificados do Windows. Você pode exportar o certificado usando o Gerenciador de Certificados do Windows ou o PowerShell depois de executar o emulador pela primeira vez.

Recupere o certificado usando o nome DocumentDbEmulatorCertificate amigável e armazene-o em uma variável de shell chamada $cert.
```
$cert = Get-ChildItem Cert:\LocalMachine\My | where{$_.FriendlyName -eq 'DocumentDbEmulatorCertificate'}
```
Use Export-Certificate para exportar o certificado para um arquivo temporário em sua pasta pessoal.
```
$params = @{
    Cert = $cert
    Type = "CERT"
    FilePath = "$home/tmp-cert.cer"
    NoClobber = $true
}
Export-Certificate @params
```
Observação

No Windows, a pasta pessoal normalmente C:\Users\[username]\é , supondo que sua unidade pessoal seja C:.
Use certutil para converter o certificado em um arquivo de certificado X.509 codificado em Base 64.
```
certutil -encode $home/tmp-cert.cer $home/cosmosdbcert.cer
```
Remova o arquivo temporário.
```
Remove-Item $home/tmp-cert.cer
```

Importar certificado para aplicativos Java

Quando você executa aplicativos Java ou aplicativos MongoDB que usam um cliente baseado em Java, instalar o certificado no armazenamento de certificados padrão Java é mais fácil do que passar os -Djavax.net.ssl.trustStore=<keystore> -Djavax.net.ssl.trustStorePassword="<password>" parâmetros. Por exemplo, o aplicativo de demonstração Java (https://localhost:8081/_explorer/index.html) depende do repositório de certificados padrão.

Siga as instruções em Criando, exportando e importando certificados TLS/SSL para importar o certificado X.509 para o armazenamento de certificados Java padrão. Lembre-se de que você está trabalhando no diretório %JAVA_HOME% ao executar o keytool. Depois que o certificado é importado para o repositório de certificados, os clientes do SQL e da API do Azure Cosmos DB para MongoDB podem se conectar ao emulador do Azure Cosmos DB.

Como alternativa, você pode executar o seguinte bash script para importar o certificado:

#!/bin/bash

# If the emulator was started with /AllowNetworkAccess, replace the following with the actual IP address of it:
EMULATOR_HOST=localhost
EMULATOR_PORT=8081
EMULATOR_CERT_PATH=/tmp/cosmos_emulator.cert
openssl s_client -connect ${EMULATOR_HOST}:${EMULATOR_PORT} </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > $EMULATOR_CERT_PATH
# Delete the cert if it already exists
sudo $JAVA_HOME/bin/keytool -cacerts -delete -alias cosmos_emulator
# Import the cert
sudo $JAVA_HOME/bin/keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH

Depois que o CosmosDBEmulatorCertificate certificado TLS/SSL for instalado, seu aplicativo deverá ser capaz de se conectar e usar o emulador local do Azure Cosmos DB.

Se você tiver problemas, confira Depurando conexões SSL/TLS. Na maioria dos casos, pode ocorrer de o certificado não estar instalado no repositório %JAVA_HOME%/jre/lib/security/cacerts. Por exemplo, se houver mais de uma versão instalada do Java, seu aplicativo poderá estar usando um repositório de certificados diferente daquele que você atualizou.

Importar certificado para aplicativos Python

Quando você se conecta ao emulador de aplicativos Python, a verificação de TLS é desativada. Por padrão, o SDK do Python para Azure Cosmos DB for NoSQL não tenta usar o certificado TLS/SSL quando se conecta ao emulador local. Para obter mais informações, confira Biblioteca de clientes do Azure Cosmos DB for NoSQL para Python.

Se você quiser usar a validação TLS, siga os exemplos em Wrapper TLS/SSL para objetos de soquete.

Certificado de importação para Node.js aplicações

Ao se conectar ao emulador a partir dos SDKs do Node.js, a verificação TLS é desabilitada. Por padrão, o SDK do Node.js (versão 1.10.1 ou posterior) para a API para NoSQL não tenta usar o certificado TLS/SSL quando se conecta ao emulador local.

Se você quiser usar a validação de SSL, siga os exemplos na Documentação do Node.js.

Girar certificados

Você pode forçar a regeneração dos certificados do emulador abrindo o emulador com o /ResetDataPath argumento. Essa ação apaga todos os dados armazenados localmente pelo emulador. Para obter mais informações sobre argumentos de linha de comando, consulte Argumentos de linha de comando do emulador do Windows.

Dica

Como alternativa, selecione Redefinir Dados no menu de contexto do emulador do Azure Cosmos DB na bandeja do sistema do Windows.

Se você instalou os certificados no armazenamento de certificados Java ou os usou em outro lugar, deverá reimportá-los usando os certificados atuais. O seu aplicativo não poderá se conectar ao emulador local até que você atualize os certificados.

Compartilhar via