Problembehandlung beim Azure Cosmos DB-Emulator

Artikel
11/20/2024

Der Azure Cosmos DB-Emulator stellt eine Umgebung bereit, die den Clouddienst für die Entwicklung emuliert. Verwenden Sie die Tipps in diesem Artikel, um Probleme zu beheben, die beim Installieren oder Verwenden des Emulators auftreten können.

Checkliste zur Problembehandlung

Nachfolgend finden Sie eine Liste allgemeiner Schritte zur Problembehandlung, die sie ausführen müssen, wenn der Azure Cosmos DB-Emulator nicht wie erwartet funktioniert.

Zurücksetzen von Daten

Wenn Sie eine neue Version des Emulators installiert haben und Fehler auftreten, stellen Sie sicher, dass Sie die Daten zurücksetzen. Um die Daten zurückzusetzen, öffnen Sie das Kontextmenü des Azure Cosmos DB-Emulators über die Taskleiste, und wählen Sie dann "Daten zurücksetzen" aus.

Wenn das Zurücksetzen der Daten die Fehler nicht behebt, können Sie:

Deinstallieren Sie den Emulator.
Deinstallieren Sie ältere Versionen des Emulators (sofern vorhanden).
Entfernen Sie den %ProgramFiles%\Azure Cosmos DB Emulator Ordner.
Installieren Sie den Emulator erneut.

Wenn das Zurücksetzen der Daten nicht funktioniert, wechseln Sie zum %LOCALAPPDATA%\CosmosDBEmulator Speicherort, und löschen Sie dann den Ordner.

Überprüfen beschädigter Windows-Leistungsindikatoren

Wenn der Azure Cosmos DB-Emulator nicht mehr reagiert, sammeln Sie die Speicherabbilddateien aus dem %LOCALAPPDATA%\CrashDumps Ordner, komprimieren Sie die Dateien, und öffnen Sie dann ein Supportticket im Azure-Portal.
Wenn Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe der Absturz nicht mehr reagiert, kann dieser Absturz darauf hinweisen, dass die Leistungsindikatoren beschädigt sind. Führen Sie den folgenden Befehl aus, um den Leistungsindikatorstatus zu überprüfen:
```
lodctr /R
```

Diagnostizieren von Konnektivitätsproblemen

Wenn ein Verbindungsproblem auftritt, sammeln Sie Ablaufverfolgungsdateien, komprimieren Sie die Dateien, und öffnen Sie dann ein Supportticket im Azure-Portal.
Wenn Sie eine Meldung "Dienst nicht verfügbar" erhalten, initialisiert der Emulator möglicherweise nicht den Netzwerkstapel. Überprüfen Sie, ob der Pulse Secure Client oder der Juniper Networks-Client installiert ist, da die Netzwerkfiltertreiber möglicherweise das Problem verursachen. Sie können auch versuchen, andere Netzwerkfiltertreiber zu deinstallieren, um das Problem zu beheben. Alternativ können Sie den Emulator starten /DisableRIO , indem Sie die Emulatornetzwerkkommunikation in reguläre Winsock umstellen.
Wenn Sie eine Fehlermeldung zur Konnektivität erhalten, z "Forbidden", "message":"Request is being made with a forbidden encryption in transit protocol or cipher. Check account SSL/TLS minimum allowed protocol setting...". B. diese Fehlermeldung, kann auf globale Änderungen im Betriebssystem (z. B. Insider Preview Build 20170) oder Änderungen in den Browsereinstellungen hinweisen, die TLS 1.3 als Standardprotokoll aktivieren. Eine ähnliche Fehlermeldung, z. B. "Microsoft.Azure.Documents.DocumentClientException: Anforderung wird mit einer verbotenen Verschlüsselung im Transitprotokoll oder Verschlüsselung vorgenommen. Überprüfen Sie die Ssl/TLS-Mindestprotokolleinstellung des Kontos" wird möglicherweise generiert, wenn Sie das SDK verwenden, um eine Anforderung für den Azure Cosmos DB-Emulator auszuführen. Dieser Fehler kann auch auftreten, da der Azure Cosmos DB-Emulator nur das TLS 1.2-Protokoll unterstützt. Die empfohlene Problemumgehung besteht darin, TLS 1.2 als Standard festzulegen.

