Émulateur basé sur Linux (aperçu)

2025-04-18

La nouvelle génération de l’émulateur Azure Cosmos DB est entièrement basée sur Linux et est disponible sous forme de conteneur Docker. Il prend en charge l’exécution sur une grande variété de processeurs et de systèmes d’exploitation.

Important

Cette version de l'émulateur prend uniquement en charge l'API pour NoSQL en mode passerelle, avec un sous-ensemble sélectionné de fonctionnalités. Pour plus d'informations, consultez le support des fonctionnalités.

Prérequis

Docker

Installation

Obtenez l’image du conteneur Docker en utilisant docker pull. L'image du conteneur est publiée dans le Registre des artefacts Microsoft sous le nom mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview.

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

Exécution en cours

Pour exécuter le conteneur, utilisez docker run. Ensuite, utilisez docker ps pour valider que le conteneur est en cours d'exécution.

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>

Remarque

L'émulateur est composé de deux composants :

Explorateur de données - explorer de manière interactive les données dans l'émulateur. Par défaut, cela fonctionne sur le port 1234
Émulateur Azure Cosmos DB - une version locale du service de base de données Azure Cosmos DB. Par défaut, cela s'exécute sur le port 8081.

Le point de terminaison de la passerelle de l'émulateur est généralement disponible sur le port 8081 à l'adresse http://localhost:8081. Pour accéder à l’explorateur de données, utilisez l’adresse http://localhost:1234 dans votre navigateur Web. Il faudra peut-être quelques secondes pour que l’explorateur de données soit disponible. Le point de terminaison de la passerelle est généralement disponible immédiatement.

Important

Les Kits de développement logiciel (SDK) .NET et Java ne prennent pas en charge le mode HTTP dans l'émulateur. Étant donné que cette version de l’émulateur commence par HTTP par défaut, vous devez activer explicitement HTTPS lors du démarrage du conteneur (voir ci-dessous). Pour le SDK Java, vous devez également installer des certificats.

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

Commandes Docker

Le tableau suivant résume les commandes Docker disponibles pour configurer l'émulateur. Ce tableau détaille les arguments correspondants, les variables d'environnement, les valeurs autorisées, les paramètres par défaut et les descriptions de chaque commande.

Condition requise	Arg	Env	Valeurs autorisées	Default	Description
Imprimez les paramètres sur stdout à partir du conteneur	`--help`, `-h`	N/A	N/A	N/A	Affichez les informations sur la configuration disponible
Définissez le port du point de terminaison Cosmos	`--port [INT]`	PORT	INT	8081	Le port du point de terminaison Cosmos sur le conteneur. Vous devez encore publier ce port (par exemple, `-p 8081:8081`).
Spécifiez le protocole utilisé par le point de terminaison Cosmos	`--protocol`	PROTOCOLE	`https`, `http`, `https-insecure`	`http`	Le protocole du point de terminaison Cosmos sur le conteneur.
Activez l'explorateur de données	`--enable-explorer`	ENABLE_EXPLORER	`true`, `false`	`true`	Activez l’exécution de Cosmos Data Explorer sur le même conteneur.
Définissez le port utilisé par l'explorateur de données	`--explorer-port`	EXPLORER_PORT	INT	1234	Le port du Cosmos Data Explorer sur le conteneur. Vous devez encore publier ce port (par exemple, `-p 1234:1234`).
L'utilisateur doit pouvoir spécifier le protocole utilisé par l'explorateur, sinon il doit choisir par défaut celui utilisé par le point de terminaison Cosmos	`--explorer-protocol`	EXPLORER_PROTOCOL	`https`, `http`, `https-insecure`	`<the value of --protocol>`	Le protocole du Cosmos Data Explorer sur le conteneur. La valeur par défaut est le paramètre de protocole sur le point de terminaison Cosmos.
Spécifiez la clé via le fichier	`--key-file [PATH]`	KEY_FILE	PATH	`<default secret>`	Remplacez la clé par défaut par la clé spécifiée dans le fichier. Vous devez monter ce fichier dans le conteneur (par exemple, si KEY_FILE=/mykey, vous ajouteriez une option comme celle-ci à votre exécution de docker : `--mount type=bind,source=./myKey,target=/myKey`)
Définissez le chemin des données	`--data-path [PATH]`	DATA_PATH	PATH	`/data`	Spécifiez un répertoire pour les données. Fréquemment utilisé avec l'option `docker run --mount` (par exemple, si DATA_PATH=/usr/cosmos/data, vous ajouteriez une option comme celle-ci à votre exécution de docker : `--mount type=bind,source=./.local/data,target=/usr/cosmos/data`)
Spécifiez le chemin du certificat à utiliser pour https	`--cert-path [PATH]`	CERT_PATH	PATH	`<default cert>`	Spécifiez un chemin vers un certificat pour sécuriser le trafic. Vous devez monter ce fichier dans le conteneur (par exemple, si CERT_PATH=/mycert.pfx, vous ajouteriez une option comme celle-ci à votre exécution de docker : `--mount type=bind,source=./mycert.pfx,target=/mycert.pfx`)
Spécifiez le secret du certificat à utiliser pour https	N/A	CERT_SECRET	string	`<default secret>`	Le secret du certificat spécifié sur CERT_PATH.
Définissez le niveau de journalisation	`--log-level [LEVEL]`	LOG_LEVEL	`quiet`, `error`, `warn`, `info`, `debug`, `trace`	`info`	La verbosité des journaux émis par l'émulateur et l'explorateur de données.
Activez l'envoi d'informations de diagnostic à Microsoft	`--enable-telemetry`	ACTIVER_TÉLÉMÉTRIE	`true`, `false`	`true`	Activez l'envoi de journaux à Microsoft pour nous aider à améliorer l'émulateur.

