Op Linux gebaseerde emulator - vNext (preview)

Van toepassing op: ✅ NoSQL

De volgende generatie van de Azure Cosmos DB emulator is volledig op Linux gebaseerd en is beschikbaar als een Docker-container. Het ondersteunt uitvoering op een groot aantal processors en besturingssystemen.

Belangrijk

Deze versie van de emulator ondersteunt alleen de API voor NoSQL in gatewaymodus met een selecte subset van functies. Zie de functieondersteuning voor meer informatie.

Vereisten

Docker

Installatie

Haal de Docker-container-image op met docker pull. De containerimage wordt gepubliceerd in het Microsoft Artifact Registry onder de naam mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview.

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

Hardlopen

Als u de container wilt uitvoeren, gebruikt u docker run. Gebruik daarna docker ps om te controleren of de container wordt uitgevoerd.

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>

De emulator bevat twee onderdelen:

Data Explorer - De gegevens in de emulator interactief verkennen. Dit onderdeel wordt standaard uitgevoerd op poort 1234.
Azure Cosmos DB emulator : een lokale versie van de Azure Cosmos DB-databaseservice. Dit onderdeel wordt standaard uitgevoerd op poort 8081.

Het eindpunt van de emulatorgateway maakt gebruik van poort 8081 op het adres http://localhost:8081. Als u naar de Data Explorer wilt navigeren, gebruikt u het adres http://localhost:1234 in uw webbrowser. Het gateway-eindpunt is doorgaans onmiddellijk beschikbaar, maar Data Explorer kan enkele seconden duren om te starten.

Gezondheidsonderzoek

De emulator maakt een statustesteindpunt beschikbaar op poort 8080. Gebruik dit eindpunt om te bepalen wanneer de emulator volledig is geïnitialiseerd en gereed is om aanvragen te accepteren.

De volgende eindpunten zijn beschikbaar:

http://localhost:8080/alive — levensonde.
http://localhost:8080/ready — Gereedheidstest.
http://localhost:8080/status — Gedetailleerde status.

Notitie

Het verouderde logboekbericht System is now fully ready to accept requests wordt nog steeds verzonden voor compatibiliteit met eerdere versies, maar kan in een toekomstige versie worden verwijderd. Gebruik in plaats daarvan de gezondheidstest voor gereedheidscontroles.

HTTPS-modus

De .NET- en Java SDK's bieden geen ondersteuning voor de HTTP-modus in de emulator. Omdat deze versie van de emulator standaard met HTTP begint, moet u HTTPS expliciet inschakelen bij het starten van de container (zie hieronder). Voor de Java SDK moet u ook certificaten installeren.

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

Wanneer u HTTPS gebruikt met persistente gegevensvolumes, genereert de emulator automatisch SSL-certificaten bij het opstarten, zodat u certificaatvernieuwing niet hoeft te beheren.

Docker-opdrachten

De volgende tabel bevat een overzicht van de beschikbare Docker-opdrachten voor het configureren van de emulator. In deze tabel worden de bijbehorende argumenten, omgevingsvariabelen, toegestane waarden, standaardinstellingen en beschrijvingen van elke opdracht beschreven.

