Installer et utiliser l’émulateur Azure Cosmos DB à des fins de développement et de test en local
S’APPLIQUE À : 
NoSQL MongoDB Cassandra Gremlin Table
L’émulateur Azure Cosmos DB fournit un environnement local qui émule le service Azure Cosmos DB à des fins de développement. L’émulateur Azure Cosmos DB vous permet de développer et de tester votre application localement, sans créer d’abonnement Azure et sans frais. Lorsque vous êtes satisfait du fonctionnement de votre application dans l’émulateur Azure Cosmos DB, vous pouvez commencer à utiliser un compte Azure Cosmos DB dans le cloud. Cet article décrit l’installation et l’utilisation de l’émulateur sur les environnements Windows, Linux, macOS et Windows Docker.
Télécharger l’émulateur
Pour commencer, téléchargez et installez la dernière version de l’émulateur Azure Cosmos DB sur votre ordinateur local. L’article Notes de publication de l’émulateur répertorie toutes les versions disponibles et les mises à jour de fonctionnalités qui ont été effectuées dans chaque version.
Télécharger l’émulateur Azure Cosmos DB
Vous pouvez développer des applications à l’aide de l’émulateur Azure Cosmos DB avec le compte en utilisant des API pour NoSQL, Apache Cassandra, MongoDB, Apache Gremlin et Table. Actuellement, l’explorateur de données dans l’émulateur prend entièrement en charge l’affichage des données SQL uniquement ; les données créées à l’aide d’applications clientes MongoDB, Gremlin/Graph et Cassandra ne sont pas visibles pour l’instant. Pour plus d’informations, consultez Comment se connecter au point de terminaison de l’émulateur à partir de différentes API.
Comment l’émulateur fonctionne-t-il ?
L’émulateur Azure Cosmos DB fournit une émulation haute fidélité du service Azure Cosmos DB. Il prend en charge les mêmes fonctionnalités qu’Azure Cosmos DB, notamment la prise en charge de la création et de l’interrogation des données, la configuration et la mise à l’échelle des conteneurs, et l’exécution des procédures stockées et des déclencheurs. Vous pouvez développer et tester des applications à l’aide de l’émulateur Azure Cosmos DB, et les déployer sur Azure à l’échelle mondiale en mettant à jour le point de terminaison de connexion Azure Cosmos DB.
Si l’émulation du service Azure Cosmos DB est fidèle, l’implémentation de l’émulateur est différente de celle du service. Par exemple, l’émulateur utilise les composants du système d’exploitation standard, notamment le système de fichiers local pour la persistance, et la pile de protocole HTTPS pour la connectivité. Les fonctionnalités qui s’appuient sur l’infrastructure Azure, comme la réplication globale, la latence en quelques millisecondes pour les lectures/écritures et les niveaux de cohérence ajustables ne s’appliquent pas lorsque vous utilisez l’émulateur.
Différences entre l’émulateur et le service cloud
Dans la mesure où l’émulateur Azure Cosmos DB offre un environnement émulé qui s’exécute sur la station de travail de développement locale, il existe quelques différences entre les fonctionnalités de l’émulateur et celles d’un compte Azure Cosmos DB dans le cloud :
Actuellement, le volet Explorateur de données dans l’émulateur prend entièrement en charge les clients d’API pour NoSQL uniquement. La vue de l’Explorateur de données et les opérations pour les API MongoDB, Table, Graph et Cassandra d’Azure Cosmos DB ne sont pas entièrement prises en charge.
L'émulateur prend en charge uniquement un compte fixe et une clé principale connue. Vous ne pouvez pas regénérer la clé quand vous utilisez l’émulateur Azure Cosmos DB. Toutefois, vous pouvez changer la clé par défaut à l’aide de l’option de ligne de commande.
Avec l’émulateur, vous pouvez créer un compte Azure Cosmos DB en mode débit provisionné uniquement ; actuellement, il ne prend pas en charge le mode serverless.
L’émulateur n’est pas un service de stockage scalable et ne prend pas en charge un grand nombre de conteneurs. Par défaut, vous pouvez créer jusqu’à 25 conteneurs de taille fixe à 400 RU/s (pris en charge uniquement avec les kits SDK Azure Cosmos DB), ou 5 conteneurs illimités avec l’émulateur Azure Cosmos DB. Pour plus d’informations sur la modification de cette valeur, consultez l’article Définir la valeur PartitionCount.
L’émulateur n’offre pas de niveaux de cohérence Azure Cosmos DB différents comme le service cloud le fait.
L’émulateur ne permet pas la réplication entre plusieurs régions.
Votre copie de l’émulateur Azure Cosmos DB n’étant pas forcément à jour par rapport aux derniers changements apportés au service Azure Cosmos DB, nous vous conseillons de consulter l’outil de planification de capacité Azure Cosmos DB pour évaluer avec précision les besoins en débit (RU) de votre application.
L’émulateur prend en charge la taille maximale de propriété d’ ID qui est de 254 caractères.
Installer l’émulateur
Avant d’installer l’émulateur, vérifiez que vous disposez de la configuration matérielle et logicielle requise suivante :
Configuration logicielle requise :
- Actuellement, les systèmes d’exploitation hôtes Windows Server 2016, 2019 ou Windows 10 sont pris en charge. Le système d’exploitation hôte avec Active Directory activé n’est pas pris en charge pour le moment.
- Système d’exploitation 64 bits
Conditions matérielles minimales requises :
- 2 Go de RAM
- 10 Go d’espace disque disponible
Pour installer, configurer et exécuter l’émulateur Azure Cosmos DB, vous devez disposer de privilèges d’administrateur sur l’ordinateur. L’émulateur ajoute un certificat et définit également les règles de pare-feu afin d’exécuter ses services. Par conséquent, des droits d’administrateur sont nécessaires pour que l’émulateur puisse exécuter ces opérations.
Pour commencer, téléchargez et installez la dernière version de l’émulateur Azure Cosmos DB sur votre ordinateur local. Si vous rencontrez des problèmes lors de l’installation de l’émulateur, consultez l’article Résolution des problèmes de l’émulateur pour déboguer.
En fonction de la configuration requise, vous pouvez exécuter l’émulateur sur Windows, Docker pour Windows, Linux ou macOS, comme décrit dans les sections suivantes de cet article.
Rechercher les mises à jour de l’émulateur
Chaque version de l’émulateur est fournie avec un ensemble de mises à jour de fonctionnalités ou de correctifs de bogues. Pour afficher les versions disponibles, lisez l’article Notes de publication de l’émulateur.
Après l’installation, si vous avez utilisé les paramètres par défaut, les données correspondant à l’émulateur sont enregistrées à l’emplacement %LOCALAPPDATA%\CosmosDBEmulator. Vous pouvez configurer un autre emplacement à l’aide des paramètres facultatifs de chemin d’accès aux données, avec /DataPath=PREFERRED_LOCATION comme paramètre de ligne de commande. Il n’est pas garanti que vous puissiez accéder aux données créées dans une version de l’émulateur Azure Cosmos DB à partir d’une autre version. Si vous devez rendre vos données persistantes à long terme, nous vous recommandons de les stocker dans un compte Azure Cosmos DB plutôt que dans l’émulateur Azure Cosmos DB.
Utiliser l’émulateur sur Windows
L’émulateur Azure Cosmos DB est installé à l’emplacement C:\Program Files\Azure Cosmos DB Emulator par défaut. Pour démarrer l’émulateur Azure Cosmos DB sur Windows, sélectionnez le bouton Démarrer, ou appuyez sur la touche Windows. Commencez à taper Émulateur Azure Cosmos DB, puis sélectionnez l’émulateur dans la liste des applications.
Lorsque l’émulateur est démarré, une icône est affichée dans la zone de notification de la barre des tâches Windows. L’explorateur de données Azure Cosmos DB s’ouvre automatiquement dans votre navigateur à cette URL https://localhost:8081/_explorer/index.html.
Vous pouvez également démarrer et arrêter l’émulateur à partir de la ligne de commande ou de commandes PowerShell. Pour plus d’informations, consultez l’article Référence de l’outil en ligne de commande.
L’émulateur Azure Cosmos DB s’exécute par défaut sur l’ordinateur local (« localhost ») et écoute sur le port 8081. L’adresse apparaît sous la forme https://localhost:8081/_explorer/index.html. Si vous fermez l’explorateur et que vous souhaitez le rouvrir ultérieurement, vous pouvez ouvrir l’URL dans votre navigateur ou la lancer à partir de l’émulateur Azure Cosmos DB dans l’icône de la barre d’état système Windows, comme indiqué ci-dessous.
Utiliser l’émulateur sur Linux ou macOS
L’émulateur Azure Cosmos DB peut uniquement être exécuté sur Windows. Si vous utilisez Linux ou macOS, nous vous recommandons de vous servir de l’émulateur Linux (préversion) ou d’exécuter l’émulateur sur une machine virtuelle Windows hébergée dans un hyperviseur (par exemple Parallels ou VirtualBox).
Notes
Chaque fois que vous redémarrez la machine virtuelle Windows qui est hébergée dans un hyperviseur, vous devez réimporter le certificat, car l’adresse IP de la machine virtuelle change. L’importation du certificat n’est pas nécessaire si vous avez configuré la machine virtuelle pour conserver l’adresse IP.
Procédez comme suit pour utiliser l’émulateur sur des environnements Linux ou macOS :
Exécutez la commande suivante à partir de la machine virtuelle Windows et prenez note de l’adresse IPv4 :
ipconfig.exeDans votre application, modifiez l’URL du point de terminaison pour utiliser l’adresse IPv4 renvoyée par
ipconfig.exeau lieu delocalhost.À partir de la machine virtuelle Windows, depuis la ligne de commande, lancez l’émulateur Azure Cosmos DB avec les options suivantes. Pour plus d’informations sur les paramètres pris en charge par la ligne de commande, consultez l’article Référence de l’outil en ligne de commande de l’émulateur :
Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==Enfin, vous devez résoudre le processus d’approbation de certificat entre l’application en cours d’exécution dans l’environnement Linux ou Mac et l’émulateur. Vous pouvez utiliser l’une des deux options suivantes pour résoudre le certificat :
Option 1 : Importer le certificat TLS/SSL de l’émulateur
Les sections suivantes montrent comment importer le certificat TLS/SSL de l’émulateur dans des environnements Linux et macOS.
Environnement Linux
Si vous travaillez sur Linux, .NET compte sur OpenSSL pour effectuer la validation :
Exporter le certificat au format .PFX. L’option PFX est disponible lorsque vous choisissez d’exporter la clé privée.
Copiez ce fichier PFX dans votre environnement Linux.
Convertir le fichier PFX en fichier CRT
openssl pkcs12 -in YourPFX.pfx -clcerts -nokeys -out YourCTR.crtCopiez le fichier CRT dans le dossier qui contient les certificats personnalisés dans votre distribution Linux. Sur les distributions Debian, il se trouve en général sur
/usr/local/share/ca-certificates/.cp YourCTR.crt /usr/local/share/ca-certificates/Mettez à jour les certificats TLS/SSL, ce qui mettra à jour le dossier
/etc/ssl/certs/.update-ca-certificates
Environnement macOS
Suivez les étapes ci-dessous si vous travaillez sur Mac :
Exporter le certificat au format .PFX. L’option PFX est disponible lorsque vous choisissez d’exporter la clé privée.
Copiez ce fichier PFX dans votre environnement Mac.
Ouvrez l’application Keychain Access et importez le fichier PFX.
Ouvrez la liste des certificats et identifiez celui qui a le nom
localhost.Ouvrez le menu contextuel pour cet élément particulier, sélectionnez Obtenir l’élément et, sous Approuver>Lors de l’utilisation de ce certificat, sélectionnez Toujours approuver.
Option 2 : Désactiver la validation SSL dans l’application
La désactivation de la validation SSL est uniquement recommandée à des fins de développement et ne doit pas être effectuée lors de l’exécution dans un environnement de production. Les exemples suivants montrent comment désactiver la validation SSL pour les applications .NET et Node.js.
Pour toute application s’exécutant dans une infrastructure compatible avec .NET Standard 2.1 ou une version ultérieure, nous pouvons tirer parti de CosmosClientOptions.HttpClientFactory :
CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
{
HttpClientFactory = () =>
{
HttpMessageHandler httpMessageHandler = new HttpClientHandler()
{
ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
};
return new HttpClient(httpMessageHandler);
},
ConnectionMode = ConnectionMode.Gateway
};
CosmosClient client = new CosmosClient(endpoint, authKey, cosmosClientOptions);
Activer l’accès à l’émulateur sur un réseau local
Supposons que vous avez plusieurs ordinateurs utilisant un même réseau, et que vous configurez l’émulateur sur un ordinateur et souhaitez y accéder à partir d’un autre ordinateur. Dans ce cas, vous devez activer l’accès à l’émulateur sur un réseau local.
Vous pouvez exécuter l’émulateur sur un réseau local. Pour activer l’accès réseau, spécifiez l’option /AllowNetworkAccess sur la ligne de commande, avec /Key=key_string ou /KeyFile=file_name. Vous pouvez initialement utiliser /GenKeyFile=file_name pour générer un fichier avec une clé aléatoire. Passez ensuite cette clé à /KeyFile=file_name ou /Key=contents_of_file.
Avant d’activer l’accès réseau pour la première fois, l’utilisateur doit arrêter l’émulateur et supprimer le répertoire de données de l’émulateur %LOCALAPPDATA%\CosmosDBEmulator.
Authentifier les connexions lors de l’utilisation de l’émulateur
Tout comme avec Azure Cosmos DB dans le cloud, chaque demande que vous effectuez auprès de l’émulateur Azure Cosmos DB doit être authentifiée. L’émulateur Azure Cosmos DB prend uniquement en charge une communication sécurisée via TLS. L’émulateur Azure Cosmos DB prend en charge un seul compte fixe et une clé d’authentification connue pour l’authentification de la clé primaire. Ce compte et cette clé sont les seules informations d’identification autorisées pour une utilisation avec l’émulateur Azure Cosmos DB. Il s'agit des éléments suivants :
Account name: localhost:<port>
Account key: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
Notes
La clé primaire prise en charge par l’émulateur Azure Cosmos DB peut être utilisée uniquement avec l’émulateur. Vous ne pouvez pas utiliser votre compte et votre clé Azure Cosmos DB de production avec l’émulateur Azure Cosmos DB.
Notes
Si vous avez démarré l’émulateur avec l’option /Key, utilisez la clé générée à la place de la clé par défaut C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==. Pour plus d’informations sur l’option /Key, consultez la section Référence sur l’outil en ligne de commande.
Se connecter à différentes API avec l’émulateur
API pour NoSQL
Une fois que l’émulateur Azure Cosmos DB est exécuté sur votre bureau, vous pouvez utiliser n’importe quel SDK Azure Cosmos DB pris en charge ou l’API REST Azure Cosmos DB pour interagir avec lui. L’émulateur Azure Cosmos DB comprend également un explorateur de données intégré à partir duquel vous pouvez créer des conteneurs pour l’API pour NoSQL ou MongoDB. L’Explorateur de données vous permet d’afficher et de modifier des éléments sans écrire de code.
// Connect to the Azure Cosmos DB Emulator running locally
CosmosClient client = new CosmosClient(
"https://localhost:8081",
"C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==");
API pour MongoDB
Une fois que l’émulateur Azure Cosmos DB s’exécute sur votre poste de travail, vous pouvez utiliser l’API Azure Cosmos DB pour MongoDB afin d’interagir avec lui. Démarrez l’émulateur à partir d’une invite de commandes administrateur avec « /EnableMongoDbEndpoint ». Utilisez ensuite la chaîne de connexion suivante pour vous connecter au compte de l’API pour MongoDB :
mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true
API pour Table
Une fois que l’émulateur Azure Cosmos DB s’exécute sur votre poste de travail, vous pouvez utiliser le SDK d’API pour Table Azure Cosmos DB afin d’interagir avec lui. Démarrez l’émulateur à partir d’une invite de commandes administrateur avec « /EnableTableEndpoint ». Ensuite, exécutez le code suivant pour vous connecter au compte d’API pour Table :
using Microsoft.WindowsAzure.Storage;
using Microsoft.WindowsAzure.Storage.Table;
using CloudTable = Microsoft.WindowsAzure.Storage.Table.CloudTable;
using CloudTableClient = Microsoft.WindowsAzure.Storage.Table.CloudTableClient;
string connectionString = "DefaultEndpointsProtocol=http;AccountName=localhost;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;TableEndpoint=http://localhost:8902/;";
CloudStorageAccount account = CloudStorageAccount.Parse(connectionString);
CloudTableClient tableClient = account.CreateCloudTableClient();
CloudTable table = tableClient.GetTableReference("testtable");
table.CreateIfNotExists();
table.Execute(TableOperation.Insert(new DynamicTableEntity("partitionKey", "rowKey")));
API pour Cassandra
Démarrez l’émulateur à partir d’une invite de commandes administrateur avec « /EnableCassandraEndpoint ». Vous pouvez également définir la variable d’environnement AZURE_COSMOS_EMULATOR_CASSANDRA_ENDPOINT=true.
Exécutez les commandes ci-dessous à partir d’une fenêtre d’invite de commandes :
set Path=c:\Python27;%Path% cd /d C:\sdk\apache-cassandra-3.11.3\bin set SSL_VERSION=TLSv1_2 set SSL_VALIDATE=false cqlsh localhost 10350 -u localhost -p C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== --sslDans l’interpréteur de commandes CQLSH, exécutez les commandes suivantes pour vous connecter au point de terminaison Cassandra :
CREATE KEYSPACE MyKeySpace WITH replication = {'class':'MyClass', 'replication_factor': 1}; DESCRIBE keyspaces; USE mykeyspace; CREATE table table1(my_id int PRIMARY KEY, my_name text, my_desc text); INSERT into table1 (my_id, my_name, my_desc) values( 1, 'name1', 'description 1'); SELECT * from table1; EXIT
API pour Gremlin
Démarrez l’émulateur à partir d’une invite de commandes administrateur avec « /EnableGremlinEndpoint ». Vous pouvez également définir la variable d’environnement AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=true
Dans l’Explorateur de données de l’émulateur, créez une base de données « db1 » et une collection « coll1 » ; pour la clé de partition, définissez le nom avec « /name »
Exécutez les commandes ci-dessous à partir d’une fenêtre d’invite de commandes :
cd /d C:\sdk\apache-tinkerpop-gremlin-console-3.6.0-bin\apache-tinkerpop-gremlin-console-3.6.0 copy /y conf\remote.yaml conf\remote-localcompute.yaml notepad.exe conf\remote-localcompute.yaml hosts: [localhost] port: 8901 username: /dbs/db1/colls/coll1 password: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== connectionPool: { enableSsl: false} serializer: { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV1d0, config: { serializeResultToString: true }} bin\gremlin.batDans l’interpréteur de commandes Gremlin, exécutez les commandes suivantes pour vous connecter au point de terminaison Gremlin :
:remote connect tinkerpop.server conf/remote-localcompute.yaml :remote console :> g.V() :> g.addV('person1').property(id, '1').property('name', 'somename1') :> g.addV('person2').property(id, '2').property('name', 'somename2') :> g.V()
Désinstaller l’émulateur local
Utilisez les étapes suivantes pour désinstaller l’émulateur :
Quittez toutes les instances ouvertes de l’émulateur local en cliquant avec le bouton droit sur l’icône de l’émulateur Azure Cosmos DB dans la zone de notification, puis en sélectionnant Quitter. Quitter l’ensemble des instances peut prendre une minute.
Dans la zone de recherche Windows, tapez Applications & fonctionnalités, puis sélectionnez Applications & fonctionnalités (paramètres système).
Dans la liste des applications, faites défiler la page jusqu’à trouver Émulateur Azure Cosmos DB, sélectionnez-le, cliquez sur Désinstaller, puis confirmez en sélectionnant de nouveau Désinstaller.
Étapes suivantes
Dans cet article, vous avez appris à utiliser l’émulateur local pour un développement local gratuit. Vous pouvez maintenant passer aux articles suivants :