Prise en charge des fonctionnalités

Cet émulateur est en développement actif et en aperçu. Par conséquent, toutes les fonctionnalités d’Azure Cosmos DB ne sont pas prises en charge. Certaines fonctionnalités ne seront pas non plus prises en charge à l’avenir. Ce tableau comprend l'état des différentes fonctionnalités et leur niveau de support.

Fonctionnalité	Support
API Batch	✅ Pris en charge
API en bloc	✅ Pris en charge
Flux de modification	⚠️ Pas encore implémenté
Créez et lire un document avec des données utf	✅ Pris en charge
Créer une collection	✅ Pris en charge
Créez une collection deux fois en conflit	✅ Pris en charge
Créez une collection avec une politique d'index personnalisée	⚠️ Pas encore implémenté
Créez une collection avec une expiration TTL	⚠️ Pas encore implémenté
Créer une base de données	✅ Pris en charge
Créez une base de données deux fois en conflit	✅ Pris en charge
Créez un document	✅ Pris en charge
Créez une collection partitionnée	⚠️ Pas encore implémenté
Supprimer une collection	✅ Pris en charge
Supprimez la base de données	✅ Pris en charge
Supprimer un document	✅ Pris en charge
Obtenez et modifier les performances de la collection	⚠️ Pas encore implémenté
Insérez un document volumineux	✅ Pris en charge
Document de correctif	⚠️ Pas encore implémenté
Interroger une collection partitionnée en parallèle	⚠️ Pas encore implémenté
Requête avec agrégats	⚠️ Pas encore implémenté
Requête avec filtre AND	⚠️ Pas encore implémenté
Requête avec filtre et projection	⚠️ Pas encore implémenté
Requête avec égalité	✅ Pris en charge
Requête avec equals sur id	✅ Pris en charge
Requête avec jointures	⚠️ Pas encore implémenté
Requête avec ordre par	✅ Pris en charge
Requête avec ordre par pour une collection partitionnée	⚠️ Pas encore implémenté
Requête avec ordre par numéros	✅ Pris en charge
Requête avec ordre par chaînes	⚠️ Pas encore implémenté
Requête avec pagination	⚠️ Pas encore implémenté
Requête avec opérateurs de plage date heures	⚠️ Pas encore implémenté
Requête avec opérateurs de plage sur les nombres	⚠️ Pas encore implémenté
Requête avec opérateurs de plage sur des chaînes	⚠️ Pas encore implémenté
Requête avec jointure unique	⚠️ Pas encore implémenté
Requête avec des opérateurs mathématiques de chaîne et de tableau	⚠️ Pas encore implémenté
Requête avec sous-documents	⚠️ Pas encore implémenté
Requête avec deux jointures	⚠️ Pas encore implémenté
Requête avec deux jointures et filtre	⚠️ Pas encore implémenté
Lire la collection	✅ Pris en charge
Lisez le flux de la collection	⚠️ Pas encore implémenté
Lisez la base de données	✅ Pris en charge
Lisez le flux de la base de données	⚠️ Pas encore implémenté
Lisez le document	✅ Pris en charge
Lisez le flux de documents	✅ Pris en charge
Remplacer le document	✅ Pris en charge
Unités de requête	⚠️ Pas encore implémenté
procédures stockées	❌ Non prévu
Déclencheurs	❌ Non prévu
Fonctions définies par l’utilisateur	❌ Non prévu
Mettre à jour la collection	⚠️ Pas encore implémenté
Mise à jour du document	✅ Pris en charge

