Linux-baserad emulator – vNext (förhandsversion)

Gäller för: ✅ NoSQL

Nästa generation av Azure Cosmos DB-emulatorn är helt Linux-baserad och är tillgänglig som en Docker-container. Den stöder körning på en mängd olika processorer och operativsystem.

Viktigt!

Den här versionen av emulatorn stöder endast API:et för NoSQL i gateway-läge med en utvald delmängd funktioner. Mer information finns i funktionsstöd.

Förutsättningar

Docker

Installation

Hämta Docker-containeravbildningen med docker pull. Containeravbildningen publiceras till Microsoft Artifact Registry som mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview.

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

Körs

Om du vill köra containern använder du docker run. Därefter kan du använda docker ps för att verifiera att containern körs.

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>

Emulatorn innehåller två komponenter:

Data Explorer – Utforska data i emulatorn interaktivt. Som standard körs den här komponenten på port 1234.
Azure Cosmos DB emulator – en lokal version av Azure Cosmos DB-databastjänsten. Som standard körs den här komponenten på port 8081.

Emulatorns gatewayslutpunkt använder porten 8081 på adressen http://localhost:8081. Om du vill navigera till Data Explorer använder du adressen http://localhost:1234 i webbläsaren. Gatewayslutpunkten är vanligtvis tillgänglig omedelbart, men Data Explorer kan ta några sekunder att starta.

Hälsoavsökning

Emulatorn tillhandahåller en slutpunkt för hälsokontroll på port 8080. Använd den här slutpunkten för att avgöra när emulatorn är helt initierad och redo att acceptera begäranden.

Följande slutpunkter är tillgängliga:

http://localhost:8080/alive — Liveness-avsökning.
http://localhost:8080/ready — Beredskapsavsökning.
http://localhost:8080/status — Detaljerad status.

Kommentar

Det äldre loggmeddelandet System is now fully ready to accept requests genereras fortfarande för bakåtkompatibilitet men kan tas bort i en framtida version. Använd hälsoavsökningen för beredskapskontroller i stället.

HTTPS-läge

SDK:erna för .NET och Java stöder inte HTTP-läge i emulatorn. Eftersom den här versionen av emulatorn börjar med HTTP som standard måste du uttryckligen aktivera HTTPS när du startar containern (se nedan). För Java SDK måste du också installera certifikat.

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

När du använder HTTPS med bevarade datavolymer återskapar emulatorn automatiskt SSL-certifikat vid start, så du behöver inte hantera certifikatförnyelse.

Docker-kommandon

I följande tabell sammanfattas de tillgängliga Docker-kommandona för att konfigurera emulatorn. Den här tabellen beskriver motsvarande argument, miljövariabler, tillåtna värden, standardinställningar och beskrivningar av varje kommando.