Vereiste	Argh	Omgeving	Toegestane waarden	Verstek	Beschrijving
De instellingen afdrukken naar stdout vanuit de container	`--help`, `-h`	N.v.t.	N.v.t.	N.v.t.	Informatie weergeven over de beschikbare configuratie
De poort van het Cosmos-eindpunt instellen	`--port [INT]`	POORT	INT	8081	De poort van het Cosmos-eindpunt op de container. U moet deze poort nog steeds publiceren (bijvoorbeeld `-p 8081:8081`).
Geef het protocol op dat wordt gebruikt door het Cosmos-eindpunt	`--protocol`	PROTOCOL	`https`, `httphttps-insecure`	`http`	Het protocol van het Cosmos-eindpunt in de container.
Data Explorer inschakelen	`--enable-explorer`	INSCHAKELEN_EXPLORER	`true`, `false`	`true`	Schakel het uitvoeren van de Cosmos-Data Explorer in op dezelfde container.
De poort instellen die wordt gebruikt door data explorer	`--explorer-port`	EXPLORER_PORT	INT	1234	De poort van de Cosmos-Data Explorer op de container. U moet deze poort nog steeds publiceren (bijvoorbeeld `-p 1234:1234`).
Geef het protocol op dat wordt gebruikt door data explorer	`--explorer-protocol`	EXPLORER_PROTOCOL	`https`, `httphttps-insecure`	`<the value of --protocol>`	Het protocol van de Cosmos-Data Explorer op de container. De standaardwaarden zijn ingesteld volgens de protocolinstellingen op het Cosmos-eindpunt.
Het openbare eindpunt van de gateway aanpassen	`--gateway-endpoint`	PUBLIEK GATEWAY-EINDPUNT	N.v.t.	`localhost`	Het openbare gateway-eindpunt. Standaardwaarde is `localhost`.
De sleutel opgeven via bestand	`--key-file [PATH]`	SLEUTEL_BESTAND	PAD	`<default secret>`	Overschrijf de standaardsleutel met de sleutel die is opgegeven in het bestand. U moet dit bestand koppelen aan de container (bijvoorbeeld als KEY_FILE=/mykey, voegt u een optie zoals het volgende toe aan uw Docker-uitvoering: `--mount type=bind,source=./myKey,target=/myKey`)
Het gegevenspad instellen	`--data-path [PATH]`	gegevenspad	PAD	`/data`	Geef een map op voor gegevens. Vaak gebruikt met de optie `docker run --mount` (bijvoorbeeld als DATA_PATH=/usr/cosmos/data, voegt u een optie zoals de volgende toe aan uw Docker-run-command: `--mount type=bind,source=./.local/data,target=/usr/cosmos/data`)
Geef het certificaatpad op dat moet worden gebruikt voor https	`--cert-path [PATH]`	CERT_PATH	PAD	`<default cert>`	Geef een pad naar een certificaat op voor het beveiligen van verkeer. U moet dit bestand koppelen aan de container (bijvoorbeeld als CERT_PATH=/mycert.pfx, voegt u een optie toe zoals het volgende aan uw Docker-uitvoering: `--mount type=bind,source=./mycert.pfx,target=/mycert.pfx`)
Geef het certificaatgeheim op dat moet worden gebruikt voor https	N.v.t.	CERT_SECRET	tekenreeks	`<default secret>`	Het geheim voor het certificaat dat is opgegeven in CERT_PATH.
Het logboekniveau instellen	`--log-level [LEVEL]`	LOGNIVEAU	`quiet`, , `errorwarn`, `info`, , , `debugtrace`	`info`	De uitgebreidheid van logboeken die worden verzonden door de emulator en Data Explorer.
OpenTelemetry OTLP-exporteur inschakelen	`--enable-otlp`	ENABLE_OTLP_EXPORTER	`true`, `false`	`false`	OpenTelemetry-integratie inschakelen.
Consoleexporteur inschakelen	`--enable-console`	ENABLE_CONSOLE_EXPORTER	`true`, `false`	`false`	Console-uitvoer van telemetriegegevens inschakelen (handig voor foutopsporing).
Uitgebreide modus inschakelen	`--verbose`	LANGDRADIG	`true`, `false`	`false`	Schakel de uitgebreide modus in om PostgreSQL-logboeken (pglog) naar de console af te drukken. Handig voor foutopsporing.
Grootte van querybuffer instellen	`--query-buffer-size`	QUERY_BUFFER_SIZE_KB	INT	4096 (4 MB), max. 65536 (64 MB)	De maximale grootte in kB voor queryresultaatbuffers. Verhoog dit als u HTTP 500-fouten ondervindt voor grote query's.
Diagnostische gegevens die naar Microsoft worden verzonden inschakelen	`--enable-telemetry`	TELEMETRIE_INSCHAKELEN	`true`, `false`	`true`	Schakel het verzenden van gebruiksgegevens in naar Microsoft om ons te helpen de emulator te verbeteren.

Functieondersteuning

Deze emulator bevindt zich in actieve ontwikkeling en preview. Hierdoor worden niet alle Azure Cosmos DB functies ondersteund. Sommige functies worden ook in de toekomst niet ondersteund. Deze tabel bevat de status van verschillende functies en hun ondersteuningsniveau.