Limites

En plus des fonctionnalités non encore prises en charge ou non prévues, la liste suivante inclut les limitations actuelles de l'émulateur.

Le SDK .NET pour Azure Cosmos DB ne prend pas en charge l’exécution en masse dans l’émulateur.
Les Kits de développement logiciel (SDK) .NET et Java ne prennent pas en charge le mode HTTP dans l'émulateur.

Installation de certificats pour le SDK Java

Lorsque vous utilisez le SDK Java pour Azure Cosmos DB avec cette version de l’émulateur en mode https, il est nécessaire d’installer ses certificats dans votre magasin de confiance Java local.

Obtention de certificat

Dans une fenêtre bash, exécutez ce qui suit :

# 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

Installer le certificat

Accédez au répertoire de votre installation Java où se trouve le fichier cacerts (remplacez ci-dessous par le bon répertoire) :

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

Importez le certificat (vous pouvez être invité à indiquer un mot de passe, la valeur par défaut est « changeit ») :

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

Si vous obtenez une erreur parce que l’alias existe déjà, supprimez-le, puis exécutez à nouveau la commande ci-dessus :

keytool -cacerts -delete -alias cosmos_emulator

Utiliser dans le flux de travail d’intégration continue

Il existe de nombreux avantages à utiliser des conteneurs Docker dans des pipelines CI/CD, en particulier pour les systèmes avec état comme les bases de données. Cela peut être en termes de rentabilité, de performances, de fiabilité et de cohérence de vos suites de tests.

L’émulateur peut être incorporé dans le cadre de pipelines CI/CD. Vous pouvez vous référer à ce référentiel GitHub qui fournit des exemples d'utilisation de l'émulateur dans le cadre d'un workflow CI GitHub Actions pour les applications .NET, Python, Java et Go sur les architectures x64 et ARM64 (illustré pour un exécuteur Linux utilisant ubuntu).

Voici un exemple de flux de travail CI GitHub Actions qui montre comment configurer l’émulateur en tant que conteneur de service GitHub Actions dans le cadre d’un travail dans le flux de travail. GitHub s’occupe du démarrage du conteneur Docker et le détruit une fois le travail terminé, sans avoir besoin d’intervention manuelle (par exemple, à l’aide de la docker run commande).

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

Ce travail s’exécute sur un exécuteur Ubuntu et utilise l’image mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview Docker en tant que conteneur de service. Il utilise des variables d’environnement pour configurer la chaîne de connexion, le nom de la base de données et le nom du conteneur. Étant donné que, dans ce cas, le travail s’exécute directement sur l’ordinateur exécuteur GitHub Actions, l’étape Exécuter les tests du travail peut accéder à l’émulateur qui est accessible via localhost:8081 (8081 étant le port exposé par l’émulateur).

L’étape Exporter le certificat de l’émulateur Cosmos DB est spécifique aux applications Java, car le Kit de développement logiciel (SDK) Java Azure Cosmos DB ne prend actuellement pas en charge HTTP le mode dans l’émulateur. La PROTOCOL variable d’environnement est définie https dans la services section et cette étape exporte le certificat de l’émulateur et l’importe dans le magasin de clés Java. La même chose s’applique également à .NET.

Signaler un problème

Si vous rencontrez des problèmes lors de l'utilisation de cette version de l'émulateur, ouvrez un problème dans le référentiel GitHub (https://github.com/Azure/azure-cosmos-db-emulator-docker) et étiquetez-le avec l'étiquette cosmosEmulatorVnextPreview.