Emulátor založený na Linuxu – vNext (Preview)

Nová generace emulátoru služby Azure Cosmos DB je zcela založená na Linuxu a je k dispozici jako kontejner Dockeru. Podporuje spouštění na široké škále procesorů a operačních systémů.

Důležité

Tato verze emulátoru podporuje pouze rozhraní API pro NoSQL v režimu brány s výběrovou podmnožinou funkcí. Další informace najdete v podpoře funkcí.

Požadavky

Docker

Instalace

Získejte image kontejneru Dockeru pomocí docker pull. Image kontejneru se publikuje do Registr artefaktů Microsoft jako mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview.

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

Spuštěno

Ke spuštění kontejneru použijte docker run. Potom použijte docker ps k ověření, že je kontejner spuštěný.

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>

Poznámka:

Emulátor se skládá ze dvou komponent:

Průzkumník dat – interaktivně prozkoumejte data v emulátoru. Ve výchozím nastavení se spustí na portu. 1234
Emulátor služby Azure Cosmos DB – místní verze databázové služby Azure Cosmos DB Ve výchozím nastavení se spustí na portu 8081.

Koncový bod brány emulátoru je obvykle k dispozici na portu 8081 na adrese http://localhost:8081. Pokud chcete přejít do Průzkumníka dat, použijte adresu http://localhost:1234 ve webovém prohlížeči. Dostupnost Průzkumníka dat může trvat několik sekund. Koncový bod brány je obvykle k dispozici okamžitě.

Důležité

Sady .NET a Java SDK nepodporují režim HTTP v emulátoru. Vzhledem k tomu, že tato verze emulátoru ve výchozím nastavení začíná protokolem HTTP, budete muset při spuštění kontejneru explicitně povolit PROTOKOL HTTPS (viz níže). Pro sadu Java SDK budete také muset nainstalovat certifikáty.

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

Příkazy Dockeru

Následující tabulka shrnuje dostupné příkazy Dockeru pro konfiguraci emulátoru. Tato tabulka podrobně popisuje odpovídající argumenty, proměnné prostředí, povolené hodnoty, výchozí nastavení a popisy jednotlivých příkazů.