Zum Beispiel:
1. Wechseln Sie im IIS-Manager zu "Websites>standardwebsites".
2. Suchen Sie die Websitebindungen für Port 8081, und bearbeiten Sie sie, um TLS 1.3 zu deaktivieren. Sie können die Einstellungen für den Webbrowser auch mithilfe der Option "Einstellungen" aktualisieren.
  
  Notiz
  
  Wenn Ihr Computer in den Energiesparmodus wechselt oder Betriebssystemupdates ausführt, während der Emulator ausgeführt wird, wird möglicherweise eine Fehlermeldung "Dienst ist zurzeit nicht verfügbar" angezeigt.
3. Um die Emulatordaten zurückzusetzen, klicken Sie mit der rechten Maustaste auf das Symbol, das in der Windows-Benachrichtigungsleiste angezeigt wird, und wählen Sie dann "Daten zurücksetzen" aus.

Sammeln von Ablaufverfolgungsdateien

Führen Sie zum Sammeln von Debugablaufverfolgungen die folgenden Befehle als Administrator in einem Eingabeaufforderungsfenster aus:

Navigieren Sie zu dem Pfad, in dem der Emulator installiert ist:
```
cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"
```
Beenden Sie den Emulator, und beobachten Sie die Taskleiste, um sicherzustellen, dass das Programm heruntergefahren wird:
```
Microsoft.Azure.Cosmos.Emulator.exe /shutdown
```
Notiz

Es kann eine Minute dauern, bis der Vorgang abgeschlossen ist. Sie können auch "Beenden" auf der Benutzeroberfläche des Azure Cosmos DB-Emulators auswählen.
Beginnen Sie mit der Protokollierung, indem Sie den folgenden Befehl ausführen:
```
Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces
```
Starten Sie den Emulator:
```
Microsoft.Azure.Cosmos.Emulator.exe
```
Reproduzieren Sie das Problem. Wenn der Daten-Explorer nicht funktioniert, müssen Sie nur einige Sekunden warten, bis der Browser geladen wird, um den Fehler erkennen zu können.

Protokollierung beenden:

Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces

Navigieren Sie zum %ProgramFiles%\Azure Cosmos DB Emulator Pfad, und suchen Sie die Datei docdbemulator_000001.etl .
Öffnen Sie ein Supportticket in der Azure-Portal, und schließen Sie die ETL-Datei zusammen mit allen Schritten ein, die zum Reproduzieren des Problems erforderlich sind.

Installieren von Zertifikaten für Clientanwendungen

Gelegentlich müssen Sie möglicherweise das exportierte Emulatorzertifikat verwenden und es mit einer Clientanwendung verwenden. Der genaue Prozess variiert je nach SDK.

Exportieren des TLS/SLL-Zertifikats

Exportieren Sie das Emulatorzertifikat, um den Emulatorendpunkt erfolgreich aus Sprachen und Laufzeitumgebungen zu verwenden, die nicht in den Windows-Zertifikatspeicher integriert sind. Sie können das Zertifikat mithilfe des Windows-Zertifikat-Managers oder powerShell exportieren, nachdem Sie den Emulator zum ersten Mal ausgeführt haben.

Rufen Sie das Zertifikat mithilfe des Anzeigenamens DocumentDbEmulatorCertificate ab, und speichern Sie das Zertifikat in einer Shellvariable namens $cert.
```
$cert = Get-ChildItem Cert:\LocalMachine\My | where{$_.FriendlyName -eq 'DocumentDbEmulatorCertificate'}
```
Verwenden Sie "Exportzertifikat ", um das Zertifikat in eine temporäre Datei in Ihrem Startordner zu exportieren.
```
$params = @{
    Cert = $cert
    Type = "CERT"
    FilePath = "$home/tmp-cert.cer"
    NoClobber = $true
}
Export-Certificate @params
```
Notiz

In Windows ist der Startordner in der Regel C:\Users\[username]\, vorausgesetzt, Ihr Heimlaufwerk ist C:.
Verwenden Sie certutil , um das Zertifikat in eine Base-64-codierte X.509-Zertifikatdatei zu konvertieren.
```
certutil -encode $home/tmp-cert.cer $home/cosmosdbcert.cer
```
Entfernen Sie die temporäre Datei.
```
Remove-Item $home/tmp-cert.cer
```

