Références sur la ligne de commande et PowerShell pour l’émulateur Windows (local)

Article
09/14/2023

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 local. Après avoir installé l’émulateur, vous pouvez le contrôler à l’aide de la ligne de commande et des commandes PowerShell. Cet article explique comment utiliser la ligne de commande et les commandes PowerShell pour démarrer et arrêter ’émulateur, configurer les options et effectuer d’autres opérations. Vous devez exécuter les commandes à partir de l’emplacement d’installation.

Important

Cet article n'inclut que les arguments de ligne de commande pour l'émulateur local Windows.

Gérer l’émulateur avec la syntaxe de ligne de commande

Microsoft.Azure.Cosmos.Emulator.exe 
    [/Shutdown] [/DataPath] [/Port] [/MongoPort] 
    [/DirectPorts] [/Key] [/EnableRateLimiting] 
    [/DisableRateLimiting] [/NoUI] [/NoExplorer] 
    [/EnableMongoDbEndpoint] 
    [/?]

Pour afficher la liste des paramètres, saisissez Microsoft.Azure.Cosmos.Emulator.exe /? dans l’invite de commandes.

Paramètre	Description	Exemple de commande
[Aucun argument]	Démarre l’émulateur avec des paramètres par défaut.	Microsoft.Azure.Cosmos.Emulator.exe
[Aide]	Affiche la liste des arguments de ligne de commande pris en charge.	`Microsoft.Azure.Cosmos.Emulator.exe /?`
`GetStatus`	Obtient l'état de l'émulateur. Chaque code de sortie indique un état : `1` = Démarrage, `2` = Exécution et `3` = Arrêté. Un code de sortie négatif indique qu’une erreur s’est produite. Aucune autre sortie n’est générée.	`Microsoft.Azure.Cosmos.Emulator.exe /GetStatus`
`Shutdown`	Arrête l’émulateur.	`Microsoft.Azure.Cosmos.Emulator.exe /Shutdown`
`DataPath`	Spécifie le chemin d’accès dans lequel stocker les fichiers de données. La valeur par défaut est `%LocalAppdata%\CosmosDBEmulator`.	`Microsoft.Azure.Cosmos.Emulator.exe /DataPath=E:\SomeDataFolder`
`Port`	Spécifie le numéro de port à utiliser pour l'émulateur. La valeur par défaut est `8081`.	`Microsoft.Azure.Cosmos.Emulator.exe /Port=65000`
`ComputePort`	Spécifie le numéro du port à utiliser pour le service de la passerelle de calcul interopérabilité. Le port de sonde du point de terminaison HTTP de la passerelle est calculé comme étant égal à `ComputePort + 79`. Par conséquent, `ComputePort` et `ComputePort + 79` doivent être ouverts et disponibles. La valeur par défaut est `8900`.	`Microsoft.Azure.Cosmos.Emulator.exe /ComputePort=65100`
`EnableMongoDbEndpoint=3.2`	Active l’API pour MongoDB 3.2.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.2`
`EnableMongoDbEndpoint=3.6`	Active l’API pour MongoDB 3.6.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.6`
`EnableMongoDbEndpoint=4.0`	Active l’API pour MongoDB 4.0.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=4.0`
`MongoPort`	Spécifie le numéro de port à utiliser pour l'API MongoDB. La valeur par défaut est `10255`.	`Microsoft.Azure.Cosmos.Emulator.exe /MongoPort=65200`
`EnableCassandraEndpoint`	Active l’API pour Apache Cassandra.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpoint`
`CassandraPort`	Spécifie le numéro de port à utiliser pour l’API du point de terminaison de Cassandra. La valeur par défaut est `10350`.	`Microsoft.Azure.Cosmos.Emulator.exe /CassandraPort=65300`
`EnableGremlinEndpoint`	Active l’API pour Apache Gremlin.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpoint`
`GremlinPort`	Numéro de port à utiliser pour l’API du point de terminaison d’Apache Gremlin. La valeur par défaut est `8901`.	`Microsoft.Azure.Cosmos.Emulator.exe /GremlinPort=65400`
`EnableTableEndpoint`	Active l’API pour Table.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableTableEndpoint`
`TablePort`	Numéro de port à utiliser pour l’API du point de terminaison de Table. La valeur par défaut est `8902`.	`Microsoft.Azure.Cosmos.Emulator.exe /TablePort=65500`
`KeyFile`	Lit la clé d’autorisation dans le fichier spécifié. Utilisez l’option `/GenKeyFile` pour générer un fichier clé.	`Microsoft.Azure.Cosmos.Emulator.exe /KeyFile=D:\Keys\keyfile`
`ResetDataPath`	Supprime de manière récursive tous les fichiers du chemin spécifié. Si vous ne spécifiez pas de chemin, la valeur par défaut est `%LOCALAPPDATA%\CosmosDbEmulator`.	`Microsoft.Azure.Cosmos.Emulator.exe /ResetDataPath`
`StartTraces`	Démarre la collecte des journaux de traces du débogage à l’aide de LOGMAN.	`Microsoft.Azure.Cosmos.Emulator.exe /StartTraces`
`StopTraces`	Arrête la collecte des journaux de traces du débogage à l’aide de LOGMAN.	`Microsoft.Azure.Cosmos.Emulator.exe /StopTraces`
`StartWprTraces`	Démarre la collecte des journaux de traces du débogage à l’aide de l’outil d’enregistrement des performances Windows.	`Microsoft.Azure.Cosmos.Emulator.exe /StartWprTraces`
`StopWprTraces`	Arrête la collecte des journaux de traces du débogage à l’aide de l’outil d’enregistrement des performances Windows.	`Microsoft.Azure.Cosmos.Emulator.exe /StopWprTraces`
`FailOnSslCertificateNameMismatch`	Par défaut, l’émulateur regénère son certificat TLS/SSL auto-signé, si le réseau SAN du certificat n’inclut pas le nom de domaine de l’hôte émulateur, l’adresse IP locale, (v4), `localhost` et `127.0.0.1`. Avec cette option, l’émulateur échoue au démarrage. Vous devez alors utiliser l’option `/GenCert` pour créer et installer un nouveau certificat TLS/SSL auto-signé.	`Microsoft.Azure.Cosmos.Emulator.exe /FailOnSslCertificateNameMismatch`
`GenCert`	Génère et installe un nouveau certificat TLS/SSL auto-signé, incluant de manière facultative une liste de noms DNS supplémentaires séparés par des virgules pour accéder à l’émulateur sur le réseau.	`Microsoft.Azure.Cosmos.Emulator.exe /GenCert`
`DirectPorts`	Spécifie les ports à utiliser pour une connectivité directe. Les valeurs par défaut sont `10251`, `10252`, `10253` et `10254`.	`Microsoft.Azure.Cosmos.Emulator.exe /DirectPorts:65600,65700`
`Key`	Clé d’autorisation pour l’émulateur. La clé doit être le codage en base 64 d’un vecteur de 64 octets.	`Microsoft.Azure.Cosmos.Emulator.exe /Key:D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==`
`EnableRateLimiting`	Spécifie que le comportement de limitation de taux de demandes est activé.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableRateLimiting`
`DisableRateLimiting`	Spécifie que le comportement de limitation de taux de demandes est désactivé.	`Microsoft.Azure.Cosmos.Emulator.exe /DisableRateLimiting`
`NoUI`	Ne pas afficher l’interface utilisateur de l’émulateur.	`Microsoft.Azure.Cosmos.Emulator.exe /NoUI`
`NoExplorer`	Ne pas afficher l’Explorateur de données au démarrage.	`Microsoft.Azure.Cosmos.Emulator.exe /NoExplorer`
`PartitionCount`	Spécifie le nombre maximal de conteneurs partitionnés. Pour plus d’informations, consultez Changer le nombre de conteneurs. La valeur par défaut est `25`. La valeur maximale autorisée est `250`.	`Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=15`
`DefaultPartitionCount`	Spécifie le nombre par défaut de partitions pour un conteneur partitionné. La valeur par défaut est `25`.	`Microsoft.Azure.Cosmos.Emulator.exe /DefaultPartitionCount=50`
`AllowNetworkAccess`	Permet d’accéder à l’émulateur sur un réseau. Vous devez également passer `/Key=<key_string>` ou /`KeyFile=<file_name>` pour activer l’accès au réseau.	`Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==`
`NoFirewall`	Ne pas ajuster les règles de pare-feu quand l’option `/AllowNetworkAccess` est utilisée.	`Microsoft.Azure.Cosmos.Emulator.exe /NoFirewall`
`GenKeyFile`	Générer une nouvelle clé d’autorisation et Générer une nouvelle clé d’autorisation et l’enregistrer dans le fichier spécifié. La clé générée peut être utilisée avec les options `/Key` ou `/KeyFile`.	`Microsoft.Azure.Cosmos.Emulator.exe /GenKeyFile=D:\Keys\keyfile`
`Consistency`	Définir le niveau de cohérence par défaut pour le compte. La valeur par défaut est Session.	`Microsoft.Azure.Cosmos.Emulator.exe /Consistency=Strong`
`?`	Afficher le message d’aide.

Gérer l’émulateur avec les cmdlets PowerShell

L’émulateur est fourni avec un module PowerShell que vous pouvez utiliser pour démarrer, arrêter et désinstaller le service, et récupérer son état. Exécutez l’applet de commande suivante pour utiliser le module PowerShell :

Import-Module "$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules\Microsoft.Azure.CosmosDB.Emulator"

Vous pouvez aussi placer le répertoire PSModules dans PSModulePath et importer le module en utilisant la commande suivante :

$env:PSModulePath += ";$env:ProgramFiles\Azure Cosmos DB Emulator\PSModules"
Import-Module Microsoft.Azure.CosmosDB.Emulator

Voici un résumé des commandes permettant de contrôler l’émulateur à partir de PowerShell :

`Get-CosmosDbEmulatorStatus`

Obtient l'état de l'émulateur. Choisissez l’une de ces valeurs ServiceControllerStatus :

ServiceControllerStatus.StartPending
ServiceControllerStatus.Running
ServiceControllerStatus.Stopped

Si une erreur est rencontrée, aucune valeur n’est retournée.

Syntaxe

Get-CosmosDbEmulatorStatus 
    [[-AlternativeInstallLocation] <String>] 
    [<CommonParameters>]

Paramètres

Nom	Type	Description
`AlternativeInstallLocation`	`String`

Exemples

Obtenez l’état d’un émulateur installé dans le dossier D:\SomeFolder\AzureCosmosDBEmulator.

@parameters = {
    AlternativeInstallLocation = "D:\SomeFolder\AzureCosmosDBEmulator"
}
Get-CosmosDbEmulatorStatus @parameters

`Start-CosmosDbEmulator`

Démarre l’émulateur sur l’ordinateur local. Par défaut, la commande attend que l’émulateur soit prêt à accepter les requêtes. Utilisez l’option -NoWait si vous souhaitez que la cmdlet soit retournée dès le démarrage de l’émulateur. Utilisez les paramètres de Start-CosmosDbEmulator pour spécifier des options, telles que le port NoSQL, le port direct et les numéros de port MongoDB.

Syntaxe

Start-CosmosDbEmulator [-AllowNetworkAccess]
    [-AlternativeInstallLocation <String>] [-CassandraPort <UInt16>]
    [-ComputePort <UInt16>] [-Consistency <String>] [-Credential
    <PSCredential>] [-DataPath <String>] [-DefaultPartitionCount
    <UInt16>] [-DirectPort <UInt16[]>] [-EnableMongoDb]
    [-EnableCassandra] [-EnableGremlin] [-EnableTable]
    [-EnableSqlCompute] [-EnablePreview]
    [-FailOnSslCertificateNameMismatch] [-GremlinPort <UInt16>]
    [-TablePort <UInt16>] [-SqlComputePort <UInt16>] [-Key <String>]
    [-MongoPort <UInt16>] [-MongoApiVersion <String>] [-NoFirewall]
    [-NoTelemetry] [-NoUI] [-NoWait] [-PartitionCount <UInt16>] [-Port
    <UInt16>] [-SimulateRateLimiting] [-Timeout <UInt32>] [-Trace]
    [<CommonParameters>]

Paramètres

Nom	Type	Description
`AllowNetworkAccess`	`SwitchParameter`	Autorisez l’accès à partir de toutes les adresses IP attribuées à l’hôte de l’émulateur. Vous devez également spécifier une valeur pour Key ou KeyFile afin d’autoriser l’accès réseau.
`AlternativeInstallLocation`	`String`	Autre chemin d’accès à l’emplacement du fichier exécutable de l’émulateur.
`CassandraPort`	`UInt16`	Numéro de port à utiliser pour l’API de Cassandra. Le port par défaut est `10350`.
`ComputePort`	`UInt16`	Port à utiliser pour le service de passerelle d’interopérabilité de calcul. Le port de sonde du point de terminaison HTTP de la passerelle est calculé comme étant égal à `ComputePort + 79`. Par conséquent, `ComputePort` et `ComputePort + 79` doivent être ouverts et disponibles. Les ports par défaut sont `8900`, `8979`.
`Consistency`	`String`	Définit le niveau de cohérence par défaut de l’émulateur sur Session, Strong, Eventual ou BoundedStaleness. Le niveau par défaut est Session.
`Credential`	`PSCredential`	Spécifie un compte d’utilisateur qui a l’autorisation d’exécuter cette action. Utilisez un nom d'utilisateur, tel que `User01` ou `Domain01\User01`, ou entrez un objet `PSCredential`, tel que l’une des cmdlets `Get-Credential`. Par défaut, l'applet de commande utilise les informations d'identification de l'utilisateur actuel.
`DataPath`	`String`	Chemin d’accès pour stocker des fichiers de données. L’emplacement par défaut des fichiers de données est `$env:LocalAppData\CosmosDbEmulator`.
`DefaultPartitionCount`	`UInt16`	Nombre de partitions à réserver par collection partitionnée. La valeur par défaut est 25, qui est identique à la valeur par défaut du nombre total de partitions.
`DirectPort`	`UInt16`	Liste des quatre ports à utiliser pour la connectivité directe au back-end de l’émulateur. La liste par défaut est `10251`, `10252`, `10253` et `10254`.
`EnableMongoDb`	`SwitchParameter`	Spécifie que l’API du point de terminaison de MongoDB est activée. La valeur par défaut est false.
`EnableCassandra`	`SwitchParameter`	Spécifie que l’API du point de terminaison d’Apache Cassandra est activée. La valeur par défaut est false.
`EnableGremlin`	`SwitchParameter`	Spécifie que l’API du point de terminaison d’Apache Gremlin est activée. La valeur par défaut est false.
`EnableTable`	`SwitchParameter`	Spécifie que l’API du point de terminaison de Table est activée. La valeur par défaut est false.
`EnableSqlCompute`	`SwitchParameter`	Spécifie que l’API est activée pour le point de terminaison de NoSQL. La valeur par défaut est false.
`EnablePreview`	`SwitchParameter`	Permet aux fonctionnalités de l’émulateur en préversion et non entièrement matures d’être activées par défaut.
`FailOnSslCertificateNameMismatch`	`SwitchParameter`	Par défaut, l’émulateur regénère son certificat TLS/SSL auto-signé, si le réseau SAN du certificat n’inclut pas le nom de domaine de l’hôte émulateur, l’adresse IP locale, (v4), `localhost` et `127.0.0.1`. Cette option entraîne l’échec de l’émulateur au démarrage. Vous devez alors utiliser l’option `New-CosmosDbEmulatorCertificate` pour créer et installer un nouveau certificat TLS/SSL auto-signé.
`GremlinPort`	`UInt16`	Numéro de port à utiliser pour l’API d’Apache Gremlin. Le numéro de port par défaut est `8901`.
`TablePort`	`UInt16`	Numéro de port à utiliser pour l’API de Table. Le numéro de port par défaut est `8902`.
`SqlComputePort`	`UInt16`	Numéro de port à utiliser pour l’API de NoSQL. Le numéro de port par défaut est `8903`.
`Key`	`String`	Clé d’autorisation pour l’émulateur. Cette valeur doit être le codage en base 64 d’un vecteur de 64 octets.
`MongoPort`	`UInt16`	Numéro de port à utiliser pour l’API de MongoDB. Le numéro de port par défaut est `10250`.
`MongoApiVersion`	`String`	Spécifie la version à utiliser pour l’API de MongoDB. La version par défaut est `4.0`.
`NoFirewall`	`SwitchParameter`	Spécifie qu’aucune règle de port d’entrée ne doit être ajoutée au pare-feu de l’hôte de l’émulateur.
`NoTelemetry`	`SwitchParameter`	Spécifie que la cmdlet ne doit pas collecter de données pour la session en cours de l’émulateur.
`NoUI`	`SwitchParameter`	Spécifie que la cmdlet ne doit pas présenter l’interface utilisateur ou l’icône de barre des tâches.
`NoWait`	`SwitchParameter`	Spécifie que la cmdlet doit être retournée dès que l’émulateur commence à démarrer. Par défaut, la cmdlet attend que le démarrage soit terminé et que l’émulateur soit prêt à recevoir des requêtes avant d’être retournée.
`PartitionCount`	`UInt16`	Nombre total de partitions allouées par l’émulateur.
`Port`	`UInt16`	Numéro de port du service de passerelle de l’émulateur et l’interface utilisateur web. Le numéro de port par défaut est `8081`.
`SimulateRateLimiting`	`SwitchParameter`
`Timeout`	`UInt32`
`Trace`	`SwitchParameter`

Exemples

Démarrez l’émulateur et attendez qu’il soit entièrement démarré et prêt à accepter les requêtes.
```
Start-CosmosDbEmulator
```
Démarrez l’émulateur avec 5 partitions réservées à chaque collection partitionnée. Le nombre total de partitions est défini sur la valeur par défaut : 25. Par conséquent, le nombre total de collections partitionnées qui peuvent être créées est 5 = 25 partitions / 5 partitions/collection. Chaque collection partitionnée est limitée à 50 GB = 5 partitions * 10 GB / partiton.
```
@parameters = {
    DefaultPartitionCount = 5
}
Start-CosmosDbEmulator @parameters
```

Démarre l’émulateur avec d’autres numéros de port.

@parameters = {
    Port = 443 
    MongoPort = 27017 
    DirectPort = 20001,20002,20003,20004
}
Start-CosmosDbEmulator @parameters

`Stop-CosmosDbEmulator`

Arrête l’émulateur. Par défaut, cette commande attend que l’émulateur soit complètement arrêté. Utilisez l’option -NoWait si vous souhaitez que l’applet de commande soit retournée dès le début du processus d’arrêt de l’émulateur.

Syntaxe

Stop-CosmosDbEmulator 
    [[-AlternativeInstallLocation] <String>]
    [-NoWait] [[-Timeout] <UInt32>] [-Trace] 
    [<CommonParameters>]

Paramètres

Nom	Type	Description
`AlternativeInstallLocation`	`String`
`Timeout`	`UInt32`
`NoWait`	`SwitchParameter`	Spécifie que la cmdlet doit être retournée dès le début de l’arrêt.
`Trace`	`SwitchParameter`

Exemples

@parameters = {
    NoWait = $true
}
Stop-CosmosDbEmulator @parameters

`Uninstall-CosmosDbEmulator`

Désinstalle l’émulateur et supprime éventuellement l’intégralité du contenu de $env:LOCALAPPDATA\CosmosDbEmulator. L’applet de commande garantit que l’émulateur est arrêté avant d’être désinstallé.

Syntaxe

Uninstall-CosmosDbEmulator 
    [-RemoveData] 
    [<CommonParameters>]

Paramètres

Nom	Type	Description
`RemoveData`	`SwitchParameter`	Spécifie que la cmdlet doit supprimer toutes les données après avoir supprimé l’émulateur.

Exemples

@parameters = {
    RemoveData = $false
}
Uninstall-CosmosDbEmulator @parameters

Modifier le nombre de conteneurs par défaut

Par défaut, vous pouvez créer jusqu’à 25 conteneurs de taille fixe (pris en charge uniquement par les kits de développement logiciel SDK Azure Cosmos DB), ou 5 conteneurs illimités à l’aide de l’émulateur. En changeant la valeur PartitionCount, vous pouvez créer jusqu’à 250 conteneurs de taille fixe ou 50 conteneurs illimités, ou n’importe quelle combinaison des deux qui ne dépasse pas 250 conteneurs de taille fixe (sachant qu’un conteneur illimité = 5 conteneurs de taille fixe). Toutefois, il est déconseillé de configurer l’émulateur pour s’exécuter avec plus de 200 conteneurs de taille fixe. En effet, cela ajoute une surcharge aux opérations d’E/S sur le disque, qui entraîne des délais d’attente imprévisibles lors de l’utilisation des API de point de terminaison.

Si vous tentez de créer un conteneur après le dépassement du nombre de partitions actuel, l’émulateur lève une exception ServiceUnavailable et affiche un message similaire à celui-ci.

Sorry, we are currently experiencing high demand in this region, and cannot fulfill your request at this time. We work continuously to bring more and more capacity online, and encourage you to try again.
ActivityId: 12345678-1234-1234-1234-123456789abc

Pour changer le nombre de conteneurs disponibles dans l’émulateur , exécutez les étapes suivantes :

Supprimez toutes les données locales de l’émulateur en cliquant avec le bouton droit sur l’icône Émulateur dans la barre d’état système, puis en cliquant sur Réinitialisation des données....
Supprimez toutes les données de l’émulateur dans le dossier %LOCALAPPDATA%\CosmosDBEmulator.
Quittez toutes les instances ouvertes en cliquant avec le bouton droit sur l’icône Émulateur dans la barre d’état système, puis en cliquant sur Quitter. Quitter l’ensemble des instances peut prendre une minute.
Installer la dernière version de l’émulateur.
Lancez l’émulateur avec l’indicateur PartitionCount en définissant une valeur <= 250. Par exemple : C:\Program Files\emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100.

Références sur la ligne de commande et PowerShell pour l’émulateur Windows (local)

Gérer l’émulateur avec la syntaxe de ligne de commande

Gérer l’émulateur avec les cmdlets PowerShell

`Get-CosmosDbEmulatorStatus`

Syntaxe

Paramètres

Exemples

`Start-CosmosDbEmulator`

Syntaxe

Paramètres

Exemples

`Stop-CosmosDbEmulator`

Syntaxe

Paramètres

Exemples

`Uninstall-CosmosDbEmulator`

Syntaxe

Paramètres

Exemples

Modifier le nombre de conteneurs par défaut

Étapes suivantes

Ressources supplémentaires