Rozwiązywanie problemów z emulatorem usługi Azure Cosmos DB

Artykuł
04/13/2024

Emulator usługi Azure Cosmos DB zapewnia środowisko emulujące usługę w chmurze na potrzeby programowania. Skorzystaj z porad w tym artykule, aby pomóc w rozwiązywaniu problemów, które mogą wystąpić podczas instalowania lub korzystania z emulatora.

Lista kontrolna rozwiązywania problemów

Poniżej przedstawiono listę typowych kroków rozwiązywania problemów, które należy wykonać, jeśli emulator usługi Azure Cosmos DB nie działa zgodnie z oczekiwaniami.

Resetowanie danych

Jeśli zainstalowano nową wersję emulatora i występują błędy, upewnij się, że dane zostały zresetowane. Aby zresetować dane, otwórz menu kontekstowe emulatora usługi Azure Cosmos DB z zasobnika systemu, a następnie wybierz pozycję Resetuj dane.

Jeśli zresetowanie danych nie naprawi błędów, możesz wykonać następujące czynności:

Odinstaluj emulator.
Odinstaluj starsze wersje emulatora (jeśli istnieją).
%ProgramFiles%\Azure Cosmos DB Emulator Usuń folder.
Zainstaluj ponownie emulator.

Jeśli zresetowanie danych nie zadziała, przejdź do %LOCALAPPDATA%\CosmosDBEmulator lokalizacji, a następnie usuń folder.

Przeglądanie uszkodzonych liczników wydajności systemu Windows

Jeśli emulator usługi Azure Cosmos DB przestanie odpowiadać, zbierz pliki zrzutu z folderu%LOCALAPPDATA%\CrashDumps, skompresuj pliki, a następnie otwórz bilet pomocy technicznej w Azure Portal.
Jeśli Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe przestanie odpowiadać, ta awaria może wskazywać, że liczniki wydajności są uszkodzone. Aby sprawdzić stan licznika, uruchom następujące polecenie:
```
lodctr /R
```

Diagnozowanie problemów z łącznością

Jeśli wystąpi problem z łącznością, zbierz pliki śledzenia, skompresuj pliki, a następnie otwórz bilet pomocy technicznej w Azure Portal.
Jeśli zostanie wyświetlony komunikat "Usługa niedostępna", emulator może nie inicjować stosu sieciowego. Sprawdź, czy masz zainstalowanego klienta Pulse Secure Client lub Juniper Networks, ponieważ przyczyną problemu mogą być sterowniki filtrów sieciowych. Możesz również spróbować odinstalować inne sterowniki filtrów sieciowych, aby rozwiązać ten problem. Alternatywnie uruchom emulator przy użyciu /DisableRIO przełącznika komunikacji sieciowej emulatora na zwykły winsock.
Jeśli zostanie wyświetlony komunikat o błędzie łączności, taki jak "Forbidden", "message":"Request is being made with a forbidden encryption in transit protocol or cipher. Check account SSL/TLS minimum allowed protocol setting...", ten komunikat o błędzie może wskazywać globalne zmiany w systemie operacyjnym (na przykład kompilację insider preview 20170) lub zmiany w ustawieniach przeglądarki, które włączają protokół TLS 1.3 jako protokół domyślny. Podobny komunikat o błędzie, taki jak "Microsoft.Azure.Documents.DocumentClientException: Żądanie jest wykonywane przy użyciu zabronionego szyfrowania w protokole tranzytowym lub szyfrze. Sprawdź, czy ustawienie protokołu SSL/TLS konta jest minimalne" może zostać wygenerowane, jeśli używasz zestawu SDK do uruchamiania żądania względem emulatora usługi Azure Cosmos DB. Ten błąd może również wystąpić, ponieważ emulator usługi Azure Cosmos DB obsługuje tylko protokół TLS 1.2. Zalecanym obejściem jest ustawienie domyślnego protokołu TLS 1.2.

