Partager via


Informations de référence sur la ligne de commande et PowerShell pour l’émulateur Windows (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 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 inclut uniquement des 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 régénère son certificat TLS/SSL auto-signé, si le san du certificat n’inclut pas le nom de domaine de l’hôte de l’émulateur, l’adresse IP locale (v4) localhostet 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é, éventuellement, y compris une liste séparée par des virgules de noms DNS (Domain Name System) supplémentaires 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"

Ou placez le PSModules répertoire sur votre PSModulePath répertoire et importez-le comme indiqué dans 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 régénère son certificat TLS/SSL auto-signé, si le san du certificat n’inclut pas le nom de domaine de l’hôte de l’émulateur, l’adresse IP locale (v4) localhostet 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 prêt à accepter les demandes.

    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 à l’aide des kits de développement logiciel 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, nous vous déconseillons de configurer l’émulateur pour qu’il s’exécute 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 une fois le nombre de partitions actuel dépassé, l’émulateur lève une exception ServiceUnavailable, avec le message suivant.

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 :

  1. 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....

  2. Supprimez toutes les données de l’émulateur dans le dossier %LOCALAPPDATA%\CosmosDBEmulator.

  3. 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. La sortie de toutes les instances peut prendre une minute.

  4. Installer la dernière version de l’émulateur.

  5. 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.

Étapes suivantes