Instalowanie i używanie emulatora Azure Cosmos DB na potrzeby lokalnego tworzenia i testowaniaInstall and use the Azure Cosmos DB Emulator for local development and testing

DOTYCZY: SQL api interfejs API CASSANDRA Gremlin API interfejs API tabel Azure Cosmos DB API dla MongoDB

Emulator usługi Azure Cosmos DB zapewnia środowisko lokalne, które emuluje usługę Azure Cosmos DB do celów programistycznych.The Azure Cosmos DB Emulator provides a local environment that emulates the Azure Cosmos DB service for development purposes. 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.Using the Azure Cosmos DB Emulator, you can develop and test your application locally, without creating an Azure subscription or incurring any costs. Gdy aplikacja działa w emulatorze Azure Cosmos DB, możesz przełączyć się do korzystania z konta usługi Azure Cosmos w chmurze.When you're satisfied with how your application is working in the Azure Cosmos DB Emulator, you can switch to using an Azure Cosmos account in the cloud. W tym artykule opisano sposób instalowania emulatora i korzystania z niego w środowiskach Windows, Linux, macOS i Windows Docker.This article describes how to install and use the emulator on Windows, Linux, macOS, and Windows docker environments.

Pobieranie emulatoraDownload the emulator

Aby rozpocząć, Pobierz i zainstaluj najnowszą wersję emulatora Azure Cosmos DB na komputerze lokalnym.To get started, download and install the latest version of Azure Cosmos DB Emulator on your local computer. W artykule Informacje o wersji emulatora znajduje się lista wszystkich dostępnych wersji i aktualizacji funkcji wprowadzonych w poszczególnych wydaniach.The emulator release notes article lists all the available versions and the feature updates that were made in each release.

Pobieranie emulatora Azure Cosmos DB

Aplikacje można opracowywać przy użyciu emulatora Azure Cosmos DB z kontami interfejsu API SQL, Cassandra, MongoDB, Gremlini Table .You can develop applications using Azure Cosmos DB Emulator with the SQL, Cassandra, MongoDB, Gremlin, and Table API accounts. Obecnie Eksplorator danych w emulatorze w pełni obsługuje wyświetlanie danych SQL. dane utworzone za pomocą MongoDB, Gremlin/Graph i Cassandra aplikacje klienckie nie są w tej chwili widoczne.Currently the data explorer in the emulator fully supports viewing SQL data only; the data created using MongoDB, Gremlin/Graph and Cassandra client applications it is not viewable at this time. Aby dowiedzieć się więcej, zobacz jak nawiązać połączenie z punktem końcowym emulatora z różnych interfejsów API.To learn more, see how to connect to the emulator endpoint from different APIs.

Jak działa emulator?How does the emulator work?

Emulator usługi Azure Cosmos DB umożliwia dokładną emulację działania usługi Azure Cosmos DB.The Azure Cosmos DB Emulator provides a high-fidelity emulation of the Azure Cosmos DB service. Obsługuje ona równoważne funkcje, jak Azure Cosmos DB, które obejmują tworzenie danych, wykonywanie zapytań dotyczących danych, Inicjowanie obsługi i skalowanie kontenerów oraz wykonywanie procedur składowanych i wyzwalaczy.It supports equivalent functionality as the Azure Cosmos DB, which includes creating data, querying data, provisioning and scaling containers, and executing stored procedures and triggers. Możesz tworzyć i testować aplikacje za pomocą emulatora Azure Cosmos DB i wdrażać je na platformie Azure na skalę globalną, aktualizując punkt końcowy połączenia Azure Cosmos DB.You can develop and test applications using the Azure Cosmos DB Emulator, and deploy them to Azure at global scale by updating the Azure Cosmos DB connection endpoint.

Chociaż emulator dokładnie odzwierciedla działanie usługi Azure Cosmos DB, różni się od niej pod względem wdrożenia.While emulation of the Azure Cosmos DB service is faithful, the emulator's implementation is different than the service. 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.For example, the emulator uses standard OS components such as the local file system for persistence, and the HTTPS protocol stack for connectivity. Funkcje, które opierają się na infrastrukturze platformy Azure, takiej jak replikacja globalna, opóźnienie w milisekundach jednocyfrowych dla operacji odczytu/zapisu i możliwość dostosowania poziomy spójności nie są stosowane podczas korzystania z emulatora.Functionality that relies on the Azure infrastructure like global replication, single-digit millisecond latency for reads/writes, and tunable consistency levels are not applicable when you use the emulator.

Dane można migrować między emulatorem Azure Cosmos DB a usługą Azure Cosmos DB przy użyciu Narzędzia do migracji danych Azure Cosmos DB.You can migrate data between the Azure Cosmos DB Emulator and the Azure Cosmos DB service by using the Azure Cosmos DB Data Migration Tool.

Różnice między emulatorem a usługą w chmurzeDifferences between the emulator and the cloud service