Przykład:
1. W Menedżerze usług IIS przejdź do pozycji Witryny domyślne>witryny sieci Web.
2. Znajdź powiązania lokacji dla portu 8081 i edytuj je, aby wyłączyć protokół TLS 1.3. Ustawienia przeglądarki internetowej można również zaktualizować przy użyciu opcji Ustawienia .
  
  Uwaga
  
  Jeśli komputer przechodzi w tryb uśpienia lub uruchamia aktualizacje systemu operacyjnego podczas działania emulatora, może zostać wyświetlony komunikat o błędzie "Usługa jest obecnie niedostępna".
3. Aby zresetować dane emulatora, kliknij prawym przyciskiem myszy ikonę wyświetlaną na pasku powiadomień systemu Windows, a następnie wybierz pozycję Resetuj dane.

Zbieranie plików śledzenia

Aby zebrać ślady debugowania, uruchom następujące polecenia jako administrator w oknie wiersza polecenia:

Przejdź do ścieżki, w której zainstalowano emulator:
```
cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"
```
Zamknij emulator i watch zasobnika systemowego, aby upewnić się, że program został zamknięty:
```
Microsoft.Azure.Cosmos.Emulator.exe /shutdown
```
Uwaga

Ukończenie procesu może potrwać minutę. Możesz również wybrać pozycję Zakończ w interfejsie użytkownika emulatora usługi Azure Cosmos DB.
Rozpocznij rejestrowanie, uruchamiając następujące polecenie:
```
Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces
```
Uruchom emulator:
```
Microsoft.Azure.Cosmos.Emulator.exe
```
Odtwórz problem. Jeśli eksplorator danych nie działa, musisz poczekać tylko kilka sekund, aż przeglądarka załaduje się, aby móc wykryć błąd.

Zatrzymaj rejestrowanie:

Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces

Przejdź do ścieżki %ProgramFiles%\Azure Cosmos DB Emulator i znajdź plik docdbemulator_000001.etl .
Otwórz bilet pomocy technicznej w Azure Portal i dołącz plik .etl wraz z wszelkimi krokami wymaganymi do odtworzenia problemu.

Instalowanie certyfikatów dla aplikacji klienckich

Czasami może być konieczne pobranie wyeksportowanego certyfikatu emulatora i użycie go z aplikacją kliencką. Dokładny proces zależy od zestawu SDK.

Eksportowanie certyfikatu TLS/SLL

Wyeksportuj certyfikat emulatora, aby pomyślnie używać punktu końcowego emulatora z języków i środowisk uruchomieniowych, które nie są integrowane z Magazynem certyfikatów systemu Windows. Certyfikat można wyeksportować przy użyciu Menedżera certyfikatów systemu Windows lub programu PowerShell po pierwszym uruchomieniu emulatora.

Pobierz certyfikat przy użyciu przyjaznej nazwy DocumentDbEmulatorCertificate i zapisz certyfikat w zmiennej powłoki o nazwie $cert.
```
$cert = Get-ChildItem Cert:\LocalMachine\My | where{$_.FriendlyName -eq 'DocumentDbEmulatorCertificate'}
```
Użyj polecenia Export-Certificate , aby wyeksportować certyfikat do pliku tymczasowego w folderze macierzystym.
```
$params = @{
    Cert = $cert
    Type = "CERT"
    FilePath = "$home/tmp-cert.cer"
    NoClobber = $true
}
Export-Certificate @params
```
Uwaga

W systemie Windows folder macierzysty jest zazwyczaj , przy założeniu, że dysk domowy C:\Users\[username]\to C:.
Użyj narzędzia certutil , aby przekonwertować certyfikat na plik certyfikatu X.509 zakodowany w formacie Base-64 .
```
certutil -encode $home/tmp-cert.cer $home/cosmosdbcert.cer
```
Usuń plik tymczasowy.
```
Remove-Item $home/tmp-cert.cer
```

Importowanie certyfikatu dla aplikacji Java

