Emulator oparty na systemie Linux — vNext (wersja zapoznawcza)

Dotyczy: ✅ NoSQL

Kolejna generacja emulatora Azure Cosmos DB jest całkowicie oparta na systemie Linux i jest dostępna jako kontener platformy Docker. Obsługuje on uruchamianie na wielu różnych procesorach i systemach operacyjnych.

Ważne

Ta wersja emulatora obsługuje tylko interfejs API dla NoSQL w trybie gateway z wybranym podzestawem funkcji. Aby uzyskać więcej informacji, zobacz wsparcie funkcji.

Wymagania wstępne

Doker

Instalacja

Pobierz obraz kontenera platformy Docker przy użyciu polecenia docker pull. Obraz kontenera jest publikowany w Microsoft Artifact Registry jako mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview.

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview

Działa

Aby uruchomić kontener, użyj polecenia docker run. Następnie użyj polecenia docker ps , aby sprawdzić, czy kontener jest uruchomiony.

docker run --detach --publish 8081:8081 --publish 8080:8080 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview

docker ps

CONTAINER ID   IMAGE                                                             COMMAND                  CREATED         STATUS         PORTS                                                                                  NAMES
c1bb8cf53f8a   mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview  "/bin/bash -c /home/…"   5 seconds ago   Up 5 seconds   0.0.0.0:1234->1234/tcp, :::1234->1234/tcp, 0.0.0.0:8081->8081/tcp, :::8081->8081/tcp   <container-name>

Emulator zawiera dwa składniki:

Data Explorer — interaktywne eksplorowanie danych w emulatorze. Domyślnie ten składnik jest uruchamiany na porcie 1234.
Azure Cosmos DB emulator — lokalna wersja usługi bazy danych Azure Cosmos DB. Domyślnie ten składnik jest uruchamiany na porcie 8081.

Punkt końcowy bramy emulatora używa portu 8081 pod adresem http://localhost:8081. Aby przejść do Data Explorer, użyj adresu http://localhost:1234 w przeglądarce internetowej. Punkt końcowy bramy jest zwykle dostępny natychmiast, ale uruchomienie Data Explorer może potrwać kilka sekund.

Sonda kondycji

Emulator uwidacznia punkt końcowy sondy kondycji na porcie 8080. Użyj tego punktu końcowego, aby określić, kiedy emulator jest w pełni zainicjowany i gotowy do akceptowania żądań.

Dostępne są następujące punkty końcowe:

http://localhost:8080/alive — sonda aktywności.
http://localhost:8080/ready — sonda gotowości.
http://localhost:8080/status — stan szczegółowy.

Uwaga

Starszy komunikat System is now fully ready to accept requests dziennika jest nadal emitowany w celu zapewnienia zgodności z poprzednimi wersjami, ale może zostać usunięty w przyszłej wersji. Zamiast tego użyj sondy kondycji do sprawdzania gotowości.

Tryb HTTPS

Zestawy SDK .NET i Java nie obsługują trybu HTTP w emulatorze. Ponieważ ta wersja emulatora domyślnie rozpoczyna się od protokołu HTTP, należy jawnie włączyć protokół HTTPS podczas uruchamiania kontenera (zobacz poniżej). W przypadku zestawu SDK Java należy również instalować certyfikaty.

docker run --detach --publish 8081:8081 --publish 8080:8080 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol https

Jeśli używasz protokołu HTTPS z utrwałymi woluminami danych, emulator automatycznie ponownie generuje certyfikaty SSL podczas uruchamiania, więc nie trzeba zarządzać odnawianiem certyfikatu.

Polecenia platformy Docker

Poniższa tabela zawiera podsumowanie dostępnych poleceń platformy Docker na potrzeby konfigurowania emulatora. Ta tabela zawiera szczegółowe informacje o odpowiednich argumentach, zmiennych środowiskowych, dozwolonych wartościach, ustawieniach domyślnych i opisach każdego polecenia.

Wymaganie	Ech	Środowisko	Dozwolone wartości	Domyślny	opis
Wydrukuj ustawienia na stdout z kontenera	`--help`, `-h`	Brak	Brak	Brak	Wyświetlanie informacji o dostępnej konfiguracji
Ustawianie portu punktu końcowego usługi Cosmos	`--port [INT]`	port morski	INT	8081	Port punktu końcowego usługi Cosmos w kontenerze. Nadal musisz opublikować ten port (na przykład `-p 8081:8081`).
Określanie protokołu używanego przez punkt końcowy usługi Cosmos	`--protocol`	PROTOKÓŁ	`https`, `httphttps-insecure`	`http`	Protokół punktu końcowego Cosmos na kontenerze.
Włączanie eksploratora danych	`--enable-explorer`	WŁĄCZ_EKSPLORATOR	`true`, `false`	`true`	Włącz uruchamianie usługi Cosmos Data Explorer w tym samym kontenerze.
Ustawianie portu używanego przez eksploratora danych	`--explorer-port`	EXPLORER_PORT	INT	1234	Port usługi Cosmos Data Explorer w kontenerze. Nadal musisz opublikować ten port (na przykład `-p 1234:1234`).
Określanie protokołu używanego przez eksploratora danych	`--explorer-protocol`	EXPLORER_PROTOCOL	`https`, `httphttps-insecure`	`<the value of --protocol>`	Protokół usługi Cosmos Data Explorer w kontenerze. Domyślnie jest to ustawienie protokołu w punkcie końcowym usługi Cosmos.
Dostosuj publiczny punkt końcowy bramy	`--gateway-endpoint`	GATEWAY_PUBLIC_ENDPOINT	Brak	`localhost`	Punkt końcowy bramy publicznej. Wartość domyślna to `localhost`.
Określanie klucza za pomocą pliku	`--key-file [PATH]`	PLIK_KLUCZA	ŚCIEŻKA	`<default secret>`	Zastąpij klucz domyślny kluczem określonym w pliku. Musisz zamontować ten plik w kontenerze (na przykład, jeśli KEY_FILE=/mykey, należy dodać następującą opcję do polecenia uruchomienia Docker: `--mount type=bind,source=./myKey,target=/myKey`)
Ustawianie ścieżki danych	`--data-path [PATH]`	DATA_PATH	ŚCIEŻKA	`/data`	Określ katalog dla danych. Często używane z opcją `docker run --mount` (na przykład, jeśli DATA_PATH=/usr/cosmos/data, należy dodać opcję podobną do następującej podczas uruchamiania Dockera: `--mount type=bind,source=./.local/data,target=/usr/cosmos/data`)
Określ ścieżkę certyfikatu, która ma być używana dla protokołu https	`--cert-path [PATH]`	CERT_PATH	ŚCIEŻKA	`<default cert>`	Określ ścieżkę do certyfikatu na potrzeby zabezpieczania ruchu. Musisz zainstalować ten plik w kontenerze (na przykład jeśli CERT_PATH=/mycert.pfx, należy dodać opcję podobną do następującej do uruchomienia platformy Docker: `--mount type=bind,source=./mycert.pfx,target=/mycert.pfx`)
Określ klucz tajny certyfikatu, który ma być używany dla protokołu https	Brak	CERTYFIKAT_SEKRET	ciąg	`<default secret>`	Tajny klucz dla certyfikatu określonego w CERT_PATH.
Ustawianie poziomu dziennika	`--log-level [LEVEL]`	Poziom logowania	`quiet`, , `error`, `warn`, `info`, , `debugtrace`	`info`	Szczegółowość dzienników emitowanych przez emulator i eksplorator danych.
Włączanie eksportera OTLP OpenTelemetry	`--enable-otlp`	ENABLE_OTLP_EXPORTER	`true`, `false`	`false`	Włącz integrację platformy OpenTelemetry.
Włącz eksportera konsoli	`--enable-console`	WŁĄCZ_KONSOLOWY_EKSPORTER	`true`, `false`	`false`	Włącz wyświetlanie danych telemetrycznych w konsoli (przydatne do debugowania).
Włącz tryb szczegółowy	`--verbose`	GADATLIWY	`true`, `false`	`false`	Włącz tryb szczegółowy, aby wyświetlić dzienniki PostgreSQL (pglog) na konsoli. Przydatne do debugowania.
Ustawianie rozmiaru buforu zapytania	`--query-buffer-size`	QUERY_BUFFER_SIZE_KB	INT	4096 (4 MB), max 65536 (64 MB)	Maksymalny rozmiar w KB dla buforów wyników zapytania. Zwiększ tę liczbę, jeśli wystąpią błędy HTTP 500 w przypadku dużych zapytań.
Włączanie wysyłania informacji diagnostycznych do Microsoft	`--enable-telemetry`	WŁĄCZ TELEMETRIĘ	`true`, `false`	`true`	Włącz wysyłanie danych użycia do Microsoft, aby pomóc nam ulepszyć emulator.

Obsługa funkcji

Ten emulator jest w aktywnym rozwoju i wersji testowej. W związku z tym nie wszystkie funkcje Azure Cosmos DB są obsługiwane. Niektóre funkcje nie będą również obsługiwane w przyszłości. Ta tabela zawiera stan różnych funkcji i ich poziom obsługi.

Funkcja	Wsparcie
Batch API	✅ Obsługiwane
API zbiorcze	✅ Obsługiwane
Zestawienie zmian	✅ Obsługiwane
Tworzenie i odczytywanie dokumentu przy użyciu danych utf	✅ Obsługiwane
Tworzenie kolekcji	✅ Obsługiwane
Konflikt wynikający z dwukrotnego tworzenia kolekcji	✅ Obsługiwane
Tworzenie kolekcji przy użyciu niestandardowych zasad indeksu	⚠✔ Brak operacji
Utwórz kolekcję z czasem wygaśnięcia (TTL)	✅ Obsługiwane
Tworzenie bazy danych	✅ Obsługiwane
Podwójny konflikt tworzenia bazy danych	✅ Obsługiwane
Tworzenie dokumentu	✅ Obsługiwane
Tworzenie kolekcji partycjonowanej	✅ Obsługiwane
Usuwanie kolekcji	✅ Obsługiwane
Usuwanie bazy danych	✅ Obsługiwane
Usuwanie dokumentu	✅ Obsługiwane
Zyskaj i zmień efektywność kolekcji	⚠✔ Jeszcze nie zaimplementowano
Wstaw duży dokument	✅ Obsługiwane
Dokument poprawki	✅ Obsługiwane
Wykonywanie zapytań dotyczących kolekcji partycjonowanej równolegle	⚠✔ Jeszcze nie zaimplementowano
Wykonywanie zapytań za pomocą agregacji	✅ Obsługiwane
Wykonywanie zapytań za pomocą funkcji i filtrowanie	✅ Obsługiwane
Zapytywanie z filtrowaniem i projekcją	✅ Obsługiwane
Zapytanie o równość	✅ Obsługiwane
Zapytanie z warunkiem równości na identyfikatorze	✅ Obsługiwane
Wykonywanie zapytań z sprzężeniami	✅ Obsługiwane
Wykonywanie zapytań według kolejności	✅ Obsługiwane
Wykonywanie zapytań o kolejność według dla kolekcji partycjonowanej	✅ Obsługiwane
Wykonywanie zapytań według kolejności według liczb	✅ Obsługiwane
Zapytywanie z sortowaniem według ciągów	✅ Obsługiwane
Wykonywanie zapytań przy użyciu stronicowania	✅ Obsługiwane
Wykonywanie zapytań przy użyciu operatorów zakresu daty/godziny	✅ Obsługiwane
Wykonywanie zapytań przy użyciu operatorów zakresu w liczbach	✅ Obsługiwane
Wykonywanie zapytań za pomocą operatorów zakresu w ciągach	✅ Obsługiwane
Zapytanie z pojedynczym sprzężeniem	✅ Obsługiwane
Wykonywanie zapytań przy użyciu operatorów matematycznych ciągów i tablic	✅ Obsługiwane
Wykonywanie zapytań przy użyciu dokumentów podrzędnych	✅ Obsługiwane
Zapytanie z dwoma sprzężeniami	✅ Obsługiwane
Zapytanie z dwoma sprzężeniami i filtrem	✅ Obsługiwane
Odczytaj kolekcję	✅ Obsługiwane
Odczytywanie źródła danych kolekcji	⚠✔ Jeszcze nie zaimplementowano
Odczyt bazy danych	✅ Obsługiwane
Odczyt źródła danych	⚠✔ Jeszcze nie zaimplementowano
Odczytywanie dokumentu	✅ Obsługiwane
Odczytywanie kanału informacyjnego dokumentu	✅ Obsługiwane
Zamień dokument	✅ Obsługiwane
Jednostki żądania	⚠✔ Jeszcze nie zaimplementowano
Procedury składowane	❌ Nieplanowe
Wyzwalacze	❌ Nieplanowe
UDF (Funkcje zdefiniowane przez użytkownika)	❌ Nieplanowe
Aktualizowanie kolekcji	⚠✔ Brak operacji
Aktualizowanie dokumentu	✅ Obsługiwane
Oferuje punkt końcowy	⚠✔ Brak operacji
Punkt końcowy użytkowników	⚠✔ Brak operacji
Punkt końcowy uprawnień	⚠✔ Brak operacji
Klucze szyfrowania klienta (CEK)	⚠✔ Brak operacji

Uwaga

Funkcje oznaczone jako brak operacji akceptują żądania i zwracają prawidłowe kody stanu HTTP, ale nie wykonują podstawowej operacji. Kod nie ulegnie awarii, ale nie polegaj na tych funkcjach dla działania funkcjonalnego. Niestandardowe zasady indeksowania i aktualizacje kolekcji są akceptowane pod kątem zgodności, ale zapytania nie są zoptymalizowane przez indeksy niestandardowe.

Ograniczenia

Oprócz funkcji, które nie są jeszcze obsługiwane lub nie są planowane, poniższa lista zawiera bieżące ograniczenia emulatora.

Zestaw SDK .NET dla Azure Cosmos DB nie obsługuje wykonywania zbiorczego w emulatorze.
Jeśli wystąpią błędy HTTP 500 przy dużych wynikach zapytania, aby zwiększyć rozmiar buforu zapytania, użyj flagi --query-buffer-size lub zmiennej środowiskowej QUERY_BUFFER_SIZE_KB. Wartość domyślna to KB (4096MB), a wartość maksymalna to 465536 KB (64MB).

Instalowanie certyfikatów dla zestawu SDK Java

Podczas korzystania z pakietu Java SDK dla Azure Cosmos DB z tą wersją emulatora w trybie https, należy zainstalować jego certyfikaty w lokalnym magazynie zaufania Java.

Pobieranie certyfikatu

W oknie bash uruchom następujące polecenie:

# If the emulator was started with /AllowNetworkAccess, replace localhost 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

Instalowanie certyfikatu

Przejdź do katalogu instalacji języka Java, w którym cacerts znajduje się plik (zastąp poniżej poprawnym katalogiem):

cd "C:/Program Files/Eclipse Adoptium/jdk-17.0.10.7-hotspot/bin"

Zaimportuj certyfikat (może zostać wyświetlony monit o podanie hasła, wartość domyślna to "changeit"):

keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH

Jeśli wystąpi błąd, ponieważ alias już istnieje, usuń go, a następnie ponownie uruchom powyższe polecenie:

keytool -cacerts -delete -alias cosmos_emulator

Obsługa funkcji OpenTelemetry

OpenTelemetry to platforma do obserwacji typu open source, która udostępnia kolekcję narzędzi, interfejsów API i zestawów SDK do instrumentowania, generowania, zbierania i eksportowania danych telemetrycznych. Protokół OpenTelemetry Protocol (OTLP) to protokół używany przez usługę OpenTelemetry do przesyłania danych telemetrycznych między składnikami.

Możesz użyć funkcji OpenTelemetry z emulatorem do monitorowania i śledzenia aplikacji. Emulator obsługuje opcje telemetrii, które można skonfigurować za pomocą zmiennych środowiskowych lub flag wiersza polecenia podczas uruchamiania kontenera platformy Docker.

Emulator eksportuje następujące metryki. Są one dostępne za pośrednictwem dowolnego zaplecza metryk, które obsługują protokół OTLP i zapewniają cenny wgląd w wydajność i kondycję bazy danych:

Stawki żądań: pokazuje wzorce ruchu dla różnych typów operacji
Czas wykonywania zapytań: mierzy czas potrzebny na wykonywanie różnych zapytań
Wykorzystanie zasobów: procesor CPU, użycie pamięci i metryki puli połączeń
Współczynniki błędów: Śledzenie błędów według typu i punktu końcowego

Uwaga

Emulator obsługuje warunkowy protokół TLS dla eksportera OTLP, dzięki czemu można zintegrować z platformami do obserwacji, które wymagają bezpiecznych połączeń.