Ponieważ emulator Azure Cosmos DB udostępnia emulowane środowisko działające na lokalnej stacji roboczej dewelopera, istnieją pewne różnice w działaniu między emulatorem a kontem usługi Azure Cosmos w chmurze:Because the Azure Cosmos DB Emulator provides an emulated environment that runs on the local developer workstation, there are some differences in functionality between the emulator and an Azure Cosmos account in the cloud:

  • Obecnie okienko Eksplorator danych w emulatorze w pełni obsługuje tylko klientów interfejsu API SQL.Currently the Data Explorer pane in the emulator fully supports SQL API clients only. Widok Eksplorator danych i operacje dotyczące Azure Cosmos DB interfejsów API, takich jak MongoDB, Table, Graph i Cassandra, nie są w pełni obsługiwane.The Data Explorer view and operations for Azure Cosmos DB APIs such as MongoDB, Table, Graph, and Cassandra APIs are not fully supported.

  • Emulator obsługuje tylko jedno stałe konto i dobrze znany klucz podstawowy.The emulator supports only a single fixed account and a well-known primary key. Nie można wygenerować ponownie klucza podczas korzystania z emulatora Azure Cosmos DB, jednak można zmienić klucz domyślny przy użyciu opcji wiersza polecenia .You can't regenerate key when using the Azure Cosmos DB Emulator, however you can change the default key by using the command-line option.

  • Za pomocą emulatora można utworzyć konto usługi Azure Cosmos tylko w trybie przepływności aprowizacji . obecnie nie obsługuje trybu bezserwerowego .With the emulator, you can create an Azure Cosmos account in provisioned throughput mode only; currently it doesn't support serverless mode.

  • Emulator nie jest skalowalną usługą i nie obsługuje dużej liczby kontenerów.The emulator is not a scalable service and it doesn't support a large number of containers. W przypadku korzystania z emulatora Azure Cosmos DB domyślnie można utworzyć maksymalnie 25 kontenerów o stałym rozmiarze o 400 RU/s (obsługiwane tylko przy użyciu zestawów SDK Azure Cosmos DB) lub 5 nieograniczone kontenery.When using the Azure Cosmos DB Emulator, by default, you can create up to 25 fixed size containers at 400 RU/s (only supported using Azure Cosmos DB SDKs), or 5 unlimited containers. Aby uzyskać więcej informacji na temat zmiany tej wartości, zobacz Ustawianie artykułu wartość PartitionCount .For more information on how to change this value, see Set the PartitionCount value article.

  • Emulator nie oferuje różnych Azure Cosmos DB poziomów spójności , takich jak usługa w chmurze.The emulator does not offer different Azure Cosmos DB consistency levels like the cloud service does.

  • Emulator nie oferuje wieloregionowej replikacji.The emulator does not offer multi-region replication.

  • Ponieważ kopia emulatora Azure Cosmos DB może być nieaktualna w stosunku do najnowszych zmian w usłudze Azure Cosmos DB, zawsze należy zapoznać się z terminarzem Azure Cosmos DB wydajności , aby dokładnie oszacować wymagania dotyczące przepływności (jednostek ru) aplikacji.Because the copy of your Azure Cosmos DB Emulator might not always be up to date with the most recent changes in the Azure Cosmos DB service, you should always refer to the Azure Cosmos DB capacity planner to accurately estimate the throughput (RUs) needs of your application.

  • Emulator obsługuje maksymalny rozmiar właściwości identyfikatora wynoszący 254 znaków.The emulator supports a maximum ID property size of 254 characters.

Zainstaluj emulatorInstall the emulator

Przed zainstalowaniem emulatora upewnij się, że masz następujące wymagania dotyczące sprzętu i oprogramowania:Before you install the emulator, make sure you have the following hardware and software requirements:

  • Wymagania dotyczące oprogramowania:Software requirements:

    • Obecnie obsługiwane są system operacyjny Windows Server 2016, 2019 lub Windows 10.Currently Windows Server 2016, 2019 or Windows 10 host OS are supported. System operacyjny hosta z włączonym Active Directory nie jest obecnie obsługiwany.The host OS with Active Directory enabled is currently not supported.
    • 64-bitowy system operacyjny64-bit operating system
  • Minimalne wymagania sprzętowe:Minimum hardware requirements:

    • 2 GB pamięci RAM2-GB RAM
    • 10 GB dostępnego miejsca na dysku twardym10-GB available hard disk space
  • Do zainstalowania, skonfigurowania i uruchomienia emulatora usługi Azure Cosmos DB potrzebne są uprawnienia administratora na komputerze.To install, configure, and run the Azure Cosmos DB Emulator, you must have administrative privileges on the computer. Emulator doda certyfikat, a także ustawi reguły zapory w celu uruchomienia jej usług.The emulator will add a certificate and also set the firewall rules in order to run its services. W związku z tym, aby emulator mógł wykonać takie operacje, wymagane są uprawnienia administratora.Therefore admin rights are necessary for the emulator to be able to execute such operations.

