Problembehandlung für den Azure Cosmos DB-Emulator

Artikel
04/13/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 bei der Installation oder Verwendung des Emulators auftreten können.

Checkliste zur Problembehandlung

Im Folgenden finden Sie eine Liste der allgemeinen Schritte zur Problembehandlung, die Ausgeführt werden müssen, wenn der Azure Cosmos DB-Emulator nicht wie erwartet funktioniert.

Daten zurücksetzen

Wenn Sie eine neue Version des Emulators installiert haben und Fehler auftreten, stellen Sie sicher, dass Sie die Daten zurücksetzen. Öffnen Sie zum Zurücksetzen der Daten das Kontextmenü des Azure Cosmos DB-Emulators in der Taskleiste, und wählen Sie dann Daten zurücksetzen aus.

Wenn durch das Zurücksetzen der Daten die Fehler nicht behoben werden, haben Sie folgende Möglichkeiten:

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 neu.

Wenn das Zurücksetzen der Daten nicht funktioniert, wechseln Sie alternativ 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 Sicherungsdateien aus dem %LOCALAPPDATA%\CrashDumps Ordner, komprimieren Sie die Dateien, und öffnen Sie dann ein Supportticket im Azure-Portal.
Wenn Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe nicht mehr reagiert, kann dieser Absturz darauf hindeuten, dass die Leistungsindikatoren beschädigt sind. Führen Sie den folgenden Befehl aus, um den leistungsindikator status zu überprüfen:
```
lodctr /R
```

Diagnostizieren von Konnektivitätsproblemen

Wenn ein Konnektivitätsproblem auftritt, sammeln Sie Ablaufverfolgungsdateien, komprimieren Sie die Dateien, und öffnen Sie dann ein Supportticket im Azure-Portal.
Wenn Sie die Meldung "Dienst nicht verfügbar" erhalten, initialisiert der Emulator den Netzwerkstapel möglicherweise nicht. Überprüfen Sie, ob der Pulse Secure Client oder Juniper Networks Client installiert ist, da deren Netzwerkfiltertreiber das Problem verursachen könnten. Sie können auch versuchen, andere Netzwerkfiltertreiber zu deinstallieren, um das Problem zu beheben. Alternativ können Sie den Emulator mithilfe /DisableRIO von starten, um die Netzwerkkommunikation des Emulators auf reguläre Winsock umzustellen.
Wenn Sie eine Konnektivitätsfehlermeldung wie "Forbidden", "message":"Request is being made with a forbidden encryption in transit protocol or cipher. Check account SSL/TLS minimum allowed protocol setting..."erhalten, kann diese Fehlermeldung auf globale Änderungen am 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: Die Anforderung wird mit einer unzulässigen Verschlüsselung im Transitprotokoll oder der Verschlüsselung gestellt. Check account SSL/TLS minimum allowed protocol setting" might be generated if you use the SDK to run a request to the Azure Cosmos DB emulator. Dieser Fehler kann auch auftreten, weil 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.
  
  Hinweis
  
  Wenn Ihr Computer in den Energiesparmodus wechselt oder Betriebssystemupdates ausführt, während der Emulator ausgeführt wird, wird möglicherweise die Fehlermeldung "Dienst ist derzeit nicht verfügbar" angezeigt.
3. Klicken Sie zum Zurücksetzen der Emulatordaten 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"
```
Fahren Sie den Emulator herunter, und watch die Taskleiste, um sicherzustellen, dass das Programm heruntergefahren wird:
```
Microsoft.Azure.Cosmos.Emulator.exe /shutdown
```
Hinweis

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.
Starten Sie die 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 wurde, 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 im Azure-Portal, und fügen 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 das exportierte Emulatorzertifikat möglicherweise mit einer Clientanwendung verwenden. Der genaue Prozess variiert je nach SDK.

Exportieren eines 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 mit PowerShell exportieren, nachdem Sie den Emulator zum ersten Mal ausgeführt haben.

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

Unter Windows ist der Basisordner in der Regel C:\Users\[username]\, vorausgesetzt, Ihr Startlaufwerk ist C:.
Verwenden Sie certutil , um das Zertifikat in eine Base64-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. Beispielsweise hängt die enthaltene Java Demo-Anwendung (https://localhost:8081/_explorer/index.html) vom Standardzertifikatspeicher ab.

Befolgen Sie die Anweisungen unter Erstellen, Exportieren und Importieren von TLS/SSL-Zertifikaten , um das X.509-Zertifikat in den Java-Standardzertifikatspeicher 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 SQL und die 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 diesen zu verwenden.

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

Importieren eines Zertifikats für Python-Anwendungen

Wenn Sie über Python-Anwendungen eine Verbindung mit dem Emulator herstellen, ist die TLS-Überprüfung deaktiviert. Standardmäßig versucht das Python SDK für Azure Cosmos DB for NoSQL nicht, das TLS/SSL-Zertifikat zu verwenden, wenn es eine Verbindung mit dem lokalen Emulator herstellt. 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 unter TLS/SSL-Wrapper für Socketobjekte.

Importieren eines Zertifikats für Node.js Anwendungen

Wenn Sie über Node.js SDKs eine Verbindung mit dem Emulator 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 eine Verbindung mit dem lokalen Emulator hergestellt wird.

Wenn Sie die TLS-Überprüfung verwenden möchten, befolgen Sie die Beispiele in der Node.js Dokumentation.

Rotieren von Zertifikaten

Sie können die Generierung der Emulatorzertifikate erzwingen, indem Sie den Emulator mit dem /ResetDataPath Argument öffnen. Durch diese 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 auf 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. Ihre Anwendung kann erst dann eine Verbindung mit dem lokalen Emulator herstellen, wenn Sie die Zertifikate aktualisieren.

Freigeben über