Linux-baserad emulator – vNext (förhandsversion)

2025-04-16

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 gatewayläge, med en utvald delmängd av funktioner. Mer information finns i funktionsstöd.

Förutsättningar

Docker

Installation

Hämta Docker-containeravbildningen med docker pull. Containeravbildningen publiceras till Microsofts artefaktregister 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 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>

Kommentar

Emulatorn består av två komponenter:

Datautforskaren – utforska data i emulatorn interaktivt. Som standard körs detta på porten 1234
Azure Cosmos DB-emulator – en lokal version av Azure Cosmos DB-databastjänsten. Som standard körs detta på port 8081.

Emulatorns gatewayslutpunkt är vanligtvis tillgänglig på porten 8081 på adressen http://localhost:8081. Om du vill navigera till datautforskaren använder du adressen http://localhost:1234 i webbläsaren. Det kan ta några sekunder innan datautforskaren är tillgänglig. Gatewayslutpunkten är vanligtvis tillgänglig omedelbart.

Viktigt!

.NET- och Java-SDK:erna 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 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol https

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 i containern. Du måste fortfarande publicera den här porten (till exempel `-p 1234:1234`).
Användaren bör kunna ange det protokoll som används av utforskaren, annars som standard vad Cosmos-slutpunkten använder	`--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.
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`, `debug`, `trace`	`info`	Utförligheten i loggar som genereras av emulatorn och datautforskaren.
Aktivera diagnostikinformation som skickas till Microsoft	`--enable-telemetry`	AKTIVERA TELEMETRI	`true`, `false`	`true`	Aktivera sändning av loggar 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	⚠️ Ännu inte implementerad
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	⚠️ Ännu inte implementerad
Sök och filtrera	⚠️ Ännu inte implementerad
Fråga med filter och projektion	⚠️ Ännu inte implementerad
Fråga med likhet	✅ Stödd
Fråga med likhet på id	✅ Stödd
Fråga med sammanfogningar	⚠️ Ännu inte implementerad
Fråga med ordning efter	✅ Stödd
Fråga med ORDER BY för en partitionerad datainsamling	⚠️ Ännu inte implementerad
Fråga med ordning efter tal	✅ Stödd
Fråga med ordning efter strängar	⚠️ Ännu inte implementerad
Fråga med sidindelning	⚠️ Ännu inte implementerad
Fråga med datumtider för intervalloperatorer	⚠️ Ännu inte implementerad
Fråga med intervalloperatorer om tal	⚠️ Ännu inte implementerad
Fråga med intervalloperatorer på strängar	⚠️ Ännu inte implementerad
Fråga med enkel koppling	⚠️ Ännu inte implementerad
Fråga med strängmatematik- och matrisoperatorer	⚠️ Ännu inte implementerad
Fråga med underdokument	⚠️ Ännu inte implementerad
Fråga med två kopplingar	⚠️ Ännu inte implementerad
Fråga med två kopplingar och filter	⚠️ Ännu inte implementerad
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	⚠️ Ännu inte implementerad
Uppdatera dokument	✅ Stödd

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.
.NET- och Java-SDK:erna stöder inte HTTP-läge i emulatorn.

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

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 det här GitHub-lagringsplatsen som ger exempel på hur man 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-arkitekturerna (demonstrerat för Linux-exekverare med 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 genom att docker run använda kommandot).

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 anslutningssträngen, databasnamnet och containernamnet. Eftersom jobbet i det här fallet körs direkt på GitHub Actions-löpardatorn, kan steget Kör tester i jobbet komma åt emulatorn, som är åtkomlig 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 anges till https i services avsnittet och det här steget exporterar emulatorcertifikatet och importerar det till Java-nyckelarkivet. Detsamma 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.