Aby rozpocząć, Pobierz i zainstaluj najnowszą wersję emulatora Azure Cosmos DB na komputerze lokalnym.To get started, download and install the latest version of Azure Cosmos DB Emulator on your local computer. Jeśli podczas instalacji emulatora wystąpią jakiekolwiek problemy, zapoznaj się z artykułem Rozwiązywanie problemów z emulatorem .If you run into any issues when installing the emulator, see the emulator troubleshooting article to debug.

W zależności od wymagań systemowych można uruchomić emulator w systemie Windows, Docker for Windows, Linux lub macOS zgodnie z opisem w następnych sekcjach tego artykułu.Depending upon your system requirements, you can run the emulator on Windows, Docker for Windows, Linux, or macOS as described in next sections of this article.

Sprawdź dostępność aktualizacji emulatoraCheck for emulator updates

Każda wersja emulatora zawiera zestaw aktualizacji funkcji lub poprawek błędów.Each version of emulator comes with a set of feature updates or bug fixes. Aby wyświetlić dostępne wersje, przeczytaj artykuł Informacje o wersji emulatora .To see the available versions, read the emulator release notes article.

Po zakończeniu instalacji, jeśli użyto ustawień domyślnych, dane odpowiadające emulatorowi są zapisywane w lokalizacji%LOCALAPPDATA%\CosmosDBEmulator.After installation, if you have used the default settings, the data corresponding to the emulator is saved at %LOCALAPPDATA%\CosmosDBEmulator location. Można skonfigurować inną lokalizację przy użyciu ustawień opcjonalne ścieżki danych. jest to /DataPath=PREFERRED_LOCATION parametr wiersza polecenia.You can configure a different location by using the optional data path settings; that is the /DataPath=PREFERRED_LOCATION as the command-line parameter. W przypadku korzystania z innej wersji nie ma gwarancji, że dane utworzone w jednej wersji emulatora Azure Cosmos DB są dostępne.The data created in one version of the Azure Cosmos DB Emulator is not guaranteed to be accessible when using a different version. Jeśli chcesz utrzymywać dane przez długi czas, zalecamy przechowywanie tych danych w ramach konta usługi Azure Cosmos, a nie emulatora Azure Cosmos DB.If you need to persist your data for the long term, it is recommended that you store that data in an Azure Cosmos account, instead of the Azure Cosmos DB Emulator.

Korzystanie z emulatora w systemie WindowsUse the emulator on Windows

Emulator Azure Cosmos DB jest instalowany domyślnie w C:\Program Files\Azure Cosmos DB Emulator lokalizacji.The Azure Cosmos DB Emulator is installed at C:\Program Files\Azure Cosmos DB Emulator location by default. Aby uruchomić emulator Azure Cosmos DB w systemie Windows, wybierz przycisk Start lub naciśnij klawisz systemu Windows.To start the Azure Cosmos DB Emulator on Windows, select the Start button or press the Windows key. Zacznij pisać Emulator usługi Azure Cosmos DB i wybierz emulator z listy aplikacji.Begin typing Azure Cosmos DB Emulator, and select the emulator from the list of applications.

Wybierz przycisk Start lub naciśnij klawisz systemu Windows, zacznij pisać Azure Cosmos DB emulatora i wybierz emulator z listy aplikacji

Po uruchomieniu emulatora zobaczysz ikonę w obszarze powiadomień paska zadań systemu Windows.When the emulator has started, you'll see an icon in the Windows taskbar notification area. Automatycznie otwiera Eksploratora danych usługi Azure Cosmos w przeglądarce przy użyciu https://localhost:8081/_explorer/index.html adresu URL adresu URL.It automatically opens the Azure Cosmos data explorer in your browser at this URL https://localhost:8081/_explorer/index.html URL.

Powiadomienie na pasku zadań Azure Cosmos DB lokalnego emulatora

Możesz również uruchomić i zatrzymać emulator z poleceń wiersza polecenia lub programu PowerShell.You can also start and stop the emulator from the command-line or PowerShell commands. Aby uzyskać więcej informacji, zobacz artykuł dotyczący narzędzia wiersza polecenia .For more information, see the command-line tool reference article.

Emulator usługi Azure Cosmos DB domyślnie jest uruchamiany na komputerze lokalnym („localhost”) i nasłuchuje na porcie 8081.The Azure Cosmos DB Emulator by default runs on the local machine ("localhost") listening on port 8081. Adres jest wyświetlany jako https://localhost:8081/_explorer/index.html.The address appears as 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.If you close the explorer and would like to reopen it later, you can either open the URL in your browser or launch it from the Azure Cosmos DB Emulator in the Windows Tray Icon as shown below.

Moduł uruchamiający Eksploratora danych lokalnego emulatora usługi Azure Cosmos

Korzystanie z emulatora w Docker for WindowsUse the emulator on Docker for Windows