Krav	Argument	Env	Tillåtna värden	Standardvärde	beskrivning
Skriv ut inställningarna till stdout från containern	`--help`, `-h`	Saknas	Saknas	Saknas	Visa information om tillgänglig konfiguration
Ange porten för Cosmos-slutpunkten	`--port [INT]`	HAMN	INT	8081	Porten för Cosmos-endpointen på containern. Du måste fortfarande publicera den här porten (till exempel `-p 8081:8081`).
Ange det protokoll som används av Cosmos-slutpunkten	`--protocol`	PROTOKOLL	`https` `http` `https-insecure`	`http`	Protokollet för Cosmos-slutpunkten på containern.
Aktivera datautforskaren	`--enable-explorer`	Aktivera Utforskare	`true`, `false`	`true`	Aktivera körning av Cosmos Data Explorer på samma container.
Ange den port som används av datautforskaren	`--explorer-port`	Utforskarport	INT	1234	Porten för Cosmos Data Explorer på containern. Du måste fortfarande publicera den här porten (till exempel `-p 1234:1234`).
Ange det protokoll som används av datautforskaren	`--explorer-protocol`	EXPLORER_PROTOCOL	`https` `http` `https-insecure`	`<the value of --protocol>`	Protokollet för Cosmos Data Explorer i containern. Standardinställningen för protokoll på Cosmos-slutpunkten.
Anpassa gatewayens offentliga slutpunkt	`--gateway-endpoint`	GATEWAY_PUBLIC_ENDPOINT	Saknas	`localhost`	Slutpunkten för den offentliga gatewayen. Standardinställningen är `localhost`.
Ange nyckeln via filen	`--key-file [PATH]`	NYCKELFIL	VÄG	`<default secret>`	Åsidosätt standardnyckeln med nyckeln som anges i filen. Du måste montera den här filen i containern (till exempel, om KEY_FILE=/mykey, skulle du lägga till ett alternativ som följande i din docker run: `--mount type=bind,source=./myKey,target=/myKey`)
Ange datasökvägen	`--data-path [PATH]`	DATA_PATH	VÄG	`/data`	Ange en katalog för data. Används ofta med `docker run --mount` alternativet (om du till exempel DATA_PATH=/usr/cosmos/data lägger du till ett alternativ som liknar följande i docker-körningen: `--mount type=bind,source=./.local/data,target=/usr/cosmos/data`)
Ange den certifikatsökväg som ska användas för https	`--cert-path [PATH]`	CERT_PATH	VÄG	`<default cert>`	Ange en sökväg till ett certifikat för att skydda trafiken. Du måste montera den här filen i containern (om CERT_PATH=/mycert.pfx, till exempel, lägger du till ett alternativ som liknar följande i din docker-körning: `--mount type=bind,source=./mycert.pfx,target=/mycert.pfx`)
Ange den certifikathemlighet som ska användas för https	Saknas	CERTIFIKAT_HEMLIGHET	sträng	`<default secret>`	Hemligheten för certifikatet som anges på CERT_PATH.
Ange loggnivå	`--log-level [LEVEL]`	LOGGNINGSNIVÅ	`quiet`, `error`, `warn`, `info`, `debugtrace`	`info`	Utförligheten hos loggar som genereras av emulatorn och datautforskaren.
Aktivera OpenTelemetry OTLP-exportör	`--enable-otlp`	ENABLE_OTLP_EXPORTER	`true`, `false`	`false`	Aktivera OpenTelemetry-integration.
Aktivera konsolexportör	`--enable-console`	ENABLE_CONSOLE_EXPORTER	`true`, `false`	`false`	Aktivera konsolutdata för telemetridata (användbart för felsökning).
Aktivera utförligt läge	`--verbose`	UTFÖRLIG	`true`, `false`	`false`	Aktivera utförligt läge för att skriva ut PostgreSQL-loggar (pglog) till konsolen. Användbart för felsökning.
Ange frågebuffertstorlek	`--query-buffer-size`	QUERY_BUFFER_SIZE_KB	INT	4 096 (4 MB), max 65536 (64 MB)	Maximal storlek i KB för frågeresultatbuffertar. Öka detta om du stöter på HTTP 500-fel på stora frågor.
Aktivera diagnostikinformation som skickas till Microsoft	`--enable-telemetry`	AKTIVERA TELEMETRI	`true`, `false`	`true`	Aktivera sändning av användningsdata till Microsoft för att hjälpa oss att förbättra emulatorn.

Funktionsstöd

Den här emulatorn är i aktiv utveckling och förhandsversion. Därför stöds inte alla Azure Cosmos DB funktioner. Vissa funktioner kommer inte heller att stödjas i framtiden. Den här tabellen innehåller tillståndet för olika funktioner och deras supportnivå.

