Problemen met de Azure Cosmos DB-emulator oplossen

Artikel
11/20/2024

De Azure Cosmos DB-emulator biedt een omgeving die de cloudservice emuleren voor ontwikkeling. Gebruik de tips in dit artikel om problemen op te lossen die u mogelijk ondervindt bij het installeren of gebruiken van de emulator.

Controlelijst voor probleemoplossing

Hier volgt een lijst met veelvoorkomende stappen voor probleemoplossing als de Azure Cosmos DB-emulator niet werkt zoals verwacht.

Gegevens opnieuw instellen

Als u een nieuwe versie van de emulator hebt geïnstalleerd en er fouten optreden, moet u ervoor zorgen dat u de gegevens opnieuw instelt. Als u de gegevens opnieuw wilt instellen, opent u het contextmenu van de Azure Cosmos DB-emulator in het systeemvak en selecteert u Vervolgens Gegevens opnieuw instellen.

Als het opnieuw instellen van de gegevens de fouten niet oplost, kunt u het volgende doen:

Verwijder de emulator.
Verwijder oudere versies van de emulator (indien aanwezig).
Verwijder de %ProgramFiles%\Azure Cosmos DB Emulator map.
Installeer de emulator opnieuw.

Als het opnieuw instellen van de gegevens niet werkt, gaat u naar de %LOCALAPPDATA%\CosmosDBEmulator locatie en verwijdert u de map.

Beschadigde Windows-prestatiemeteritems controleren

Als de Azure Cosmos DB-emulator niet meer reageert, verzamelt u de dumpbestanden uit de %LOCALAPPDATA%\CrashDumps map, comprimeert u de bestanden en opent u vervolgens een ondersteuningsticket in Azure Portal.
Als Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe deze crash niet meer reageert, kan dit erop wijzen dat de prestatiemeteritems beschadigd zijn. Voer de volgende opdracht uit om de tellerstatus te controleren:
```
lodctr /R
```

Connectiviteitsproblemen vaststellen

Als u een verbindingsprobleem ondervindt, verzamelt u traceringsbestanden, comprimeert u de bestanden en opent u vervolgens een ondersteuningsticket in Azure Portal.
Als u een bericht 'Service niet beschikbaar' ontvangt, initialiseert de emulator mogelijk niet de netwerkstack. Controleer of de Pulse Secure-client of Juniper Networks-client is geïnstalleerd omdat de netwerkfilterstuurprogramma's mogelijk het probleem veroorzaken. U kunt ook andere netwerkfilterstuurprogramma's verwijderen om het probleem op te lossen. U kunt de emulator ook starten door /DisableRIO de netwerkcommunicatie van de emulator over te schakelen naar reguliere Winsock.
Als u een verbindingsfout ontvangt, bijvoorbeeld "Forbidden", "message":"Request is being made with a forbidden encryption in transit protocol or cipher. Check account SSL/TLS minimum allowed protocol setting...", kan dit foutbericht duiden op algemene wijzigingen in het besturingssysteem (bijvoorbeeld Insider Preview Build 20170) of wijzigingen in de browserinstellingen die TLS 1.3 inschakelen als het standaardprotocol. Een vergelijkbaar foutbericht, zoals 'Microsoft.Azure.Documents.DocumentClientException: Aanvraag wordt gedaan met een verboden versleuteling in transitprotocol of codering. Controleer de minimaal toegestane protocolinstelling voor account SSL/TLS' kan worden gegenereerd als u de SDK gebruikt om een aanvraag uit te voeren op de Azure Cosmos DB-emulator. Deze fout kan ook optreden omdat de Azure Cosmos DB-emulator alleen het TLS 1.2-protocol ondersteunt. De aanbevolen tijdelijke oplossing is om TLS 1.2 als standaard in te stellen.

Bijvoorbeeld:
1. Ga in IIS-beheer naar Standaardwebsites>voor sites.
2. Zoek de sitebindingen voor poort 8081 en bewerk ze om TLS 1.3 uit te schakelen. U kunt de instellingen voor de webbrowser ook bijwerken met behulp van de optie Instellingen .
  
  Notitie
  
  Als uw computer in de slaapstand komt of updates van het besturingssysteem uitvoert terwijl de emulator wordt uitgevoerd, ziet u mogelijk het foutbericht 'Service is momenteel niet beschikbaar'.
3. Als u de emulatorgegevens opnieuw wilt instellen, klikt u met de rechtermuisknop op het pictogram dat wordt weergegeven in het Systeemvak van Windows en selecteert u Gegevens opnieuw instellen.

Traceringsbestanden verzamelen

Als u foutopsporingstraceringen wilt verzamelen, voert u de volgende opdrachten uit als beheerder in een opdrachtpromptvenster:

Navigeer naar het pad waarin de emulator is geïnstalleerd:
```
cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"
```
Sluit de emulator af en bekijk het systeemvak om ervoor te zorgen dat het programma wordt afgesloten:
```
Microsoft.Azure.Cosmos.Emulator.exe /shutdown
```
Notitie

Het kan één minuut duren voordat het proces is voltooid. U kunt ook Afsluiten selecteren in de gebruikersinterface van de Azure Cosmos DB-emulator.
Begin met logboekregistratie door de volgende opdracht uit te voeren:
```
Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces
```
Start de emulator:
```
Microsoft.Azure.Cosmos.Emulator.exe
```
Reproduceer het probleem. Als data explorer niet werkt, moet u slechts een paar seconden wachten totdat de browser is geladen om de fout te kunnen detecteren.

Logboekregistratie stoppen:

Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces

Navigeer naar het %ProgramFiles%\Azure Cosmos DB Emulator pad en zoek het bestand docdbemulator_000001.etl .
Open een ondersteuningsticket in Azure Portal en neem het ETL-bestand op samen met de stappen die nodig zijn om het probleem te reproduceren.

Certificaten installeren voor clienttoepassingen

Soms moet u het geëxporteerde emulatorcertificaat gebruiken met een clienttoepassing. Het exacte proces verschilt per SDK.

TLS/SLL-certificaat exporteren

Exporteer het emulatorcertificaat om het emulatoreindpunt te gebruiken vanuit talen en runtime-omgevingen die niet zijn geïntegreerd met het Windows-certificaatarchief. U kunt het certificaat exporteren met Windows Certificate Manager of PowerShell nadat u de emulator voor het eerst hebt uitgevoerd.

Haal het certificaat op met behulp van de beschrijvende naam DocumentDbEmulatorCertificate en sla het certificaat op in een shellvariabele met de naam $cert.
```
$cert = Get-ChildItem Cert:\LocalMachine\My | where{$_.FriendlyName -eq 'DocumentDbEmulatorCertificate'}
```
Gebruik Export-Certificate om het certificaat te exporteren naar een tijdelijk bestand in uw basismap.
```
$params = @{
    Cert = $cert
    Type = "CERT"
    FilePath = "$home/tmp-cert.cer"
    NoClobber = $true
}
Export-Certificate @params
```
Notitie

In Windows is de basismap meestal C:\Users\[username]\, ervan uitgaande dat uw thuisstation is C:.
Gebruik certutil om het certificaat te converteren naar een met Base-64 gecodeerd X.509-certificaatbestand .
```
certutil -encode $home/tmp-cert.cer $home/cosmosdbcert.cer
```
Verwijder het tijdelijke bestand.
```
Remove-Item $home/tmp-cert.cer
```

Certificaat importeren voor Java-toepassingen

Wanneer u Java-toepassingen of MongoDB-toepassingen uitvoert die gebruikmaken van een Java-client, is het installeren van het certificaat in het standaardcertificaatarchief van Java eenvoudiger dan het doorgeven van de -Djavax.net.ssl.trustStore=<keystore> -Djavax.net.ssl.trustStorePassword="<password>" parameters. De opgenomen Java Demo-toepassing (https://localhost:8081/_explorer/index.html) is bijvoorbeeld afhankelijk van het standaardcertificaatarchief.

Volg de instructies in TLS/SSL-certificaten maken, exporteren en importeren om het X.509-certificaat te importeren in het standaard Java-certificaatarchief. Houd er rekening mee dat u in de map %JAVA_HOME% werkt wanneer u keytool uitvoert. Nadat het certificaat is geïmporteerd in het certificaatarchief, kunnen clients voor DE API van SQL en Azure Cosmos DB voor MongoDB verbinding maken met de Azure Cosmos DB-emulator.

U kunt ook het volgende bash script uitvoeren om het certificaat te importeren:

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

Zodra het CosmosDBEmulatorCertificate TLS/SSL-certificaat is geïnstalleerd, moet uw toepassing verbinding kunnen maken met en de lokale Azure Cosmos DB-emulator kunnen gebruiken.

Als u problemen ondervindt, raadpleegt u Debugging SSL/TLS-verbindingen. In de meeste gevallen is het certificaat mogelijk niet geïnstalleerd in het archief %JAVA_HOME%/jre/lib/security/cacerts . Als er bijvoorbeeld meer dan één geïnstalleerde versie van Java is, gebruikt uw toepassing mogelijk een ander certificaatarchief dan het certificaatarchief dat u hebt bijgewerkt.

Certificaat importeren voor Python-toepassingen

Wanneer u vanuit Python-toepassingen verbinding maakt met de emulator, wordt TLS-verificatie uitgeschakeld. Standaard probeert de Python SDK voor Azure Cosmos DB for NoSQL het TLS/SSL-certificaat niet te gebruiken wanneer het verbinding maakt met de lokale emulator. Zie de Azure Cosmos DB for NoSQL-clientbibliotheek voor Python voor meer informatie.

Als u TLS-validatie wilt gebruiken, volgt u de voorbeelden in TLS/SSL-wrapper voor socketobjecten.

Certificaat importeren voor Node.js-toepassingen

Wanneer u vanuit Node.js SDK's verbinding maakt met de emulator, wordt TLS-verificatie uitgeschakeld. Standaard probeert de Node.js SDK (versie 1.10.1 of hoger) voor de API voor NoSQL het TLS/SSL-certificaat niet te gebruiken wanneer het verbinding maakt met de lokale emulator.

Als u TLS-validatie wilt gebruiken, volgt u de voorbeelden in de Node.js documentatie.

Certificaten roteren

U kunt het genereren van de emulatorcertificaten afdwingen door de emulator te openen met het /ResetDataPath argument. Met deze actie worden alle gegevens die lokaal zijn opgeslagen door de emulator gewist. Zie opdrachtregelargumenten in Windows Emulator voor meer informatie over opdrachtregelargumenten.

Tip

U kunt ook Reset Data selecteren in het contextmenu van de Azure Cosmos DB-emulator in het Systeemvak van Windows.

Als u de certificaten in het Java-certificaatarchief hebt geïnstalleerd of elders hebt gebruikt, moet u ze opnieuw importeren met behulp van de huidige certificaten. Uw toepassing kan pas verbinding maken met de lokale emulator als u de certificaten bijwerkt.

Delen via