Emulator Azure Cosmos DB można uruchomić w kontenerze platformy Docker systemu Windows.You can run the Azure Cosmos DB Emulator on the Windows Docker container. Aby uzyskać więcej informacji, zobacz centrum platformy Docker dla Docker pull polecenia i GitHub Dockerfile .See the Docker Hub for the docker pull command and GitHub for the Dockerfile and more information. Obecnie emulator nie działa na platformie Docker dla Oracle Linux.Currently the emulator does not work on Docker for Oracle Linux. Wykonaj poniższe instrukcje, aby uruchomić emulator w Docker for Windows:Use the following instructions to run the emulator on Docker for Windows:

  1. Po zainstalowaniu Docker for Windows przejdź do kontenerów systemu Windows, klikając prawym przyciskiem myszy ikonę platformy Docker na pasku narzędzi i wybierając pozycję Przełącz na kontenery systemu Windows.After you have Docker for Windows installed, switch to Windows containers by right-clicking the Docker icon on the toolbar and selecting Switch to Windows containers.

  2. Następnie ściągnij obraz emulatora z usługi Docker Hub, uruchamiając następujące polecenie w wybranej powłoce.Next, pull the emulator image from Docker Hub by running the following command from your favorite shell.

    docker pull mcr.microsoft.com/cosmosdb/windows/azure-cosmos-emulator
    
  3. Aby uruchomić obraz, uruchom następujące polecenia w zależności od wiersza polecenia lub środowiska programu PowerShell:To start the image, run the following commands depending on the command line or the PowerShell environment:

    
    md %LOCALAPPDATA%\CosmosDBEmulator\bind-mount
    
    docker run --name azure-cosmosdb-emulator --memory 2GB --mount "type=bind,source=%LOCALAPPDATA%\CosmosDBEmulator\bind-mount,destination=C:\CosmosDB.Emulator\bind-mount" --interactive --tty -p 8081:8081 -p 8900:8900 -p 8901:8901 -p 8902:8902 -p 10250:10250 -p 10251:10251 -p 10252:10252 -p 10253:10253 -p 10254:10254 -p 10255:10255 -p 10256:10256 -p 10350:10350 mcr.microsoft.com/cosmosdb/windows/azure-cosmos-emulator
    

    Obrazy platformy Docker oparte na systemie Windows mogą nie być ogólnie zgodne z każdym systemem operacyjnym hosta Windows.Windows based Docker images might not be generally compatible with every Windows host OS. Na przykład domyślny obraz emulatora Azure Cosmos DB jest zgodny tylko z systemami Windows 10 i Windows Server 2016.For instance, the default Azure Cosmos DB Emulator image is only compatible with Windows 10 and Windows Server 2016. Jeśli potrzebujesz obrazu zgodnego z systemem Windows Server 2019, uruchom następujące polecenie zamiast:If you need an image that is compatible with Windows Server 2019, run the following command instead:

    docker run --name azure-cosmosdb-emulator --memory 2GB --mount "type=bind,source=%hostDirectory%,destination=C:\CosmosDB.Emulator\bind-mount" --interactive --tty -p 8081:8081 -p 8900:8900 -p 8901:8901 -p 8902:8902 -p 10250:10250 -p 10251:10251 -p 10252:10252 -p 10253:10253 -p 10254:10254 -p 10255:10255 -p 10256:10256 -p 10350:10350 mcr.microsoft.com/cosmosdb/winsrv2019/azure-cosmos-emulator:latest
    

    Uwaga

    Jeśli podczas wykonywania docker run polecenia zostanie wyświetlony komunikat o błędzie dotyczącym konfliktu portów (czyli jeśli określony port jest już używany), należy przekazać port niestandardowy, zmieniając numery portów.When executing the docker run command, if you see a port conflict error (that is if the specified port is already in use), pass a custom port by altering the port numbers. Na przykład, można zmienić parametr "-p 8081:8081" na "-p 443:8081"For example, you can change the "-p 8081:8081" parameter to "-p 443:8081"

  4. Teraz użyj punktu końcowego emulatora i klucza podstawowego z odpowiedzi i zaimportuj certyfikat TLS/SSL do hosta.Now use the emulator endpoint and primary key from the response and import the TLS/SSL certificate into your host. Aby zaimportować certyfikat TLS/SSL, uruchom następujące kroki z poziomu wiersza polecenia administratora:To import the TLS/SSL certificate, run the following steps from an admin command prompt:

    cd  %LOCALAPPDATA%\CosmosDBEmulator\bind-mount
    powershell .\importcert.ps1
    
  5. Jeśli zamkniesz interaktywną powłokę po uruchomieniu emulatora, spowoduje to zamknięcie kontenera emulatora.If you close the interactive shell after the emulator has started, it will shut down the emulator's container. Aby ponownie otworzyć Eksploratora danych, przejdź do następującego adresu URL w przeglądarce.To reopen the data explorer, navigate to the following URL in your browser. Punkt końcowy emulatora znajduje się w powyższym komunikacie odpowiedzi.The emulator endpoint is provided in the response message shown above.

    https://<emulator endpoint provided in response>/_explorer/index.html