Funktion	Stöd
Batch-API	✅ Stödd
Bulk-API	✅ Stödd
Ändringsflöde	✅ Stödd
Skapa och läsa dokument med utf-data	✅ Stödd
Skapa samling	✅ Stödd
Skapa samling två gånger i konflikt	✅ Stödd
Skapa samling med anpassad indexprincip	⚠️ No-op
Skapa samling med ttl-förfallodatum	✅ Stödd
Skapa databas	✅ Stödd
Skapa databas två gånger i konflikt	✅ Stödd
Skapa dokument	✅ Stödd
Skapa partitionerad samling	✅ Stödd
Ta bort samling	✅ Stödd
Ta bort databas	✅ Stödd
Ta bort dokument	✅ Stödd
Hämta och ändra insamlingsprestanda	⚠️ Ännu inte implementerad
Infoga stort dokument	✅ Stödd
Korrigera dokument	✅ Stödd
Fråga partitionerad samling parallellt	⚠️ Ännu inte implementerad
Fråga med aggregeringar	✅ Stödd
Sök och filtrera	✅ Stödd
Fråga med filter och projektion	✅ Stödd
Fråga med likhet	✅ Stödd
Fråga med likhet på id	✅ Stödd
Fråga med sammanfogningar	✅ Stödd
Fråga med ordning efter	✅ Stödd
Fråga med ORDER BY för en partitionerad datainsamling	✅ Stödd
Fråga med ordning efter tal	✅ Stödd
Fråga med ordning efter strängar	✅ Stödd
Fråga med sidindelning	✅ Stödd
Fråga med datumtider för intervalloperatorer	✅ Stödd
Fråga med intervalloperatorer om tal	✅ Stödd
Fråga med intervalloperatorer på strängar	✅ Stödd
Fråga med enkel koppling	✅ Stödd
Fråga med strängmatematik- och matrisoperatorer	✅ Stödd
Fråga med underdokument	✅ Stödd
Fråga med två kopplingar	✅ Stödd
Fråga med två kopplingar och filter	✅ Stödd
Läs samling	✅ Stödd
Läs samlingsfeed	⚠️ Ännu inte implementerad
Läs databas	✅ Stödd
Läsa databaserflöde	⚠️ Ännu inte implementerad
Läsa dokument	✅ Stödd
Läs dokumentfeed	✅ Stödd
Ersätt dokument	✅ Stödd
Enheter för programbegäran	⚠️ Ännu inte implementerad
Lagrade procedurer	❌ Inte planerat
Utlösare	❌ Inte planerat
UDF:er	❌ Inte planerat
Uppdatera samling	⚠️ No-op
Uppdatera dokument	✅ Stödd
Erbjudandeslutpunkt	⚠️ No-op
Användares slutpunkt	⚠️ No-op
Behörighetsslutpunkt	⚠️ No-op
Klientkrypteringsnycklar (CEK)	⚠️ Ingen åtgärd

Kommentar

Funktioner markerade No-op accepterar begäranden och returnerar giltiga HTTP-statuskoder men kör inte den underliggande åtgärden. Koden bryts inte, men är inte beroende av dessa funktioner för funktionellt beteende. Anpassade indexprinciper och samlingsuppdateringar accepteras för kompatibilitet, men frågor optimeras inte av anpassade index.

Begränsningar

Förutom funktioner som ännu inte stöds eller inte planeras innehåller följande lista aktuella begränsningar för emulatorn.

.NET SDK för Azure Cosmos DB stöder inte masskörning i emulatorn.
Om du får HTTP 500-fel på stora frågeresultat ökar du frågebuffertens storlek med --query-buffer-size flaggan eller QUERY_BUFFER_SIZE_KB miljövariabeln. Standardvärdet är 4096 KB (4 MB) och det maximala är 65536 KB (64 MB).

Installera certifikat för Java SDK

När du använder Java SDK för Azure Cosmos DB med den här versionen av emulatorn i https-läge, är det nödvändigt att installera certifikaten i ditt lokala Java förtroendearkiv.

Hämta certifikat

Kör följande i ett bash fönster:

# 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

Installera certifikat

Gå till katalogen för java-installationen där cacerts filen finns (ersätt nedan med rätt katalog):

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

Importera certifikatet (du kan bli ombedd att ange ett lösenord, standardvärdet är "changeit"):

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

Om du får ett fel eftersom aliaset redan finns tar du bort det och kör sedan ovanstående igen:

keytool -cacerts -delete -alias cosmos_emulator

