Émulateur basé sur Linux (aperçu)
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 la prise en charge des fonctionnalités.
Prérequis
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
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 8081 sur le port à 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.
| Exigence | 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 | S/O | 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 |
ENABLE_TELEMETRY | 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 et filtre | ⚠️ 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é |
| Lisez 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
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.