Jeśli masz uruchomioną aplikację kliencką platformy .NET w kontenerze platformy Docker systemu Linux i jeśli korzystasz z emulatora Azure Cosmos DB na komputerze hosta, użyj instrukcji w następnej sekcji, aby zaimportować certyfikat do kontenera platformy Docker systemu Linux.If you have a .NET client application running on a Linux docker container and if you are running Azure Cosmos DB Emulator on a host machine, use the instructions in the next section to import the certificate into the Linux docker container.

Ponowne generowanie certyfikatów emulatora podczas uruchamiania w kontenerze platformy DockerRegenerate the emulator certificates when running on a Docker container

W przypadku uruchamiania emulatora w kontenerze platformy Docker Certyfikaty skojarzone z emulatorem są generowane ponownie za każdym razem, gdy zatrzymasz i uruchomisz odpowiednie kontenery.When running the emulator in a Docker container, the certificates associated with the emulator are regenerated every time you stop and restart the respective container. Z tego powodu trzeba ponownie zaimportować certyfikaty po każdym uruchomieniu kontenera.Because of that you have to re-import the certificates after each container start. Aby obejść to ograniczenie, można użyć pliku redagowania platformy Docker w celu powiązania kontenera Docker z określonym adresem IP i obrazem kontenera.To work around this limitation, you can use a Docker compose file to bind the Docker container to a particular IP address and a container image.

Na przykład możesz użyć poniższej konfiguracji w pliku programu Docker, pamiętaj, aby sformatować go zgodnie z wymaganiami:For example, you can use the following configuration within the Docker compose file, make sure to format it per your requirement:

version: '2.4' # Do not upgrade to 3.x yet, unless you plan to use swarm/docker stack: https://github.com/docker/compose/issues/4513

networks:
  default:
    external: false
    ipam:
      driver: default
      config:
        - subnet: "172.16.238.0/24"

services:

  # First create a directory that will hold the emulator traces and certificate to be imported
  # set hostDirectory=C:\emulator\bind-mount
  # mkdir %hostDirectory%

  cosmosdb:
    container_name: "azurecosmosemulator"
    hostname: "azurecosmosemulator"
    image: 'mcr.microsoft.com/cosmosdb/windows/azure-cosmos-emulator'
    platform: windows
    tty: true
    mem_limit: 3GB
    ports:
        - '8081:8081'
        - '8900:8900'
        - '8901:8901'
        - '8902:8902'
        - '10250:10250'
        - '10251:10251'
        - '10252:10252'
        - '10253:10253'
        - '10254:10254'
        - '10255:10255'
        - '10256:10256'
        - '10350:10350'
    networks:
      default:
        ipv4_address: 172.16.238.246
    volumes:
        - '${hostDirectory}:C:\CosmosDB.Emulator\bind-mount'

Korzystanie z emulatora w systemie Linux lub macOSUse the emulator on Linux or macOS

Obecnie emulator Azure Cosmos DB można uruchomić tylko w systemie Windows.Currently the Azure Cosmos DB Emulator can only be run on Windows. W przypadku korzystania z systemu Linux lub macOS można uruchomić emulator w maszynie wirtualnej z systemem Windows hostowanej w funkcji hypervisor, takiej jak Parallels lub VirtualBox.If you are using Linux or macOS, you can run the emulator in a Windows virtual machine hosted in a hypervisor such as Parallels or VirtualBox.

Uwaga

Za każdym razem, gdy uruchamiasz maszynę wirtualną z systemem Windows, która jest hostowana w funkcji hypervisor, należy ponownie zaimportować certyfikat, ponieważ adres IP maszyny wirtualnej ulegnie zmianie.Every time you restart the Windows virtual machine that is hosted in a hypervisor, you have to reimport the certificate because the IP address of the virtual machine changes. Importowanie certyfikatu nie jest wymagane w przypadku skonfigurowania maszyny wirtualnej w celu zachowania adresu IP.Importing the certificate isn't required in case you have configured the virtual machine to preserve the IP address.

