Instalowanie i używanie emulatora usługi Azure Cosmos DB do lokalnego programowania i testowania
DOTYCZY:
Nosql Mongodb Cassandra Gremlin Tabeli
Emulator usługi Azure Cosmos DB zapewnia środowisko lokalne, które emuluje usługę Azure Cosmos DB do celów programistycznych. Za pomocą emulatora usługi Azure Cosmos DB możesz lokalnie opracowywać i testować swoją aplikację bez konieczności tworzenia subskrypcji platformy Azure i ponoszenia kosztów. Jeśli sposób działania aplikacji w emulatorze usługi Azure Cosmos DB jest zadowalający, możesz zacząć korzystać z konta usługi Azure Cosmos DB w chmurze. W tym artykule opisano sposób instalowania i używania emulatora w środowiskach platformy Docker systemu Windows, Linux, macOS i Windows.
Pobieranie emulatora
Aby rozpocząć pracę, pobierz i zainstaluj najnowszą wersję emulatora usługi Azure Cosmos DB na komputerze lokalnym. Artykuł z informacjami o wersji emulatora zawiera listę wszystkich dostępnych wersji i aktualizacji funkcji, które zostały wprowadzone w każdej wersji.
Pobieranie emulatora usługi Azure Cosmos DB
Aplikacje można tworzyć przy użyciu emulatora usługi Azure Cosmos DB z kontem przy użyciu interfejsów API dla noSQL, Apache Cassandra, MongoDB, Apache Gremlin i table. Obecnie eksplorator danych w emulatorze w pełni obsługuje wyświetlanie tylko danych SQL; dane utworzone przy użyciu baz danych MongoDB, Gremlin/Graph i aplikacji klienckich Cassandra nie są obecnie widoczne. Aby dowiedzieć się więcej, zobacz , jak nawiązać połączenie z punktem końcowym emulatora z różnych interfejsów API.
Jak działa emulator?
Emulator usługi Azure Cosmos DB umożliwia dokładną emulację działania usługi Azure Cosmos DB. Obsługuje ona równoważne funkcje jako usługę Azure Cosmos DB, która obejmuje tworzenie danych, wykonywanie zapytań dotyczących danych, aprowizowanie i skalowanie kontenerów oraz wykonywanie procedur składowanych i wyzwalaczy. Aplikacje można opracowywać i testować przy użyciu emulatora usługi Azure Cosmos DB i wdrażać je na platformie Azure na dużą skalę, aktualizując punkt końcowy połączenia usługi Azure Cosmos DB.
Chociaż emulator dokładnie odzwierciedla działanie usługi Azure Cosmos DB, różni się od niej pod względem wdrożenia. Na przykład emulator używa standardowych składników systemu operacyjnego — między innymi lokalnego systemu plików jako magazynu trwałego i stosu protokołu HTTPS na potrzeby łączności. Funkcje, które opierają się na infrastrukturze platformy Azure, takiej jak replikacja globalna, opóźnienie z jedną cyfrą milisekund dla odczytów/zapisów i możliwe do dostosowania poziomów spójności nie mają zastosowania w przypadku korzystania z emulatora.
Różnice między emulatorem a usługą w chmurze
Ponieważ emulator usługi Azure Cosmos DB udostępnia emulowane środowisko działające na lokalnej stacji roboczej dewelopera, istnieją pewne różnice w funkcjonalności między emulatorem a kontem usługi Azure Cosmos DB w chmurze:
Obecnie okienko Data Explorer w emulatorze w pełni obsługuje interfejs API tylko dla klientów NoSQL. Interfejsy API usługi Azure Cosmos DB, takie jak MongoDB, Table, Graph i Cassandra, Data Explorer nie są w pełni obsługiwane w widoku i operacjach dla interfejsów API usługi Azure Cosmos DB.
Emulator obsługuje tylko jedno stałe konto i dobrze znany klucz podstawowy. Nie można ponownie wygenerować klucza podczas korzystania z emulatora usługi Azure Cosmos DB, jednak możesz zmienić klucz domyślny przy użyciu opcji wiersza polecenia .
Za pomocą emulatora można utworzyć konto usługi Azure Cosmos DB tylko w trybie aprowizowanej przepływności ; obecnie nie obsługuje trybu bezserwerowego .
Emulator nie jest skalowalną usługą i nie obsługuje dużej liczby kontenerów. W przypadku korzystania z emulatora usługi Azure Cosmos DB domyślnie można utworzyć maksymalnie 25 kontenerów o stałym rozmiarze na poziomie 400 RU/s (obsługiwanych tylko przy użyciu zestawów SDK usługi Azure Cosmos DB) lub 5 nieograniczonych kontenerów. Aby uzyskać więcej informacji na temat zmiany tej wartości, zobacz Artykuł Set the PartitionCount value (Ustawianie wartości PartitionCount ).
Emulator nie oferuje różnych poziomów spójności usługi Azure Cosmos DB , takich jak usługa w chmurze.
Emulator nie oferuje replikacji w wielu regionach.
Ponieważ kopia emulatora usługi Azure Cosmos DB może nie zawsze być aktualna wraz z najnowszymi zmianami w usłudze Azure Cosmos DB, zawsze należy odwołać się do planisty pojemności usługi Azure Cosmos DB , aby dokładnie oszacować wymagania aplikacji dotyczące przepływności.
Emulator obsługuje maksymalny rozmiar właściwości ID wynoszący 254 znaki.
Instalowanie emulatora
Przed zainstalowaniem emulatora upewnij się, że masz następujące wymagania dotyczące sprzętu i oprogramowania:
Wymagania dotyczące oprogramowania:
- Obecnie obsługiwane są Windows Server 2016 systemu operacyjnego hosta w wersji 2019 lub Windows 10. System operacyjny hosta z włączoną usługą Active Directory nie jest obecnie obsługiwany.
- 64-bitowy system operacyjny
Minimalne wymagania sprzętowe:
- 2 GB pamięci RAM
- 10 GB dostępnego miejsca na dysku twardym
Do zainstalowania, skonfigurowania i uruchomienia emulatora usługi Azure Cosmos DB potrzebne są uprawnienia administratora na komputerze. Emulator doda certyfikat, a także ustawi reguły zapory w celu uruchomienia jego usług. W związku z tym uprawnienia administratora są niezbędne, aby emulator mógł wykonywać takie operacje.
Aby rozpocząć pracę, pobierz i zainstaluj najnowszą wersję emulatora usługi Azure Cosmos DB na komputerze lokalnym. Jeśli podczas instalowania emulatora wystąpią jakiekolwiek problemy, zapoznaj się z artykułem dotyczącym rozwiązywania problemów z emulatorem , aby debugować.
W zależności od wymagań systemowych można uruchomić emulator w systemach Windows, Docker for Windows, Linux lub macOS zgodnie z opisem w następnych sekcjach tego artykułu.
Sprawdzanie aktualizacji emulatora
Każda wersja emulatora zawiera zestaw aktualizacji funkcji lub poprawek błędów. Aby wyświetlić dostępne wersje, przeczytaj artykuł informacje o wersji emulatora .
Po zakończeniu instalacji, jeśli użyto ustawień domyślnych, dane odpowiadające emulatorowi zostaną zapisane w lokalizacji %LOCALAPPDATA%\CosmosDBEmulator. Możesz skonfigurować inną lokalizację przy użyciu opcjonalnych ustawień ścieżki danych; jest to /DataPath=PREFERRED_LOCATIONparametr wiersza polecenia. Dane utworzone w jednej wersji emulatora usługi Azure Cosmos DB nie są gwarantowane w przypadku korzystania z innej wersji. Jeśli musisz zachować dane przez długi czas, zaleca się przechowywanie tych danych na koncie usługi Azure Cosmos DB zamiast emulatora usługi Azure Cosmos DB.
Korzystanie z emulatora w systemie Windows
Emulator usługi Azure Cosmos DB jest instalowany domyślnie w C:\Program Files\Azure Cosmos DB Emulator lokalizacji. Aby uruchomić emulator usługi Azure Cosmos DB w systemie Windows, wybierz przycisk Start lub naciśnij klawisz Windows. Zacznij pisać Emulator usługi Azure Cosmos DB i wybierz emulator z listy aplikacji.
Po uruchomieniu emulatora zobaczysz ikonę w obszarze powiadomień paska zadań systemu Windows. Automatycznie otwiera eksploratora danych usługi Azure Cosmos DB w przeglądarce pod tym adresem URL https://localhost:8081/_explorer/index.html .
Możesz również uruchomić i zatrzymać emulator z wiersza polecenia lub poleceń programu PowerShell. Aby uzyskać więcej informacji, zobacz artykuł referencyjny narzędzia wiersza polecenia .
Emulator usługi Azure Cosmos DB domyślnie jest uruchamiany na komputerze lokalnym („localhost”) i nasłuchuje na porcie 8081. Adres jest wyświetlany jako https://localhost:8081/_explorer/index.html. Możesz zamknąć eksploratora. Jeśli zechcesz otworzyć go ponownie później, możesz otworzyć ten adres URL w przeglądarce lub uruchomić eksploratora za pomocą ikony emulatora usługi Azure Cosmos DB wyświetlanej w obszarze powiadomień systemu Windows.
Korzystanie z emulatora w systemie Linux lub macOS
Obecnie emulator usługi Azure Cosmos DB można uruchomić tylko w systemie Windows. Jeśli używasz systemu Linux lub macOS, zalecamy użycie emulatora systemu Linux (wersja zapoznawcza) lub uruchomienie emulatora na maszynie wirtualnej z systemem Windows hostowanej w funkcji hypervisor, takiej jak Parallels lub VirtualBox.
Uwaga
Za każdym razem, gdy ponownie uruchomisz maszynę wirtualną z systemem Windows hostowaną w funkcji hypervisor, musisz ponownie zaimportować certyfikat, ponieważ adres IP maszyny wirtualnej ulegnie zmianie. Importowanie certyfikatu nie jest wymagane w przypadku skonfigurowania maszyny wirtualnej w celu zachowania adresu IP.
Wykonaj następujące kroki, aby użyć emulatora w środowiskach systemu Linux lub macOS:
Uruchom następujące polecenie z maszyny wirtualnej z systemem Windows i zanotuj adres IPv4:
ipconfig.exeW aplikacji zmień adres URL punktu końcowego, aby użyć adresu IPv4 zwróconego przez
ipconfig.exezamiastlocalhost.Na maszynie wirtualnej z systemem Windows uruchom emulator usługi Azure Cosmos DB z poziomu wiersza polecenia, korzystając z poniższych opcji. Aby uzyskać szczegółowe informacje na temat parametrów obsługiwanych przez wiersz polecenia, zobacz dokumentację narzędzia wiersza polecenia emulatora:
Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==Na koniec należy rozpoznać proces zaufania certyfikatu między aplikacją działającą w środowisku Linux lub Mac i emulatorem. Aby rozwiązać ten certyfikat, możesz użyć jednej z następujących dwóch opcji:
Opcja 1. Importowanie certyfikatu TLS/SSL emulatora
W poniższych sekcjach pokazano, jak zaimportować certyfikat TLS/SSL emulatora do środowisk linux i macOS.
Środowisko systemu Linux
Jeśli pracujesz w systemie Linux, platforma .NET korzysta z biblioteki OpenSSL, aby przeprowadzić walidację:
Wyeksportuj certyfikat w formacie PFX. Opcja PFX jest dostępna podczas wybierania eksportu klucza prywatnego.
Skopiuj ten plik PFX do środowiska systemu Linux.
Konwertowanie pliku PFX na plik CRT
openssl pkcs12 -in YourPFX.pfx -clcerts -nokeys -out YourCTR.crtSkopiuj plik CRT do folderu zawierającego certyfikaty niestandardowe w dystrybucji systemu Linux. Często w dystrybucjach Debian znajduje się on w lokalizacji
/usr/local/share/ca-certificates/.cp YourCTR.crt /usr/local/share/ca-certificates/Zaktualizuj certyfikaty TLS/SSL, które zaktualizują
/etc/ssl/certs/folder.update-ca-certificates
Środowisko systemu macOS
Jeśli pracujesz na komputerze Mac, wykonaj następujące czynności:
Wyeksportuj certyfikat w formacie PFX. Opcja PFX jest dostępna podczas wybierania eksportu klucza prywatnego.
Skopiuj ten plik PFX do środowiska komputerów Mac.
Otwórz aplikację Keychain Access i zaimportuj plik PFX.
Otwórz listę certyfikatów i zidentyfikuj ten o nazwie
localhost.Otwórz menu kontekstowe dla tego konkretnego elementu, wybierz pozycję Pobierz element , a następnie w obszarze Zaufanie>w przypadku korzystania z tego certyfikatu wybierz pozycję Zawsze ufaj.
Opcja 2. Wyłączanie walidacji PROTOKOŁU SSL w aplikacji
Wyłączenie weryfikacji protokołu SSL jest zalecane tylko w celach programistycznych i nie powinno być wykonywane podczas uruchamiania w środowisku produkcyjnym. W poniższych przykładach pokazano, jak wyłączyć walidację protokołu SSL dla aplikacji platformy .NET i Node.js.
W przypadku dowolnej aplikacji działającej w strukturze zgodnej z platformą .NET Standard 2.1 lub nowszą możemy skorzystać z polecenia CosmosClientOptions.HttpClientFactory:
CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
{
HttpClientFactory = () =>
{
HttpMessageHandler httpMessageHandler = new HttpClientHandler()
{
ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
};
return new HttpClient(httpMessageHandler);
},
ConnectionMode = ConnectionMode.Gateway
};
CosmosClient client = new CosmosClient(endpoint, authKey, cosmosClientOptions);
Włączanie dostępu do emulatora w sieci lokalnej
Jeśli masz wiele maszyn korzystających z jednej sieci, a jeśli skonfigurowano emulator na jednej maszynie i chcesz uzyskać do niej dostęp z innej maszyny. W takim przypadku należy włączyć dostęp do emulatora w sieci lokalnej.
Emulator możesz uruchomić w sieci lokalnej. Aby włączyć dostęp do sieci, określ /AllowNetworkAccess opcję w wierszu polecenia, która również wymaga określenia /Key=key_string lub /KeyFile=file_name. Możesz użyć /GenKeyFile=file_name polecenia , aby wygenerować plik z losowym kluczem z góry. Następnie możesz przekazać je do /KeyFile=file_name lub /Key=contents_of_file.
Aby włączyć dostęp do sieci po raz pierwszy, użytkownik powinien zamknąć emulator i usunąć katalog danych emulatora %LOCALAPPDATA%\CosmosDBEmulator.
Uwierzytelnianie połączeń podczas korzystania z emulatora
Podobnie jak w usłudze Azure Cosmos DB w chmurze, każde żądanie wykonywane względem emulatora usługi Azure Cosmos DB musi zostać uwierzytelnione. Emulator usługi Azure Cosmos DB obsługuje tylko bezpieczną komunikację za pośrednictwem protokołu TLS. Emulator usługi Azure Cosmos DB obsługuje jedno stałe konto i dobrze znany klucz uwierzytelniania na potrzeby uwierzytelniania klucza podstawowego. To konto i klucz są jedynymi poświadczeniami, których można używać z emulatorem usługi Azure Cosmos DB. Są to:
Account name: localhost:<port>
Account key: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
Uwaga
Klucz podstawowy obsługiwany przez emulator usługi Azure Cosmos DB jest przeznaczony tylko do użycia z emulatorem. W emulatorze usługi Azure Cosmos DB nie można korzystać z klucza ani konta usługi Azure Cosmos DB używanych w środowisku produkcyjnym.
Uwaga
Jeśli emulator został uruchomiony z opcją /Key, użyj wygenerowanego klucza zamiast klucza C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==domyślnego . Aby uzyskać więcej informacji na temat opcji /Key, zobacz Dokumentacja narzędzia wiersza polecenia.
Nawiązywanie połączenia z różnymi interfejsami API za pomocą emulatora
Interfejs API dla NoSQL
Po uruchomieniu emulatora usługi Azure Cosmos DB na komputerze możesz z niego korzystać przy użyciu dowolnego obsługiwanego zestawu Azure Cosmos DB SDK lub interfejsu API REST usługi Azure Cosmos DB. Emulator usługi Azure Cosmos DB zawiera również wbudowanego eksploratora danych, który umożliwia tworzenie kontenerów dla interfejsu API dla bazy danych NoSQL lub MongoDB. Za pomocą Eksploratora danych można wyświetlać i edytować elementy bez konieczności pisania kodu.
// Connect to the Azure Cosmos DB Emulator running locally
CosmosClient client = new CosmosClient(
"https://localhost:8081",
"C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==");
Interfejs API dla bazy danych MongoDB
Po uruchomieniu emulatora usługi Azure Cosmos DB na pulpicie możesz użyć interfejsu API usługi Azure Cosmos DB dla bazy danych MongoDB do interakcji z emulatorem. Uruchom emulator z poziomu wiersza polecenia jako administrator z poleceniem "/EnableMongoDbEndpoint". Następnie użyj następujących parametrów połączenia, aby nawiązać połączenie z kontem interfejsu API dla bazy danych MongoDB:
mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true
Interfejs API dla tabeli
Po uruchomieniu emulatora usługi Azure Cosmos DB na pulpicie możesz użyć interfejsu API usługi Azure Cosmos DB dla zestawu TABLE SDK do interakcji z emulatorem. Uruchom emulator z poziomu wiersza polecenia jako administrator z parametrem "/EnableTableEndpoint". Następnie uruchom następujący kod, aby nawiązać połączenie z interfejsem API dla konta tabeli:
using Microsoft.WindowsAzure.Storage;
using Microsoft.WindowsAzure.Storage.Table;
using CloudTable = Microsoft.WindowsAzure.Storage.Table.CloudTable;
using CloudTableClient = Microsoft.WindowsAzure.Storage.Table.CloudTableClient;
string connectionString = "DefaultEndpointsProtocol=http;AccountName=localhost;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;TableEndpoint=http://localhost:8902/;";
CloudStorageAccount account = CloudStorageAccount.Parse(connectionString);
CloudTableClient tableClient = account.CreateCloudTableClient();
CloudTable table = tableClient.GetTableReference("testtable");
table.CreateIfNotExists();
table.Execute(TableOperation.Insert(new DynamicTableEntity("partitionKey", "rowKey")));
Interfejs API dla bazy danych Cassandra
Uruchom emulator z poziomu wiersza polecenia administratora za pomocą polecenia "/EnableCassandraEndpoint". Alternatywnie można również ustawić zmienną środowiskową AZURE_COSMOS_EMULATOR_CASSANDRA_ENDPOINT=true.
Uruchom następujące polecenia w zwykłym oknie wiersza polecenia:
set Path=c:\Python27;%Path% cd /d C:\sdk\apache-cassandra-3.11.3\bin set SSL_VERSION=TLSv1_2 set SSL_VALIDATE=false cqlsh localhost 10350 -u localhost -p C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== --sslW powłoce CQLSH uruchom następujące polecenia, aby nawiązać połączenie z punktem końcowym Cassandra:
CREATE KEYSPACE MyKeySpace WITH replication = {'class':'MyClass', 'replication_factor': 1}; DESCRIBE keyspaces; USE mykeyspace; CREATE table table1(my_id int PRIMARY KEY, my_name text, my_desc text); INSERT into table1 (my_id, my_name, my_desc) values( 1, 'name1', 'description 1'); SELECT * from table1; EXIT
Interfejs API dla języka Gremlin
Uruchom emulator z poziomu wiersza polecenia administratora za pomocą polecenia /EnableGremlinEndpoint. Alternatywnie można również ustawić zmienną środowiskową AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=true
Konsola Tinkerpop 3.6.2 jest zgodna z językiem Java 8 lub Java 11. Aby uzyskać więcej informacji, zobacz OpenJDK 11.
Wyodrębnij plik apache-tinkerpop-gremlin-console-3.6.2 do folderu na maszynie.
Uwaga
W pozostałej części tych kroków przyjęto założenie, że konsola została zainstalowana w folderze
%ProgramFiles%\gremlin.W eksploratorze danych emulatora utwórz bazę danych "db1" i kontener "coll1"; dla klucza partycji wybierz pozycję "/name"
Uruchom następujące polecenia w zwykłym oknie wiersza polecenia:
cd /d %ProgramFiles%\apache-tinkerpop-gremlin-console-3.6.0copy /y conf\remote.yaml conf\remote-localcompute.yamlOtwórz plik
conf\remote-localcompute.yamlw programie Notatnik.notepad.exe conf\remote-localcompute.yamlZastąp zawartość pliku YAML tą konfiguracją i zapisz plik.
hosts: [localhost] port: 8901 username: /dbs/db1/colls/coll1 password: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== connectionPool: { enableSsl: false } serializer: { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV1d0, config: { serializeResultToString: true }}Uruchom konsolę gremlin.
bin\gremlin.batW powłoce gremlin uruchom następujące polecenia, aby nawiązać połączenie z punktem końcowym języka Gremlin:
:remote connect tinkerpop.server conf/remote-localcompute.yaml :remote consoleUruchom następujące polecenia, aby wypróbować różne operacje na końcu gremlin:
g.V() g.addV('person1').property(id, '1').property('name', 'somename1') g.addV('person2').property(id, '2').property('name', 'somename2') g.V()
Odinstalowywanie lokalnego emulatora
Aby odinstalować emulator, wykonaj następujące kroki:
Zamknij wszystkie otwarte wystąpienia lokalnego emulatora, klikając prawym przyciskiem myszy ikonę emulatora usługi Azure Cosmos DB na pasku zadań systemu, a następnie wybierz polecenie Zakończ. Zamykanie wszystkich wystąpień może potrwać około minuty.
W polu wyszukiwania systemu Windows wpisz Funkcje aplikacji & i wybierz pozycję Funkcje aplikacji & (ustawienia systemowe).
Na liście aplikacji przewiń do emulatora usługi Azure Cosmos DB, wybierz go, kliknij pozycję Odinstaluj, a następnie potwierdź i ponownie wybierz pozycję Odinstaluj .
Następne kroki
W tym artykule przedstawiono sposób korzystania z lokalnego emulatora do bezpłatnego programowania lokalnego. Teraz możesz przejść do następnych artykułów: