Emulator oparty na systemie Linux — vNext (wersja zapoznawcza)

2025-04-09

Kolejna generacja emulatora usługi 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 Rejestr Artefaktów Microsoft 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 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>

Uwaga

Emulator składa się z dwóch składników:

Eksplorator danych — interaktywnie eksplorowanie danych w emulatorze. Domyślnie jest to uruchamiane na porcie 1234
Emulator usługi Azure Cosmos DB — lokalna wersja usługi bazy danych Azure Cosmos DB. Domyślnie jest to uruchamiane na porcie 8081.

Punkt końcowy bramy emulatora jest zazwyczaj dostępny na porcie 8081 pod adresem http://localhost:8081. Aby przejść do eksploratora danych, użyj adresu http://localhost:1234 w przeglądarce internetowej. Udostępnienie eksploratora danych może potrwać kilka sekund. Punkt końcowy bramy jest zwykle dostępny natychmiast.

Ważne

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 JAVA SDK należy również zainstalować certyfikaty.

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

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`, `http`, `https-insecure`	`http`	Protokół punktu końcowego Cosmos na kontenerze.
Włączanie eksploratora danych	`--enable-explorer`	WŁĄCZ_EKSPLORATOR	`true`, `false`	`true`	Włącz uruchamianie Eksploratora danych usługi Cosmos na tym samym kontenerze.
Ustawianie portu używanego przez eksploratora danych	`--explorer-port`	EXPLORER_PORT	INT	1234	Port Eksploratora danych Cosmos na kontenerze. Nadal musisz opublikować ten port (na przykład `-p 1234:1234`).
Użytkownik powinien mieć możliwość określenia protokołu używanego przez eksploratora, w przeciwnym razie powinien używać protokołu domyślnego, który stosuje punkt końcowy usługi Cosmos.	`--explorer-protocol`	EXPLORER_PROTOCOL	`https`, `http`, `https-insecure`	`<the value of --protocol>`	Protokół danych Cosmos Explorer w kontenerze. Domyślnie jest to ustawienie protokołu w punkcie końcowym usługi Cosmos.
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ść logów emitowanych przez emulator i eksplorator danych.
Włączanie wysyłania informacji diagnostycznych do firmy Microsoft	`--enable-telemetry`	WŁĄCZ TELEMETRIĘ	`true`, `false`	`true`	Włącz wysyłanie dzienników do firmy 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 usługi 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	⚠✔ Jeszcze nie zaimplementowano
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	⚠✔ Jeszcze nie zaimplementowano
Wykonywanie zapytań za pomocą funkcji i filtrowanie	⚠✔ Jeszcze nie zaimplementowano
Zapytywanie z filtrowaniem i projekcją	⚠✔ Jeszcze nie zaimplementowano
Zapytanie o równość	✅ Obsługiwane
Zapytanie z warunkiem równości na identyfikatorze	✅ Obsługiwane
Wykonywanie zapytań z sprzężeniami	⚠✔ Jeszcze nie zaimplementowano
Wykonywanie zapytań według kolejności	✅ Obsługiwane
Wykonywanie zapytań o kolejność według dla kolekcji partycjonowanej	⚠✔ Jeszcze nie zaimplementowano
Wykonywanie zapytań według kolejności według liczb	✅ Obsługiwane
Zapytywanie z sortowaniem według ciągów	⚠✔ Jeszcze nie zaimplementowano
Wykonywanie zapytań przy użyciu stronicowania	⚠✔ Jeszcze nie zaimplementowano
Wykonywanie zapytań przy użyciu operatorów zakresu daty/godziny	⚠✔ Jeszcze nie zaimplementowano
Wykonywanie zapytań przy użyciu operatorów zakresu w liczbach	⚠✔ Jeszcze nie zaimplementowano
Wykonywanie zapytań za pomocą operatorów zakresu w ciągach	⚠✔ Jeszcze nie zaimplementowano
Zapytanie z pojedynczym sprzężeniem	⚠✔ Jeszcze nie zaimplementowano
Wykonywanie zapytań przy użyciu operatorów matematycznych ciągów i tablic	⚠✔ Jeszcze nie zaimplementowano
Wykonywanie zapytań przy użyciu dokumentów podrzędnych	⚠✔ Jeszcze nie zaimplementowano
Zapytanie z dwoma sprzężeniami	⚠✔ Jeszcze nie zaimplementowano
Zapytanie z dwoma sprzężeniami i filtrem	⚠✔ Jeszcze nie zaimplementowano
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	⚠✔ Jeszcze nie zaimplementowano
Aktualizowanie dokumentu	✅ Obsługiwane

Ograniczenia

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

Zestaw .NET SDK dla usługi Azure Cosmos DB nie obsługuje wykonywania zbiorczego w emulatorze.
Zestawy SDK .NET i Java nie obsługują trybu HTTP w emulatorze.

Instalowanie certyfikatów dla zestawu Java SDK

W przypadku korzystania z Java SDK dla Azure Cosmos DB z tą wersją emulatora w trybie https konieczne jest zaimportowanie jego certyfikatów do lokalnego magazynu 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

Stosowanie w cyklu ciągłej integracji

Korzystanie z kontenerów platformy Docker w potokach CI/CD ma wiele zalet, zwłaszcza w przypadku systemów z zachowaniem stanu, 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 zapoznać się z tym repozytorium GitHub, które zawiera przykłady użycia emulatora w ramach przepływu pracy ciągłej integracji z GitHub Actions dla aplikacji .NET, Python, Java i Go na obu architekturach x64 i ARM64 (pokazano dla agenta na Linuxie przy użyciu ubuntu).

Oto przykład przepływu pracy CI z użyciem GitHub Actions, który pokazuje, jak skonfigurować emulator jako kontener usługi GitHub Actions jako część zadania w przepływie pracy. Usługa GitHub zajmuje się uruchamianiem kontenera 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 parametrów połączenia, nazwy bazy danych i nazwy kontenera. Ponieważ w tym przypadku zadanie jest uruchomione bezpośrednio na maszynie uruchamiającej akcje GitHub, krok Uruchom testy w zadaniu może uzyskać dostęp do emulatora za pomocą localhost:8081 (8081 to port wystawiony przez emulator).

Krok Eksportowanie certyfikatu emulatora usługi Cosmos DB jest specyficzny dla aplikacji Java, ponieważ zestaw Java SDK usługi Azure Cosmos DB obecnie nie obsługuje HTTP trybu w emulatorze. Zmienna PROTOCOL środowiskowa jest ustawiona na https w sekcji services, a ten krok polega na eksportowaniu certyfikatu emulatora i jego importowaniu do magazynu kluczy Java. Dotyczy to również platformy .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.