Požadavek	Argument	Prostředí	Povolené hodnoty	Výchozí	Popis
Tisk nastavení do stdoutu z kontejneru	`--help`, `-h`	–	–	–	Zobrazení informací o dostupné konfiguraci
Nastavení portu koncového bodu Cosmos	`--port [INT]`	přístav	INT	8081	Port koncového bodu Cosmos v kontejneru. Tento port stále potřebujete publikovat (například `-p 8081:8081`).
Zadání protokolu používaného koncovým bodem cosmos	`--protocol`	PROTOKOL	`https`, , `httphttps-insecure`	`http`	Protokol koncového bodu Cosmos v kontejneru.
Povolení Průzkumníka dat	`--enable-explorer`	POVOLIT_PRŮZKUMNÍKA	`true`, `false`	`true`	Povolte spuštění Průzkumníka dat Cosmos ve stejném kontejneru.
Nastavení portu používaného Průzkumníkem dat	`--explorer-port`	EXPLORER_PORT	INT	1 234	Port Průzkumníka dat systému Cosmos v kontejneru. Tento port stále potřebujete publikovat (například `-p 1234:1234`).
Uživatel může zadat protokol používaný průzkumníkem, jinak bude automaticky použit protokol, který používá koncový bod Cosmos.	`--explorer-protocol`	PROTOKOL_PRŮZKUMNÍKA	`https`, , `httphttps-insecure`	`<the value of --protocol>`	Protokol Průzkumníka dat Cosmos v kontejneru. Ve výchozím nastavení se nastaví protokol v koncovém bodu Cosmos.
Přizpůsobte veřejný koncový bod brány	`--gateway-endpoint`	GATEWAY_PUBLIC_ENDPOINT	–	`localhost`	Koncový bod veřejné brány. Výchozí hodnota je `localhost`.
Zadání klíče prostřednictvím souboru	`--key-file [PATH]`	SOUbor_KLÍČe	CESTA	`<default secret>`	Přepsat výchozí klíč klíčem, který je zadán v souboru. Tento soubor musíte připojit do kontejneru (například pokud KEY_FILE=/mykey, přidejte do svého dockeru následující možnost: `--mount type=bind,source=./myKey,target=/myKey`
Nastavení cesty k datům	`--data-path [PATH]`	DATA_CESTA	CESTA	`/data`	Zadejte adresář pro data. Často se používá s `docker run --mount` možností (například pokud DATA_PATH=/usr/cosmos/data, přidejte do svého dockeru následující možnost: `--mount type=bind,source=./.local/data,target=/usr/cosmos/data`
Zadejte cestu certifikátu, která se má použít pro https.	`--cert-path [PATH]`	CERT_PATH	CESTA	`<default cert>`	Zadejte cestu k certifikátu pro zabezpečení provozu. Tento soubor musíte připojit do kontejneru (například pokud CERT_PATH=/mycert.pfx, přidejte do svého dockeru následující možnost: `--mount type=bind,source=./mycert.pfx,target=/mycert.pfx`
Zadejte tajný kód certifikátu, který se má použít pro https.	–	CERTIFIKÁT_TAJNÝ	řetězec	`<default secret>`	Tajný klíč certifikátu zadaného v CERT_PATH.
Nastavte úroveň protokolu	`--log-level [LEVEL]`	ÚROVEŇ_ZÁZNAMU	`quiet`, `error`, `warn`, `info`, , `debugtrace`	`info`	Úroveň podrobností protokolů generovaných emulátorem a průzkumníkem dat.
Povolení exportéru OpenTelemetry OTLP	`--enable-otlp`	ENABLE_OTLP_EXPORTER	`true`, `false`	`false`	Povolte integraci OpenTelemetry.
Povolení exportéru konzoly	`--enable-console`	ENABLE_CONSOLE_EXPORTER	`true`, `false`	`false`	Povolení výstupu telemetrických dat konzoly (užitečné pro ladění)
Povolení odesílání diagnostických informací do Microsoftu	`--enable-telemetry`	Povolit Telemetrii	`true`, `false`	`true`	Povolte odesílání dat o využití do Microsoftu, abychom mohli vylepšit emulátor.

Podpora funkcí

Tento emulátor je v aktivním vývoji a verzi Preview. V důsledku toho se nepodporují všechny funkce služby Azure Cosmos DB. Některé funkce nebudou v budoucnu podporovány. Tato tabulka obsahuje stav různých funkcí a jejich úroveň podpory.

Funkce	Technická podpora
Batch API	✅ Podporovaný
Hromadné rozhraní API	✅ Podporovaný
Kanál změn	✅ Podporovaný
Vytvoření a čtení dokumentu s daty utf	✅ Podporovaný
Vytvoření kolekce	✅ Podporovaný
Vytvoření kolekce dvakrát v konfliktu	✅ Podporovaný
Vytvoření kolekce pomocí vlastních zásad indexu	⚠️ Ještě není implementováno
Vytvoření kolekce s vypršením platnosti ttl	✅ Podporovaný
Vytvoření databáze	✅ Podporovaný
Vytvoření databáze dvakrát v konfliktu	✅ Podporovaný
Vytvoření dokumentu	✅ Podporovaný
Vytvoření dělené kolekce	✅ Podporovaný
Odstranění kolekce	✅ Podporovaný
Odstranění databáze	✅ Podporovaný
Odstranění dokumentu	✅ Podporovaný
Získání a změna výkonu shromažďování	⚠️ Ještě není implementováno
Vložení velkého dokumentu	✅ Podporovaný
Oprava dokumentu	✅ Podporovaný
Dotaz na rozdělenou kolekci paralelně	⚠️ Ještě není implementováno
Dotazování s agregacemi	✅ Podporovaný
Dotazování s filtrováním	✅ Podporovaný
Dotaz s filtrováním a projekcí	✅ Podporovaný
Dotaz s rovností	✅ Podporovaný
Dotaz s rovností na id	✅ Podporovaný
Dotazování pomocí spojení	✅ Podporovaný
Dotazování s pořadím podle	✅ Podporovaný
Dotaz s řazením podle particionované kolekce	✅ Podporovaný
Dotaz s pořadím podle čísel	✅ Podporovaný
Dotazování s pořadím podle řetězců	✅ Podporovaný
Dotaz se stránkováním	✅ Podporovaný
Dotaz s operátory rozsahu datum a čas	✅ Podporovaný
Dotazy na čísla pomocí operátorů rozsahu	✅ Podporovaný
Dotazování s operátory rozsahu v řetězcích	✅ Podporovaný
Dotaz s jedním JOINem	✅ Podporovaný
Dotaz s operátory pro matematiku řetězců a pole	✅ Podporovaný
Dotazování pomocí vnořených dokumentů	✅ Podporovaný
Dotazování se dvěma spojeními	✅ Podporovaný
Dotazování se dvěma spojeními a filtrováním	✅ Podporovaný
Čtení kolekce	✅ Podporovaný
Čtení zdroje kolekce	⚠️ Ještě není implementováno
Čtení databáze	✅ Podporovaný
Čtení databázového zdroje	⚠️ Ještě není implementováno
Čtení dokumentu	✅ Podporovaný
Čtení dokumentového kanálu	✅ Podporovaný
Nahradit dokument	✅ Podporovaný
Jednotky žádostí	⚠️ Ještě není implementováno
Uložené procedury	❌ Neplánované
Triggery	❌ Neplánované
Funkce definované uživatelem	❌ Neplánované
Aktualizace kolekce	⚠️ Ještě není implementováno
Aktualizace dokumentu	✅ Podporovaný

Omezení

Kromě funkcí, které nejsou dosud podporovány nebo nejsou plánovány, zahrnuje následující seznam současná omezení emulátoru.

Sada .NET SDK pro službu Azure Cosmos DB nepodporuje hromadné spouštění v emulátoru.

Instalace certifikátů pro Java SDK

Při použití sady Java SDK pro Azure Cosmos DB s touto verzí emulátoru v režimu https je nutné nainstalovat jeho certifikáty do místního úložiště důvěryhodných certifikátů Java.

Získání certifikátu

bash V okně spusťte následující příkaz:

# 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

Instalace certifikátu

Přejděte do adresáře vaší instalace java, kde cacerts se nachází soubor (nahraďte ho správným adresářem):

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

Importujte certifikát (můžete být požádáni o heslo, výchozí hodnota je "changeit"):

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

Pokud se zobrazí chyba, protože alias už existuje, odstraňte ho a spusťte výše uvedené příkazy znovu:

keytool -cacerts -delete -alias cosmos_emulator

Podpora OpenTelemetry

OpenTelemetry je opensourcová architektura pozorovatelnosti, která poskytuje kolekci nástrojů, rozhraní API a sad SDK pro instrumentaci, generování, shromažďování a export telemetrických dat. OpenTelemetry Protocol (OTLP) je protokol používaný OpenTelemetry k přenosu telemetrických dat mezi komponentami.

K monitorování a trasování aplikace můžete použít OpenTelemetry s emulátorem. Emulátor podporuje možnosti telemetrie, které je možné nakonfigurovat prostřednictvím proměnných prostředí nebo příznaků příkazového řádku při spuštění kontejneru Dockeru.

Emulátor exportuje následující metriky. K dispozici jsou prostřednictvím jakéhokoli back-endu metrik, který podporuje OTLP, a poskytuje cenné přehledy o výkonu a stavu databáze:

Frekvence požadavků: Zobrazuje vzory provozu pro různé typy operací.
Časy provádění dotazů: Měří čas potřebný ke spouštění různých dotazů.
Využití prostředků: metriky procesoru, využití paměti a fondu připojení
Míry chyb: Sledování chyb podle typu a koncového bodu

Podrobné pokyny s příklady jsou k dispozici v úložišti GitHub.

Použití v pracovním postupu kontinuální integrace

Používání kontejnerů Dockeru v kanálech CI/CD má spoustu výhod, zejména pro stavové systémy, jako jsou databáze. Může se jednat o nákladovou efektivitu, výkon, spolehlivost a konzistenci testovacích sad.

Emulátor je možné začlenit jako součást kanálů CI/CD. Můžete se podívat na toto úložiště GitHub , které poskytuje příklady použití emulátoru jako součást pracovního postupu CI GitHub Actions pro aplikace .NET, Python, Java a Go v obou x64 architekturách ARM64 (demonstrováno pro Linux Runner pomocí ubuntu).

Tady je příklad pracovního postupu CI GitHub Actions, který ukazuje, jak nakonfigurovat emulátor jako kontejner služby GitHub Actions jako součást úlohy v pracovním postupu. GitHub se postará o spuštění kontejneru Dockeru a po dokončení úlohy ho zničí bez nutnosti ručního zásahu docker run (například pomocí příkazu).

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

Tato úloha běží na spouštěči Ubuntu a používá mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview image Dockeru jako kontejner služby. Používá proměnné prostředí ke konfiguraci připojovacího řetězce, názvu databáze a názvu kontejneru. Vzhledem k tomu, že úloha běží přímo na počítači spouštěče GitHub Actions, může krok spuštění testů v úloze přistupovat k emulátoru pomocí localhost:8081 (8081 je port vystavený emulátorem).

Krok Export certifikátu emulátoru služby Cosmos DB je specifický pro aplikace v Javě, protože sada Azure Cosmos DB Java SDK v současné době nepodporuje HTTP režim v emulátoru. Proměnná PROTOCOL prostředí je nastavená v httpsservices části a tento krok exportuje certifikát emulátoru a importuje ho do úložiště klíčů Java. Totéž platí i pro .NET.

Hlášení problémů

Pokud narazíte na problémy s používáním této verze emulátoru, otevřete problém v úložišti GitHub (https://github.com/Azure/azure-cosmos-db-emulator-docker) a označte ho popiskem cosmosEmulatorVnextPreview.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-11-19