Risolvere i problemi dell'emulatore di Azure Cosmos DB

Articolo
11/20/2024

L'emulatore di Azure Cosmos DB fornisce un ambiente che emula il servizio cloud per lo sviluppo. Usare i suggerimenti in questo articolo per risolvere i problemi che potrebbero verificarsi durante l'installazione o l'uso dell'emulatore.

Elenco di controllo per la risoluzione dei problemi

Ecco un elenco dei passaggi comuni per la risoluzione dei problemi da seguire se l'emulatore di Azure Cosmos DB non funziona come previsto.

Reimpostare i dati

Se è stata installata una nuova versione dell'emulatore e si verificano errori, assicurarsi di reimpostare i dati. Per reimpostare i dati, aprire il menu di scelta rapida dell'emulatore di Azure Cosmos DB dall'area di notifica e quindi selezionare Reimposta dati.

Se la reimpostazione dei dati non corregge gli errori, è possibile:

Disinstallare l'emulatore.
Disinstallare le versioni precedenti dell'emulatore (se esistenti).
Rimuovere la %ProgramFiles%\Azure Cosmos DB Emulator cartella.
Reinstallare l'emulatore.

In alternativa, se la reimpostazione dei dati non funziona, passare al %LOCALAPPDATA%\CosmosDBEmulator percorso e quindi eliminare la cartella.

Esaminare i contatori delle prestazioni di Windows danneggiati

Se l'emulatore di Azure Cosmos DB smette di rispondere, raccogliere i file di dump dalla %LOCALAPPDATA%\CrashDumps cartella, comprimere i file e quindi aprire un ticket di supporto nella portale di Azure.
Se Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe smette di rispondere, questo arresto anomalo potrebbe indicare che i contatori delle prestazioni sono danneggiati. Per controllare lo stato del contatore, eseguire il comando seguente:
```
lodctr /R
```

Diagnosticare i problemi di connettività

Se si verifica un problema di connettività, raccogliere i file di traccia, comprimere i file e quindi aprire un ticket di supporto nella portale di Azure.
Se viene visualizzato un messaggio "Servizio non disponibile", l'emulatore potrebbe non inizializzare lo stack di rete. Verificare se è installato Pulse Secure Client o Juniper Networks Client perché i driver di filtro di rete potrebbero causare il problema. È anche possibile provare a disinstallare altri driver di filtro di rete per risolvere il problema. In alternativa, avviare l'emulatore usando /DisableRIO per passare la comunicazione di rete dell'emulatore al normale Winsock.
Se viene visualizzato un messaggio di errore di connettività, ad "Forbidden", "message":"Request is being made with a forbidden encryption in transit protocol or cipher. Check account SSL/TLS minimum allowed protocol setting..."esempio , questo messaggio di errore potrebbe indicare modifiche globali nel sistema operativo (ad esempio Insider Preview Build 20170) o modifiche nelle impostazioni del browser che abilitano TLS 1.3 come protocollo predefinito. Messaggio di errore simile, ad esempio "Microsoft.Azure.Documents.DocumentClientException: la richiesta viene eseguita con una crittografia non consentita nel protocollo di transito o nella crittografia. Controllare l'impostazione minima del protocollo consentito ssl/TLS dell'account" se si usa l'SDK per eseguire una richiesta nell'emulatore di Azure Cosmos DB. Questo errore può verificarsi anche perché l'emulatore di Azure Cosmos DB supporta solo il protocollo TLS 1.2. La soluzione alternativa consigliata consiste nell'impostare TLS 1.2 come predefinito.

Ad esempio:
1. In Gestione IIS passare a Siti> Web predefiniti.
2. Individuare le associazioni sito per la porta 8081 e modificarle per disabilitare TLS 1.3. È anche possibile aggiornare le impostazioni per il Web browser usando l'opzione Impostazioni .
  
  Note
  
  Se il computer entra in modalità sospensione o esegue aggiornamenti del sistema operativo durante l'esecuzione dell'emulatore, potrebbe essere visualizzato un messaggio di errore "Il servizio non è attualmente disponibile".
3. Per reimpostare i dati dell'emulatore, fare clic con il pulsante destro del mouse sull'icona visualizzata nell'area di notifica di Windows e quindi scegliere Reimposta dati.

Raccogliere i file di traccia

Per raccogliere tracce di debug, eseguire i comandi seguenti come amministratore in una finestra del prompt dei comandi:

Passare al percorso in cui è installato l'emulatore:
```
cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"
```
Arrestare l'emulatore e controllare la barra delle applicazioni per assicurarsi che il programma venga arrestato:
```
Microsoft.Azure.Cosmos.Emulator.exe /shutdown
```
Note

Il completamento del processo potrebbe richiedere un minuto. È anche possibile selezionare Esci nell'interfaccia utente dell'emulatore di Azure Cosmos DB.
Avviare la registrazione eseguendo il comando seguente:
```
Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces
```
Avviare l'emulatore:
```
Microsoft.Azure.Cosmos.Emulator.exe
```
Riprodurre il problema. Se Esplora dati non funziona, è necessario attendere solo pochi secondi prima che il browser venga caricato per poter rilevare l'errore.