Wykonaj następujące kroki, aby użyć emulatora w środowiskach Linux lub macOS:Use the following steps to use the emulator on Linux or macOS environments:

  1. Uruchom następujące polecenie z maszyny wirtualnej z systemem Windows i Zanotuj adres IPv4:Run the following command from the Windows virtual machine and make a note of the IPv4 address:

    ipconfig.exe
    
  2. W aplikacji Zmień adres URL punktu końcowego tak, aby używał adresu IPv4 zwróconego przez ipconfig.exe zamiast localhost .Within your application, change the endpoint URL to use the IPv4 address returned by ipconfig.exe instead of localhost.

  3. Na maszynie wirtualnej z systemem Windows uruchom emulator Azure Cosmos DB z wiersza polecenia, korzystając z następujących opcji.From the Windows VM, launch the Azure Cosmos DB Emulator from the command line using the following options. Aby uzyskać szczegółowe informacje na temat parametrów obsługiwanych przez wiersz polecenia, zobacz informacje na temat narzędzia wiersza polecenia emulatora:For details on the parameters supported by the command line, see the emulator command-line tool reference:

    Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
    
  4. Na koniec należy rozwiązać proces zaufania certyfikatu między aplikacją działającą w środowisku Linux lub Mac a emulatorem.Finally, you need to resolve the certificate trust process between the application running on the Linux or Mac environment and the emulator. Aby rozwiązać certyfikat, można użyć jednej z następujących dwóch opcji:You can use one of the following two options to resolve the certificate:

    1. Zaimportuj certyfikat emulatora TLS/SSL do środowiska Linux lub Mac lubImport the emulator TLS/SSL certificate into the Linux or Mac environment or
    2. Wyłącz weryfikację protokołu TLS/SSL w aplikacjiDisable the TLS/SSL validation in the application

Opcja 1: Importowanie certyfikatu emulatora TLS/SSLOption 1: Import the emulator TLS/SSL certificate

W poniższych sekcjach pokazano, jak zaimportować certyfikat emulatora TLS/SSL do środowiska Linux i macOS.The following sections show how to import the emulator TLS/SSL certificate into Linux and macOS environments.

Środowisko systemu LinuxLinux environment

Jeśli pracujesz w systemie Linux, .NET przekazuje na OpenSSL w celu sprawdzenia poprawności:If you are working on Linux, .NET relays on OpenSSL to do the validation:

  1. Wyeksportuj certyfikat w formacie PFX.Export the certificate in PFX format. Opcja PFX jest dostępna podczas wybierania eksportu klucza prywatnego.The PFX option is available when choosing to export the private key.

  2. Skopiuj ten plik PFX do środowiska systemu Linux.Copy that PFX file into your Linux environment.

  3. Konwertuj plik PFX na plik CRTConvert the PFX file into a CRT file

    openssl pkcs12 -in YourPFX.pfx -clcerts -nokeys -out YourCTR.crt
    
  4. Skopiuj plik CRT do folderu, który zawiera niestandardowe certyfikaty w dystrybucji systemu Linux.Copy the CRT file to the folder that contains custom certificates in your Linux distribution. Często w przypadku dystrybucji Debian znajdują się w /usr/local/share/ca-certificates/ .Commonly on Debian distributions, it is located on /usr/local/share/ca-certificates/.

    cp YourCTR.crt /usr/local/share/ca-certificates/
    
  5. Zaktualizuj certyfikaty TLS/SSL, co spowoduje zaktualizowanie /etc/ssl/certs/ folderu.Update the TLS/SSL certificates, which will update the /etc/ssl/certs/ folder.

    update-ca-certificates
    

środowisko macOSmacOS environment

Jeśli pracujesz na komputerze Mac, wykonaj następujące czynności:Use the following steps if you are working on Mac:

  1. Wyeksportuj certyfikat w formacie PFX.Export the certificate in PFX format. Opcja PFX jest dostępna podczas wybierania eksportu klucza prywatnego.The PFX option is available when choosing to export the private key.

  2. Skopiuj ten plik PFX do środowiska Mac.Copy that PFX file into your Mac environment.

  3. Otwórz aplikację dostęp do łańcucha kluczy i zaimportuj plik PFX.Open the Keychain Access application and import the PFX file.

  4. Otwórz listę certyfikatów i zidentyfikuj ją z nazwą localhost .Open the list of Certificates and identify the one with the name localhost.

  5. Otwórz menu kontekstowe dla danego elementu, wybierz opcję Pobierz element i w obszarze zaufanie w > przypadku korzystania z tego certyfikatu , wybierz pozycję Zawsze ufaj.Open the context menu for that particular item, select Get Item and under Trust > When using this certificate option, select Always Trust.

    Otwórz menu kontekstowe dla danego elementu, wybierz pozycję Pobierz element i w obszarze zaufanie — w przypadku korzystania z tego certyfikatu wybierz opcję Zawsze ufaj.

Opcja 2. wyłączenie weryfikacji SSL w aplikacjiOption 2: Disable the SSL validation in the application

Wyłączenie walidacji protokołu SSL jest zalecane tylko w celach programistycznych i nie powinno być wykonywane w środowisku produkcyjnym.Disabling SSL validation is only recommended for development purposes and should not be done when running in a production environment. W poniższych przykładach pokazano, jak wyłączyć weryfikację SSL dla aplikacji .NET i Node.js.The following examples show how to disable SSL validation for .NET and Node.js applications.

W przypadku dowolnej aplikacji uruchomionej w strukturze zgodnej z .NET Standard 2,1 lub nowszej można wykorzystać CosmosClientOptions.HttpClientFactory :For any application running in a framework compatible with .NET Standard 2.1 or later, we can leverage the 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 lokalnejEnable access to emulator on a local network