OpenTelemetry-stöd

OpenTelemetry är ett ramverk för observerbarhet med öppen källkod som tillhandahåller en samling verktyg, API:er och SDK:er för instrumentering, generering, insamling och export av telemetridata. OpenTelemetry Protocol (OTLP) är det protokoll som används av OpenTelemetry för att överföra telemetridata mellan komponenter.

Du kan använda OpenTelemetry med emulatorn för att övervaka och spåra ditt program. Emulatorn stöder telemetrialternativ som kan konfigureras via miljövariabler eller kommandoradsflaggor när du kör Docker-containern.

Emulatorn exporterar följande mått. Dessa är tillgängliga via alla måttserverdelar som stöder OTLP och ger värdefulla insikter om databasens prestanda och hälsa:

Begärandefrekvenser: Visar trafikmönstren för olika åtgärdstyper
Exekveringstider för sökfrågor: Mäter den tid det tar att exekvera olika sökfrågor
Resursanvändning: MÅTT för CPU, minnesanvändning och anslutningspool
Felfrekvens: Spårning av fel efter typ och slutpunkt

Kommentar

Emulatorn stöder villkorsstyrd TLS för OTLP-exportören, så att du kan integrera med observerbarhetsplattformar som kräver säkra anslutningar.

Detaljerade instruktioner med exempel finns på GitHub-lagringsplatsen.

Använda i arbetsflödet för kontinuerlig integrering

Det finns många fördelar med att använda Docker-containrar i CI/CD-pipelines, särskilt för tillståndskänsliga system som databaser. Detta kan bero på kostnadseffektivitet, prestanda, tillförlitlighet och konsekvens i dina testsviter.

Emulatorn kan införlivas som en del av CI/CD-pipelines. Du kan referera till den här GitHub-lagringsplatsen som innehåller exempel på hur du använder emulatorn som en del av ett GitHub Actions CI-arbetsflöde för .NET, Python, Java och Go-program på både x64 och ARM64-arkitekturer (demonstreras för Linux-löpare med hjälp av ubuntu).

Här är ett exempel på ett GitHub Actions CI-arbetsflöde som visar hur du konfigurerar emulatorn som en GitHub Actions tjänstcontainer som en del av ett jobb i arbetsflödet. GitHub tar hand om att starta Docker-containern och förstör den när jobbet har slutförts, utan att behöva utföra manuella åtgärder (till exempel med kommandot 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

Det här jobbet körs på en Ubuntu-körning och använder Docker-bilden mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview som en tjänstcontainer. Den använder miljövariabler för att konfigurera reťazec pripojenia, databasnamn och containernamn. Eftersom jobbet i det här fallet körs direkt på GitHub Actions runner-datorn kan Run tests-steget i jobbet komma åt emulatorn via localhost:8081 (8081 är porten som exponeras av emulatorn).

Steget Exportera Cosmos DB-emulatorcertifikat är specifikt för Java program eftersom Azure Cosmos DB Java SDK för närvarande inte stöder HTTP läge i emulatorn. Miljövariabeln PROTOCOL är inställd på https i avsnittet services och det här steget exporterar emulatorcertifikatet och importerar det till Java nyckelarkiv. Samma sak gäller även för .NET.

Rapporteringsproblem

Om du får problem med att använda den här versionen av emulatorn öppnar du ett problem på GitHub-lagringsplatsen (https://github.com/Azure/azure-cosmos-db-emulator-docker) och taggar den med etiketten cosmosEmulatorVnextPreview.

Feedback

Var den här sidan till hjälp?

Last updated on 2026-04-21

Linux-baserad emulator – vNext (förhandsversion)

Förutsättningar

Installation

Körs

Hälsoavsökning

HTTPS-läge

Docker-kommandon

Funktionsstöd

Begränsningar

Installera certifikat för Java SDK

Hämta certifikat

Installera certifikat

OpenTelemetry-stöd

Använda i arbetsflödet för kontinuerlig integrering

Rapporteringsproblem

Feedback

Ytterligare resurser