W przypadku uruchamiania aplikacji Java lub aplikacji bazy danych MongoDB korzystających z klienta opartego na języku -Djavax.net.ssl.trustStore=<keystore> -Djavax.net.ssl.trustStorePassword="<password>" Java instalowanie certyfikatu w domyślnym magazynie certyfikatów Języka Java jest łatwiejsze niż przekazywanie parametrów. Na przykład dołączona aplikacja demonstracyjna Java (https://localhost:8081/_explorer/index.html) zależy od domyślnego magazynu certyfikatów.

Postępuj zgodnie z instrukcjami w temacie Tworzenie, eksportowanie i importowanie certyfikatów TLS/SSL , aby zaimportować certyfikat X.509 do domyślnego magazynu certyfikatów Java. Pamiętaj, że pracujesz w katalogu %JAVA_HOME% podczas uruchamiania narzędzia keytool. Po zaimportowaniu certyfikatu do magazynu certyfikatów klienci interfejsu API sql i usługi Azure Cosmos DB dla bazy danych MongoDB mogą łączyć się z emulatorem usługi Azure Cosmos DB.

Alternatywnie możesz uruchomić następujący bash skrypt, aby zaimportować certyfikat:

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

Po zainstalowaniu certyfikatu CosmosDBEmulatorCertificate TLS/SSL aplikacja powinna mieć możliwość nawiązywania połączenia z lokalnym emulatorem usługi Azure Cosmos DB i korzystania z niego.

Jeśli masz jakiekolwiek problemy, zobacz Debugowanie połączeń SSL/TLS. W większości przypadków certyfikat może nie być zainstalowany w magazynie %JAVA_HOME%/jre/lib/security/cacerts . Jeśli na przykład istnieje więcej niż jedna zainstalowana wersja języka Java, aplikacja może używać magazynu certyfikatów innego niż zaktualizowana.

Importowanie certyfikatu dla aplikacji języka Python

Po nawiązaniu połączenia z emulatorem z aplikacji języka Python weryfikacja protokołu TLS jest wyłączona. Domyślnie zestaw SDK języka Python dla usługi Azure Cosmos DB for NoSQL nie próbuje używać certyfikatu TLS/SSL podczas nawiązywania połączenia z lokalnym emulatorem. Aby uzyskać więcej informacji, zobacz Biblioteka klienta usługi Azure Cosmos DB for NoSQL dla języka Python.

Jeśli chcesz użyć weryfikacji protokołu TLS, postępuj zgodnie z przykładami w otoce TLS/SSL dla obiektów gniazd.

Importowanie certyfikatu dla aplikacji Node.js

Po nawiązaniu połączenia z emulatorem z zestawów Node.js SDK weryfikacja protokołu TLS jest wyłączona. Domyślnie zestawNode.js SDK (w wersji 1.10.1 lub nowszej) dla interfejsu API noSQL nie próbuje używać certyfikatu TLS/SSL podczas nawiązywania połączenia z lokalnym emulatorem.

Jeśli chcesz użyć weryfikacji protokołu TLS, postępuj zgodnie z przykładami w dokumentacjiNode.js.

Obracanie certyfikatów

Możesz wymusić regenerację certyfikatów emulatora, otwierając emulator z argumentem /ResetDataPath . Ta akcja usuwa wszystkie dane przechowywane lokalnie przez emulator. Aby uzyskać więcej informacji na temat argumentów wiersza polecenia, zobacz Argumenty wiersza polecenia emulatora systemu Windows.

Porada

Alternatywnie wybierz pozycję Resetuj dane z menu kontekstowego emulatora usługi Azure Cosmos DB w zasobniku systemu Windows.

Jeśli certyfikaty zostały zainstalowane w magazynie certyfikatów Java lub użyto ich w innym miejscu, należy je ponownie zaimportować przy użyciu bieżących certyfikatów. Aplikacja nie może nawiązać połączenia z lokalnym emulatorem, dopóki nie zaktualizujesz certyfikatów.

Udostępnij za pośrednictwem