Szczegółowe instrukcje z przykładami są dostępne w repozytorium GitHub.

Stosowanie w cyklu ciągłej integracji

Korzystanie z kontenerów platformy Docker w potokach ciągłej integracji/ciągłego wdrażania ma wiele zalet, szczególnie w przypadku systemów stanowych, takich jak bazy danych. Może to być związane z opłacalnością, wydajnością, niezawodnością i spójnością zestawów testów.

Emulator można włączyć w ramach potoków ciągłej integracji/ciągłego wdrażania. Możesz odwołać się do tego repozytorium GitHub który zawiera przykłady używania emulatora w ramach przepływu pracy ciągłej integracji GitHub Actions dla .NET, Python, Java i aplikacji Go zarówno w x64, jak i ARM64 architektur (pokazano dla modułu uruchamiającego testy systemu Linux przy użyciu ubuntu).

Oto przykład przepływu pracy CI w GitHub Actions, który pokazuje, jak skonfigurować emulator jako kontener usługi GitHub Actions w ramach zadania w tym przepływie. GitHub zajmuje się uruchamianiem kontenera platformy Docker i niszczy go po zakończeniu zadania bez konieczności ręcznej interwencji (na przykład przy użyciu polecenia docker run).

name: CI demo app

on:
  push:
    branches: [main]
    paths:
      - 'java-app/**'
  pull_request:
    branches: [main]
    paths:
      - 'java-app/**'

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    services:
      cosmosdb:
        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
        ports:
          - 8081:8081
        env:
          PROTOCOL: https
        
    env:
      COSMOSDB_CONNECTION_STRING: ${{ secrets.COSMOSDB_CONNECTION_STRING }}
      COSMOSDB_DATABASE_NAME: ${{ vars.COSMOSDB_DATABASE_NAME }}
      COSMOSDB_CONTAINER_NAME: ${{ vars.COSMOSDB_CONTAINER_NAME }}

    steps:

      - name: Set up Java
        uses: actions/setup-java@v3
        with:
          distribution: 'microsoft'
          java-version: '21.0.0'

      - name: Export Cosmos DB Emulator Certificate
        run: |

          sudo apt update && sudo apt install -y openssl

          openssl s_client -connect localhost:8081 </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cosmos_emulator.cert

          cat cosmos_emulator.cert

          $JAVA_HOME/bin/keytool -cacerts -importcert -alias cosmos_emulator -file cosmos_emulator.cert -storepass changeit -noprompt
      
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Run tests
        run: cd java-app && mvn test

To zadanie jest uruchamiane przez agenta Ubuntu i używa obrazu Dockera mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview jako kontenera usługi. Używa zmiennych środowiskowych do konfigurowania parametry połączenia, nazwy bazy danych i nazwy kontenera. Ponieważ w tym przypadku zadanie jest uruchomione bezpośrednio na maszynie uruchomieniowej GitHub Actions, krok Uruchom testy w zadaniu może uzyskać dostęp do emulatora, który jest dostępny poprzez localhost:8081 (8081 to port udostępniany przez emulator).

Krok Export Cosmos DB Emulator Certificate jest specyficzny dla aplikacji Java, ponieważ zestaw SDK Azure Cosmos DB Java obecnie nie obsługuje trybu HTTP w emulatorze. Zmienna środowiskowa PROTOCOL jest ustawiona na https w sekcji services, a ten krok eksportuje certyfikat emulatora i importuje go do magazynu kluczy Java. Dotyczy to również .NET.

Raportowanie problemów

Jeśli wystąpią problemy z używaniem tej wersji emulatora, otwórz problem w repozytorium GitHub (https://github.com/Azure/azure-cosmos-db-emulator-docker) i oznacz go etykietą cosmosEmulatorVnextPreview.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-04-21

Udostępnij za pośrednictwem

Emulator oparty na systemie Linux — vNext (wersja zapoznawcza)

Wymagania wstępne

Instalacja

Działa

Sonda kondycji

Tryb HTTPS

Polecenia platformy Docker

Obsługa funkcji

Ograniczenia

Instalowanie certyfikatów dla zestawu SDK Java

Pobieranie certyfikatu

Instalowanie certyfikatu

Obsługa funkcji OpenTelemetry

Stosowanie w cyklu ciągłej integracji

Raportowanie problemów

Opinia

Dodatkowe zasoby