Arrestare la registrazione:

Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces

Passare al %ProgramFiles%\Azure Cosmos DB Emulator percorso e individuare il file docdbemulator_000001.etl .
Aprire un ticket di supporto nella portale di Azure e includere il file con estensione etl insieme a tutti i passaggi necessari per riprodurre il problema.

Installare i certificati per le applicazioni client

In alcuni casi, potrebbe essere necessario accettare il certificato dell'emulatore esportato e usarlo con un'applicazione client. Il processo esatto varia in base all'SDK.

Esportare il certificato TLS/SLL

Esportare il certificato dell'emulatore per usare correttamente l'endpoint dell'emulatore da linguaggi e ambienti di runtime che non si integrano con l'archivio certificati di Windows. È possibile esportare il certificato usando Gestione certificati Windows o PowerShell dopo aver eseguito l'emulatore per la prima volta.

Recuperare il certificato usando il nome DocumentDbEmulatorCertificate descrittivo e archiviare il certificato in una variabile della shell denominata $cert.
```
$cert = Get-ChildItem Cert:\LocalMachine\My | where{$_.FriendlyName -eq 'DocumentDbEmulatorCertificate'}
```
Usare Export-Certificate per esportare il certificato in un file temporaneo nella home cartella.
```
$params = @{
    Cert = $cert
    Type = "CERT"
    FilePath = "$home/tmp-cert.cer"
    NoClobber = $true
}
Export-Certificate @params
```
Note

In Windows, la home folder è in C:\Users\[username]\genere , presupponendo che l'unità principale sia C:.
Usare certutil per convertire il certificato in un file di certificato X.509 con codifica Base 64.
```
certutil -encode $home/tmp-cert.cer $home/cosmosdbcert.cer
```
Rimuovere il file temporaneo.
```
Remove-Item $home/tmp-cert.cer
```

Importare il certificato per le applicazioni Java

Quando si eseguono applicazioni Java o applicazioni MongoDB che usano un client basato su Java, l'installazione del certificato nell'archivio certificati predefinito Java è più semplice rispetto al passaggio dei -Djavax.net.ssl.trustStore=<keystore> -Djavax.net.ssl.trustStorePassword="<password>" parametri. Ad esempio, l'applicazione demo Java inclusa (https://localhost:8081/_explorer/index.html) dipende dall'archivio certificati predefinito.

Seguire le istruzioni in Creazione, esportazione e importazione di certificati TLS/SSL per importare il certificato X.509 nell'archivio certificati Java predefinito. Tenere presente che si sta lavorando nella directory %JAVA_HOME% durante l'esecuzione di keytool. Dopo l'importazione del certificato nell'archivio certificati, i client per SQL e l'API di Azure Cosmos DB per MongoDB possono connettersi all'emulatore di Azure Cosmos DB.

In alternativa, è possibile eseguire lo script seguente bash per importare il certificato:

#!/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

Dopo aver installato il CosmosDBEmulatorCertificate certificato TLS/SSL, l'applicazione deve essere in grado di connettersi e usare l'emulatore locale di Azure Cosmos DB.

In caso di problemi, vedere Debug di connessioni SSL/TLS. Nella maggior parte dei casi, il certificato potrebbe non essere installato nell'archivio %JAVA_HOME%/jre/lib/security/cacerts. Ad esempio, se è installata più di una versione di Java, l'applicazione potrebbe usare un archivio certificati diverso da quello aggiornato.

Importare il certificato per le applicazioni Python

Quando ci si connette all'emulatore dalle applicazioni Python, la verifica TLS è disabilitata. Per impostazione predefinita, l’SDK Python per Azure Cosmos DB for NoSQL non tenta di usare il certificato TLS/SSL quando si connette all'emulatore locale. Per altre informazioni, vedere Libreria client di Azure Cosmos DB for NoSQL per Python.

Per usare la convalida TLS, seguire gli esempi nel wrapper TLS/SSL per gli oggetti socket.

Importare il certificato per le applicazioni Node.js

Quando ci si connette all'emulatore dagli SDK Node.js, la verifica TLS è disabilitata. Per impostazione predefinita, l'SDK di Node.js (versione 1.10.1 o successiva) per l'API per NoSQL non tenta di usare il certificato TLS/SSL quando si connette all'emulatore locale.

Se si vuole usare la convalida TLS, seguire gli esempi nella documentazione di Node.js.

Ruotare i certificati

È possibile forzare la rigenerazione dei certificati dell'emulatore aprendo l'emulatore con l'argomento /ResetDataPath . Questa azione cancella tutti i dati archiviati localmente dall'emulatore. Per altre informazioni sugli argomenti della riga di comando, vedere Argomenti della riga di comando dell'emulatore di Windows.

Suggerimento

In alternativa, selezionare Reimposta dati dal menu di scelta rapida dell'emulatore di Azure Cosmos DB nell'area di notifica di Windows.

Se i certificati sono stati installati nell'archivio certificati Java o usati altrove, è necessario reimportarli usando i certificati correnti. L'applicazione non può connettersi all'emulatore locale finché non si aggiornano i certificati.

Condividi tramite