Jeśli masz wiele maszyn przy użyciu pojedynczej sieci, a następnie skonfigurujesz emulator na jednej maszynie i chcesz uzyskać do niego dostęp z innego komputera.If you have multiple machines using a single network, and if you set up the emulator on one machine and want to access it from other machine. W takim przypadku należy włączyć dostęp do emulatora w sieci lokalnej.In such case, you need to enable access to the emulator on a local network.

Emulator możesz uruchomić w sieci lokalnej.You can run the emulator on a local network. Aby włączyć dostęp do sieci, należy określić /AllowNetworkAccess opcję w wierszu polecenia, która wymaga również określenia /Key=key_string lub /KeyFile=file_name .To enable network access, specify the /AllowNetworkAccess option at the command-line, which also requires that you specify /Key=key_string or /KeyFile=file_name. Możesz użyć /GenKeyFile=file_name do wygenerowania pliku z kluczem losowym z góry.You can use /GenKeyFile=file_name to generate a file with a random key upfront. Następnie możesz przekazać ten program do /KeyFile=file_name lub /Key=contents_of_file .Then you can pass that to /KeyFile=file_name or /Key=contents_of_file.

Aby włączyć dostęp do sieci po raz pierwszy, użytkownik powinien zamknąć emulator i usunąć %LocalAppData%\CosmosDBEmulator katalogu danych emulatora.To enable network access for the first time, the user should shut down the emulator and delete the emulator's data directory %LOCALAPPDATA%\CosmosDBEmulator.

Uwierzytelniaj połączenia w przypadku korzystania z emulatoraAuthenticate connections when using emulator

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.As with Azure Cosmos DB in the cloud, every request that you make against the Azure Cosmos DB Emulator must be authenticated. Emulator Azure Cosmos DB obsługuje tylko bezpieczną komunikację za pośrednictwem protokołu TLS.The Azure Cosmos DB Emulator supports only secure communication via TLS. Emulator Azure Cosmos DB obsługuje pojedyncze stałe konto i dobrze znane klucze uwierzytelniania na potrzeby uwierzytelniania przy użyciu klucza podstawowego.The Azure Cosmos DB Emulator supports a single fixed account and a well-known authentication key for primary key authentication. To konto i klucz są jedynymi poświadczeniami, których można używać z emulatorem usługi Azure Cosmos DB.This account and key are the only credentials permitted for use with the Azure Cosmos DB Emulator. Są to:They are:

Account name: localhost:<port>
Account key: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

Uwaga

Klucz podstawowy obsługiwany przez emulator Azure Cosmos DB jest przeznaczony do użytku tylko z emulatorem.The primary key supported by the Azure Cosmos DB Emulator is intended for use only with the emulator. 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.You cannot use your production Azure Cosmos DB account and key with the Azure Cosmos DB Emulator.

Uwaga

Jeśli emulator został uruchomiony przy użyciu opcji/Key, zamiast klucza domyślnego Użyj wygenerowanego klucza C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== .If you have started the emulator with the /Key option, then use the generated key instead of the default key C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==. Aby uzyskać więcej informacji na temat opcji/Key, zobacz informacje dotyczące narzędzia wiersza polecenia.For more information about /Key option, see Command-line tool reference.

Łączenie z innymi interfejsami API za pomocą emulatoraConnect to different APIs with the emulator

Interfejs API SQLSQL API

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.Once you have the Azure Cosmos DB Emulator running on your desktop, you can use any supported Azure Cosmos DB SDK or the Azure Cosmos DB REST API to interact with the emulator. Emulator Azure Cosmos DB obejmuje również wbudowany Eksplorator danych, który umożliwia tworzenie kontenerów dla interfejsu API SQL lub Azure Cosmos DB dla interfejsu API usługi Mongo DB.The Azure Cosmos DB Emulator also includes a built-in data explorer that lets you create containers for SQL API or Azure Cosmos DB for Mongo DB API. Za pomocą Eksploratora danych można wyświetlać i edytować elementy bez pisania kodu.By using the data explorer, you can view and edit items without writing any code.

// Connect to the Azure Cosmos DB Emulator running locally
CosmosClient client = new CosmosClient(
   "https://localhost:8081", 
    "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==");

Interfejs API usługi Azure Cosmos DB dla bazy danych MongoDBAzure Cosmos DB's API for MongoDB

Po uruchomieniu emulatora Azure Cosmos DB na pulpicie możesz użyć interfejsu API Azure Cosmos DB dla MongoDB , aby współdziałać z emulatorem.Once you have the Azure Cosmos DB Emulator running on your desktop, you can use the Azure Cosmos DB's API for MongoDB to interact with the emulator. Uruchom emulator z wiersza polecenia jako administrator z "/EnableMongoDbEndpoint".Start the emulator from command prompt as an administrator with "/EnableMongoDbEndpoint". Następnie użyj następujących parametrów połączenia, aby nawiązać połączenie z kontem interfejsu API MongoDB:Then use the following connection string to connect to the MongoDB API account:

mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true

Interfejs API tabelTable API

Po uruchomieniu emulatora Azure Cosmos DB na pulpicie możesz korzystać z zestawu SDK Azure Cosmos DB interfejs API tabel do korzystania z emulatora.Once you have the Azure Cosmos DB Emulator running on your desktop, you can use the Azure Cosmos DB Table API SDK to interact with the emulator. Uruchom emulator z wiersza polecenia jako administrator z "/EnableTableEndpoint".Start the emulator from command prompt as an administrator with "/EnableTableEndpoint". Następnie uruchom następujący kod, aby nawiązać połączenie z kontem interfejsu API tabel:Next run the following code to connect to the table API account:

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 rozwiązania CassandraCassandra API

Uruchom emulator z wiersza polecenia administratora z "/EnableCassandraEndpoint".Start emulator from an administrator command prompt with "/EnableCassandraEndpoint". Alternatywnie można również ustawić zmienną środowiskową AZURE_COSMOS_EMULATOR_CASSANDRA_ENDPOINT=true .Alternatively you can also set the environment variable AZURE_COSMOS_EMULATOR_CASSANDRA_ENDPOINT=true.

  1. Zainstaluj Język Python 2,7Install Python 2.7

  2. Instalowanie interfejsu wiersza polecenia Cassandra/CQLSHInstall Cassandra CLI/CQLSH

  3. Uruchom następujące polecenia w zwykłym oknie wiersza polecenia:Run the following commands in a regular command prompt window:

    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== --ssl
    
  4. W powłoce CQLSH Uruchom następujące polecenia, aby nawiązać połączenie z punktem końcowym Cassandra:In the CQLSH shell, run the following commands to connect to the Cassandra endpoint:

    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 języka GremlinGremlin API

Uruchom emulator z wiersza poleceniaadministratora z "/EnableGremlinEndpoint".Start emulator from an administrator command promptwith "/EnableGremlinEndpoint". Alternatywnie można również ustawić zmienną środowiskową AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=trueAlternatively you can also set the environment variable AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=true

  1. Zainstaluj Apache-tinkerpop-Gremlin-Console-3.3.4.Install apache-tinkerpop-gremlin-console-3.3.4.

  2. Z poziomu Eksploratora danych emulatora Utwórz bazę danych "DB1" i kolekcję "coll1"; w przypadku klucza partycji wybierz pozycję "/name"From the emulator's data explorer create a database "db1" and a collection "coll1"; for the partition key, choose "/name"

  3. Uruchom następujące polecenia w zwykłym oknie wiersza polecenia:Run the following commands in a regular command prompt window:

    cd /d C:\sdk\apache-tinkerpop-gremlin-console-3.3.4-bin\apache-tinkerpop-gremlin-console-3.3.4
    
    copy /y conf\remote.yaml conf\remote-localcompute.yaml
    notepad.exe conf\remote-localcompute.yaml
      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  }}
    
    bin\gremlin.bat
    
  4. W powłoce Gremlin Uruchom następujące polecenia, aby nawiązać połączenie z punktem końcowym Gremlin:In the Gremlin shell, run the following commands to connect to the Gremlin endpoint:

    :remote connect tinkerpop.server conf/remote-localcompute.yaml
    :remote console
    :> g.V()
    :> g.addV('person1').property(id, '1').property('name', 'somename1')
    :> g.addV('person2').property(id, '2').property('name', 'somename2')
    :> g.V()
    

Odinstalowywanie lokalnego emulatoraUninstall the local emulator

Aby odinstalować emulator, wykonaj następujące kroki:Use the following steps to uninstall the emulator:

  1. Zamknij wszystkie otwarte wystąpienia emulatora lokalnego, klikając prawym przyciskiem myszy ikonę emulatora Azure Cosmos DB na pasku zadań, a następnie wybierz polecenie Zakończ.Exit all the open instances of the local emulator by right-clicking the Azure Cosmos DB Emulator icon on the system tray, and then select Exit. Zamykanie wszystkich wystąpień może potrwać około minuty.It may take a minute for all instances to exit.

  2. W polu wyszukiwania systemu Windows wpisz aplikacje & funkcje i wybierz pozycję aplikacje & funkcje (Ustawienia systemowe) .In the Windows search box, type Apps & features and select Apps & features (System settings) result.

  3. Na liście aplikacji przewiń do emulatora Azure Cosmos DB, wybierz go, kliknij polecenie Odinstaluj, a następnie potwierdź i wybierz ponownie przycisk Odinstaluj .In the list of apps, scroll to the Azure Cosmos DB Emulator, select it, click Uninstall, then confirm and select Uninstall again.

Następne krokiNext steps

W tym artykule przedstawiono sposób korzystania z lokalnego emulatora do bezpłatnego tworzenia lokalnego.In this article, you've learned how to use the local emulator for free local development. Teraz możesz przechodzić do następnych artykułów:You can now proceed to the next articles: