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

Artykuł
11/20/2024

Emulator usługi Azure Cosmos DB udostępnia środowisko emulujące usługę w chmurze na potrzeby programowania. Skorzystaj z porad w tym artykule, aby rozwiązać problemy, które mogą wystąpić podczas instalowania lub używania 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 spowoduje usunięcia błędów, możesz:

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

Alternatywnie, jeśli resetowanie danych nie działa, przejdź do %LOCALAPPDATA%\CosmosDBEmulator lokalizacji, a następnie usuń folder.

Przejrzyj uszkodzone liczniki wydajności systemu Windows

Jeśli emulator usługi Azure Cosmos DB przestanie odpowiadać, zbierz pliki zrzutu z %LOCALAPPDATA%\CrashDumps folderu, skompresuj pliki, a następnie otwórz bilet pomocy technicznej w witrynie Azure Portal.
Jeśli Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe awaria przestanie odpowiadać, może to oznaczać, ż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 witrynie Azure Portal.
Jeśli zostanie wyświetlony komunikat "Usługa niedostępna", emulator może nie zainicjować stosu sieciowego. Sprawdź, czy masz zainstalowanego klienta Pulse Secure lub klienta Juniper Networks, ponieważ ich sterowniki filtrów sieciowych mogą powodować problem. Możesz również spróbować odinstalować inne sterowniki filtrów sieciowych, aby rozwiązać ten problem. Możesz też uruchomić emulator przy użyciu polecenia /DisableRIO , aby przełączyć komunikację sieci emulatora na regularną usługę 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ć na globalne zmiany w systemie operacyjnym (na przykład Insider Preview Build 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 z niedozwolonym szyfrowaniem w protokole tranzytowym lub szyfrem. Jeśli używasz zestawu SDK do uruchamiania żądania względem emulatora usługi Azure Cosmos DB, może zostać wygenerowane ustawienie minimalnego dozwolonego protokołu SSL/TLS". 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 protokołu TLS 1.2 jako domyślnego.

Na przykład:
1. W Menedżerze usług IIS przejdź do pozycji Witryny domyślne witryny> sieci Web.
2. Znajdź powiązania witryny dla portu 8081 i edytuj je, aby wyłączyć protokół TLS 1.3. Możesz również zaktualizować ustawienia przeglądarki internetowej przy użyciu opcji Ustawienia .
  
  Uwaga 16.
  
  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 polecenie 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 obejrzyj zasobnik systemu, aby upewnić się, że program został zamknięty:
```
Microsoft.Azure.Cosmos.Emulator.exe /shutdown
```
Uwaga 16.

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, aby przeglądarka mogła 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 witrynie 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 użycie wyeksportowanego certyfikatu emulatora i użycie go z aplikacją kliencką. Dokładny proces różni się w zależności od zestawu SDK.

Eksportowanie certyfikatu TLS/SLL

Wyeksportuj certyfikat emulatora, aby pomyślnie użyć punktu końcowego emulatora z języków i środowisk środowiska uruchomieniowego, które nie są zintegrowane 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 głównym.
```
$params = @{
    Cert = $cert
    Type = "CERT"
    FilePath = "$home/tmp-cert.cer"
    NoClobber = $true
}
Export-Certificate @params
```
Uwaga 16.

W systemie Windows folder główny to zazwyczaj C:\Users\[username]\, przy założeniu, że dysk macierzysny 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 MongoDB korzystających z klienta opartego na języku Java instalowanie certyfikatu w domyślnym magazynie certyfikatów języka Java jest łatwiejsze niż przekazywanie -Djavax.net.ssl.trustStore=<keystore> -Djavax.net.ssl.trustStorePassword="<password>" 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ązania 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 zostać zainstalowany w magazynie %JAVA_HOME%/jre/lib/security/cacerts . Jeśli na przykład jest zainstalowana więcej niż jedna wersja języka Java, aplikacja może używać magazynu certyfikatów innego niż ta, która została 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 SDK Node.js weryfikacja protokołu TLS jest wyłączona. Domyślnie zestaw SDK Node.js (wersja 1.10.1 lub nowsza) dla interfejsu API dla 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 dokumentacji Node.js.

Wymiana certyfikatów

Ponowne uruchomienie certyfikatów emulatora można wymusić, otwierając emulator za pomocą argumentu /ResetDataPath . Ta akcja powoduje wyczyszczenie wszystkich danych przechowywanych lokalnie przez emulator. Aby uzyskać więcej informacji na temat argumentów wiersza polecenia, zobacz Argumenty wiersza polecenia emulatora systemu Windows.

Napiwek

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 były używane w innym miejscu, należy je ponownie zaimportować przy użyciu bieżących certyfikatów. Aplikacja nie może nawiązać połączenia z emulatorem lokalnym, dopóki nie zaktualizujesz certyfikatów.

Udostępnij za pośrednictwem