Importieren eines Zertifikats für Java-Anwendungen

Wenn Sie Java-Anwendungen oder MongoDB-Anwendungen ausführen, die einen Java-basierten Client verwenden, ist die Installation des Zertifikats im Java-Standardzertifikatspeicher einfacher als das Übergeben der -Djavax.net.ssl.trustStore=<keystore> -Djavax.net.ssl.trustStorePassword="<password>" Parameter. Die enthaltene Java-Demoanwendung (https://localhost:8081/_explorer/index.html) ist beispielsweise vom Standardzertifikatspeicher abhängig.

Befolgen Sie die Anweisungen zum Erstellen, Exportieren und Importieren von TLS/SSL-Zertifikaten , um das X.509-Zertifikat in den Standard-Java-Zertifikatspeicher zu importieren. Denken Sie daran, dass Sie beim Ausführen von Keytool im Verzeichnis %JAVA_HOME% arbeiten. Nachdem das Zertifikat in den Zertifikatspeicher importiert wurde, können Clients für die SQL- und Azure Cosmos DB-API für MongoDB eine Verbindung mit dem Azure Cosmos DB-Emulator herstellen.

Alternativ können Sie das folgende bash Skript ausführen, um das Zertifikat zu importieren:

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

Nachdem das CosmosDBEmulatorCertificate TLS/SSL-Zertifikat installiert wurde, sollte Ihre Anwendung in der Lage sein, eine Verbindung mit dem lokalen Azure Cosmos DB-Emulator herzustellen und zu verwenden.

Wenn Probleme auftreten, lesen Sie den Artikel Debuggen von SSL/TLS-Verbindungen. In den meisten Fällen wird das Zertifikat möglicherweise nicht im Speicher %JAVA_HOME%/jre/lib/security/cacerts installiert. Wenn beispielsweise mehr als eine installierte Version von Java vorhanden ist, verwendet Ihre Anwendung möglicherweise einen Zertifikatspeicher, der sich von der aktualisierten Version unterscheidet.

Importieren eines Zertifikats für Python-Anwendungen

Wenn Sie eine Verbindung mit dem Emulator aus Python-Anwendungen herstellen, ist die TLS-Überprüfung deaktiviert. Das Python SDK für Azure Cosmos DB for NoSQL versucht beim Herstellen einer Verbindung mit dem lokalen Emulator standardmäßig nicht, das TLS/SSL-Zertifikat zu verwenden. Weitere Informationen finden Sie unter Azure Cosmos DB for NoSQL-Clientbibliothek für Python.

Wenn Sie die TLS-Überprüfung verwenden möchten, folgen Sie den Beispielen in TLS/SSL-Wrapper für Socketobjekte.

Importieren eines Zertifikats für Node.js Anwendungen

Wenn Sie eine Verbindung mit dem Emulator in Node.js SDKs herstellen, ist die TLS-Überprüfung deaktiviert. Standardmäßig versucht das Node.js SDK (Version 1.10.1 oder höher) für die API für NoSQL nicht, das TLS/SSL-Zertifikat zu verwenden, wenn es eine Verbindung mit dem lokalen Emulator herstellt.

Wenn Sie die TLS-Validierung verwenden möchten, befolgen Sie die Beispiele in der Node.js-Dokumentation.

Rotieren von Zertifikaten

Sie können die Regeneration der Emulatorzertifikate erzwingen, indem Sie den Emulator mit dem /ResetDataPath Argument öffnen. Mit dieser Aktion werden alle lokal vom Emulator gespeicherten Daten gelöscht. Weitere Informationen zu Befehlszeilenargumenten finden Sie unter Befehlszeilenargumente des Windows-Emulators.

Tipp

Alternativ können Sie "Daten zurücksetzen" im Kontextmenü des Azure Cosmos DB-Emulators in der Windows-Taskleiste auswählen.

Wenn Sie die Zertifikate im Java-Zertifikatspeicher installiert oder an anderer Stelle verwendet haben, müssen Sie sie mit den aktuellen Zertifikaten erneut importieren. Die Anwendung kann erst dann eine Verbindung mit dem lokalen Emulator herstellen, wenn Sie die Zertifikate aktualisiert haben.

Freigeben über