Functie	Ondersteuning
Batch-API	✅ Ondersteund
Bulk-API	✅ Ondersteund
Wijzigingenfeed	✅ Ondersteund
Document maken en lezen met utf-gegevens	✅ Ondersteund
Verzameling maken	✅ Ondersteund
Twee keer een verzameling maken veroorzaakt een conflict	✅ Ondersteund
Verzameling maken met aangepast indexbeleid	⚠️ No-op
Verzameling maken met een TTL-verlooptijd	✅ Ondersteund
Database maken	✅ Ondersteund
Database twee maal aanmaken conflict	✅ Ondersteund
Document maken	✅ Ondersteund
Gepartitioneerde verzameling maken	✅ Ondersteund
Verzameling verwijderen	✅ Ondersteund
Database verwijderen	✅ Ondersteund
Document verwijderen	✅ Ondersteund
Prestaties van verzameling ophalen en wijzigen	⚠️ nog niet geïmplementeerd
Groot document invoegen	✅ Ondersteund
Patchdocument	✅ Ondersteund
Gepartitioneerde verzameling parallel opvragen	⚠️ nog niet geïmplementeerd
Queries met aggregaties	✅ Ondersteund
Query uitvoeren met en filteren	✅ Ondersteund
Query uitvoeren met en filteren en projectie	✅ Ondersteund
Query uitvoeren met gelijkheid	✅ Ondersteund
Vraag met gelijkheid op id	✅ Ondersteund
Queries met joins	✅ Ondersteund
Query met sortering op	✅ Ondersteund
Query met 'order by' voor gepartitioneerde verzameling	✅ Ondersteund
Query op getallen sorteren	✅ Ondersteund
Query uitvoeren met volgorde op tekenreeksen	✅ Ondersteund
Query met paginering	✅ Ondersteund
Query's uitvoeren met datumtijden van bereikoperators	✅ Ondersteund
Query's uitvoeren met bereikoperators op getallen	✅ Ondersteund
Query uitvoeren met range-operators op tekenreeksen	✅ Ondersteund
Query's uitvoeren met één join	✅ Ondersteund
Query met string-bewerkingen en array-operators	✅ Ondersteund
Query uitvoeren met subdocumenten	✅ Ondersteund
Query uitvoeren met twee joins	✅ Ondersteund
Query's uitvoeren met twee joins en filteren	✅ Ondersteund
Verzameling lezen	✅ Ondersteund
Verzamelingsfeed lezen	⚠️ nog niet geïmplementeerd
Database lezen	✅ Ondersteund
Database-feed lezen	⚠️ nog niet geïmplementeerd
Document lezen	✅ Ondersteund
Documentenfeed lezen	✅ Ondersteund
Document vervangen	✅ Ondersteund
Aanvraageenheden	⚠️ nog niet geïmplementeerd
Opgeslagen procedures	❌ Niet gepland
Triggermomenten	❌ Niet gepland
UDF's	❌ Niet gepland
Verzameling bijwerken	⚠️ No-op
Document bijwerken	✅ Ondersteund
Biedt eindpunt	⚠️ No-op
Eindpunt van gebruikers	⚠️ No-op
Eindpunt voor machtigingen	⚠️ No-op
Clientversleutelingssleutels (CEK)	⚠️ No-op

Notitie

Functies die zijn gemarkeerd als Nee-aanvragen accepteren en geldige HTTP-statuscodes retourneren, maar de onderliggende bewerking niet uitvoeren. Uw code wordt niet verbroken, maar is niet afhankelijk van deze functies voor functioneel gedrag. Aangepast indexbeleid en updates voor verzamelingen worden geaccepteerd voor compatibiliteit, maar query's worden niet geoptimaliseerd door aangepaste indexen.

Beperkingen

Naast functies die nog niet worden ondersteund of niet gepland, bevat de volgende lijst de huidige beperkingen van de emulator.

De .NET SDK voor Azure Cosmos DB biedt geen ondersteuning voor bulkuitvoering in de emulator.
Als u HTTP 500-fouten krijgt voor grote queryresultaten, verhoogt u de grootte van de querybuffer met de --query-buffer-size vlag of de QUERY_BUFFER_SIZE_KB omgevingsvariabele. De standaardwaarde is KB (4096MB) en het maximum is 465536 KB (64MB).

Certificaten installeren voor Java SDK

Wanneer u de Java SDK gebruikt voor Azure Cosmos DB met deze versie van de emulator in de https-modus, moet u de certificaten installeren in uw lokale Java vertrouwensarchief.

Certificaat ophalen

Voer in een bash venster het volgende uit:

# 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

Certificaat installeren

Navigeer naar de map van uw Java-installatie waar cacerts het bestand zich bevindt (vervang hieronder door de juiste map):

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

Importeer het certificaat (mogelijk wordt u om een wachtwoord gevraagd, de standaardwaarde is changeit):

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

Als er een fout optreedt omdat de alias al bestaat, verwijdert u deze en voert u het bovenstaande opnieuw uit:

keytool -cacerts -delete -alias cosmos_emulator

Ondersteuning voor OpenTelemetry

OpenTelemetry is een opensource-waarneembaarheidsframework dat een verzameling hulpprogramma's, API's en SDK's biedt voor het instrumenteren, genereren, verzamelen en exporteren van telemetriegegevens. Het OpenTelemetry Protocol (OTLP) is het protocol dat door OpenTelemetry wordt gebruikt om telemetriegegevens tussen onderdelen te verzenden.

U kunt OpenTelemetry gebruiken met de emulator om uw toepassing te bewaken en traceren. De emulator ondersteunt telemetrieopties, die kunnen worden geconfigureerd via omgevingsvariabelen of opdrachtregelvlagmen bij het uitvoeren van de Docker-container.

De emulator exporteert de volgende metrische gegevens. Deze zijn beschikbaar via een back-end met metrische gegevens die OTLP ondersteunen en biedt waardevolle inzichten in de prestaties en status van de database:

Aanvraagtarieven: toont de verkeerspatronen voor verschillende bewerkingstypen
Uitvoeringstijden van query's: meet de tijd die nodig is om verschillende query's uit te voeren
Resourcegebruik: metrische gegevens over CPU, geheugengebruik en verbindingsgroep
Foutpercentages: Fouten bijhouden op type en eindpunt

Notitie

De emulator ondersteunt voorwaardelijke TLS voor de OTLP-exporteur, zodat u kunt integreren met waarneembaarheidsplatforms waarvoor beveiligde verbindingen zijn vereist.

Gedetailleerde instructies met voorbeelden zijn beschikbaar in de GitHub repository.

Gebruiken in werkstroom voor continue integratie

Er zijn veel voordelen voor het gebruik van Docker-containers in CI/CD-pijplijnen, met name voor stateful systemen zoals databases. Dit kan betrekking hebben op kosteneffectiviteit, prestaties, betrouwbaarheid en consistentie van uw testsuites.

De emulator kan worden opgenomen als onderdeel CI/CD-pijplijnen. U kunt verwijzen naar deze GitHub opslagplaats met voorbeelden van het gebruik van de emulator als onderdeel van een GitHub Actions CI-werkstroom voor .NET, Python, Java en Go-toepassingen op zowel x64 als ARM64 architecturen (gedemonstreerd voor Linux-runner met behulp van ubuntu).

Hier volgt een voorbeeld van een GitHub Actions CI-werkstroom die laat zien hoe u de emulator configureert als een GitHub Actions-servicecontainer als onderdeel van een taak in de werkstroom. GitHub zorgt ervoor dat de Docker-container wordt gestart en vernietigd wanneer de taak is voltooid, zonder handmatige tussenkomst (zoals het gebruik van de opdracht 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

Deze taak wordt uitgevoerd op een Ubuntu-runner en gebruikt de mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview Docker-image als servicecontainer. Er worden omgevingsvariabelen gebruikt om de verbindingsreeks, databasenaam en containernaam te configureren. Aangezien in dit geval de taak rechtstreeks op de GitHub Actions runner-machine wordt uitgevoerd, kan de stap Run tests in de taak de emulator benaderen via localhost:8081 (8081 is de poort die door de emulator wordt getoond).

De stap Export Cosmos DB Emulator Certificate is specifiek voor Java toepassingen, omdat de Azure Cosmos DB Java SDK momenteel geen ondersteuning biedt voor de modus HTTP in de emulator. De omgevingsvariabele PROTOCOL is ingesteld op https in de sectie services. Met deze stap wordt het emulatorcertificaat geëxporteerd en in het Java-sleutelarchief geïmporteerd. Hetzelfde geldt ook voor .NET.

Problemen melden

Als u problemen ondervindt met het gebruik van deze versie van de emulator, opent u een probleem in de GitHub opslagplaats (https://github.com/Azure/azure-cosmos-db-emulator-docker) en tagt u het met het label cosmosEmulatorVnextPreview.

Feedback

Is deze pagina nuttig?

Last updated on 2026-04-21

Op Linux gebaseerde emulator - vNext (preview)

Vereisten

Installatie

Hardlopen

Gezondheidsonderzoek

HTTPS-modus

Docker-opdrachten

Functieondersteuning

Beperkingen

Certificaten installeren voor Java SDK

Certificaat ophalen

Certificaat installeren

Ondersteuning voor OpenTelemetry

Gebruiken in werkstroom voor continue integratie

Problemen melden

Feedback

Aanvullende resources