Referencia de la línea de comandos y PowerShell para el emulador de Windows (local)

SE APLICA A: NoSQL MongoDB Cassandra Gremlin Table

El emulador de Azure Cosmos DB proporciona un entorno local que emula el servicio Azure Cosmos DB con fines de desarrollo local. Después de instalar el emulador, puede controlarlo con la línea de comandos y los comandos de PowerShell. En este artículo se describe cómo usar los comandos de la línea de comandos y PowerShell para iniciar y detener el emulador, configurar sus opciones y realizar otras operaciones. Tiene que ejecutar los comandos desde la ubicación de instalación.

Importante

Este artículo solo incluye argumentos de línea de comandos para el emulador local de Windows.

Administración del emulador con la sintaxis de línea de comandos

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

Para ver la lista de parámetros, escriba Microsoft.Azure.Cosmos.Emulator.exe /? en el símbolo del sistema.

Parámetro	Descripción	Comando de ejemplo
[Sin argumentos]	Inicia el Emulador con la configuración predeterminada.	Microsoft.Azure.Cosmos.Emulator.exe
[Ayuda]	Muestra la lista de argumentos de la línea de comandos admitidos.	Microsoft.Azure.Cosmos.Emulator.exe /?
GetStatus	Obtiene el estado del emulador. Cada código de salida indica un estado: 1 = Inicio, 2 = Ejecución y 3 = Detenido. Un código de salida negativo indica que se ha producido un error. Se produce ninguna otra salida.	Microsoft.Azure.Cosmos.Emulator.exe /GetStatus
Shutdown	Apaga el emulador.	Microsoft.Azure.Cosmos.Emulator.exe /Shutdown
DataPath	Especifica la ruta de acceso en la que se almacenarán los archivos de datos. El valor predeterminado es %LocalAppdata%\CosmosDBEmulator.	Microsoft.Azure.Cosmos.Emulator.exe /DataPath=E:\SomeDataFolder
Port	Especifica el número de puerto que se utilizará para el emulador. El valor predeterminado es 8081.	Microsoft.Azure.Cosmos.Emulator.exe /Port=65000
ComputePort	Especifica el número de puerto que se utilizará para el servicio de puerta de enlace de interoperabilidad informática. El puerto de sondeo del punto de conexión HTTP de la puerta de enlace se calcula como ComputePort + 79. Por lo tanto, ComputePort y ComputePort + 79 debe estar abiertos y disponibles. El valor predeterminado es 8900.	Microsoft.Azure.Cosmos.Emulator.exe /ComputePort=65100
EnableMongoDbEndpoint=3.2	Habilita la API para MongoDB versión 3.2.	Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.2
EnableMongoDbEndpoint=3.6	Habilita la API para MongoDB versión 3.6.	Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.6
EnableMongoDbEndpoint=4.0	Habilita la API para MongoDB versión 4.0.	Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=4.0
MongoPort	Especifica el número de puerto que se va a usar para la API para MongoDB. El valor predeterminado es 10255.	Microsoft.Azure.Cosmos.Emulator.exe /MongoPort=65200
EnableCassandraEndpoint	Habilita la API para Apache Cassandra.	Microsoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpoint
CassandraPort	Especifica el número de puerto que se utilizará para la API del punto de conexión de Cassandra. El valor predeterminado es 10350.	Microsoft.Azure.Cosmos.Emulator.exe /CassandraPort=65300
EnableGremlinEndpoint	Habilita la API para Apache Gremlin.	Microsoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpoint
GremlinPort	Número de puerto que se usará para la API del punto de conexión de Apache Gremlin. El valor predeterminado es 8901.	Microsoft.Azure.Cosmos.Emulator.exe /GremlinPort=65400
EnableTableEndpoint	Habilita la API para Table.	Microsoft.Azure.Cosmos.Emulator.exe /EnableTableEndpoint
TablePort	Número de puerto que se utilizará para la API del punto de conexión de Azure Table. El valor predeterminado es 8902.	Microsoft.Azure.Cosmos.Emulator.exe /TablePort=65500
KeyFile	Lee la clave de autorización del archivo especificado. Usa la opción /GenKeyFile para generar un archivo de claves.	Microsoft.Azure.Cosmos.Emulator.exe /KeyFile=D:\Keys\keyfile
ResetDataPath	Quita todos los archivos repetidamente de la ruta de acceso especificada. Si no especifica una ruta de acceso, el valor predeterminado es %LOCALAPPDATA%\CosmosDbEmulator.	Microsoft.Azure.Cosmos.Emulator.exe /ResetDataPath
StartTraces	Comienza a recopilar los registros de seguimiento de la depuración mediante LOGMAN.	Microsoft.Azure.Cosmos.Emulator.exe /StartTraces
StopTraces	Deja de recopilar los registros de seguimiento de la depuración mediante LOGMAN.	Microsoft.Azure.Cosmos.Emulator.exe /StopTraces
StartWprTraces	Inicia la recopilación de registros de seguimiento de depuración con la herramienta Windows Performance Recording.	Microsoft.Azure.Cosmos.Emulator.exe /StartWprTraces
StopWprTraces	Detiene la recopilación de registros de seguimiento de depuración con la herramienta Windows Performance Recording.	Microsoft.Azure.Cosmos.Emulator.exe /StopWprTraces
FailOnSslCertificateNameMismatch	De forma predeterminada, el emulador vuelve a generar su certificado TLS/SSL autofirmado, si la SAN del certificado no incluye el nombre de dominio del host del emulador, la dirección IP local (v4), localhosty 127.0.0.1. Con esta opción, en su lugar, se produce un error en el emulador al iniciarse. A continuación, debe usar la opción /GenCert para crear e instalar un nuevo certificado TLS/SSL autofirmado.	Microsoft.Azure.Cosmos.Emulator.exe /FailOnSslCertificateNameMismatch
GenCert	Genera e instala un nuevo certificado TLS/SSL autofirmado. opcionalmente, incluir una lista separada por comas de nombres de dominio (DNS) adicionales para acceder al emulador a través de la red.	Microsoft.Azure.Cosmos.Emulator.exe /GenCert
DirectPorts	Especifica los puertos que se usarán para la conectividad directa. Los valores predeterminados son 10251, 10252, 10253 y 10254.	Microsoft.Azure.Cosmos.Emulator.exe /DirectPorts:65600,65700
Key	Clave de autorización para el emulador. La clave debe ser la codificación en base 64 de un vector de 64 bytes.	Microsoft.Azure.Cosmos.Emulator.exe /Key:D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==
EnableRateLimiting	Especifica que el comportamiento de limitación de velocidad de solicitudes está habilitado.	Microsoft.Azure.Cosmos.Emulator.exe /EnableRateLimiting
DisableRateLimiting	Especifica que el comportamiento de limitación de velocidad de solicitudes está deshabilitado.	Microsoft.Azure.Cosmos.Emulator.exe /DisableRateLimiting
NoUI	No muestra la interfaz de usuario del emulador.	Microsoft.Azure.Cosmos.Emulator.exe /NoUI
NoExplorer	No muestra el Explorador de datos en el inicio.	Microsoft.Azure.Cosmos.Emulator.exe /NoExplorer
PartitionCount	Especifica el número máximo de los contenedores particionados. Para más información, consulte cambio del número de contenedores. El valor predeterminado es 25. El máximo permitido es 250.	Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=15
DefaultPartitionCount	Especifica el número predeterminado de particiones para un contenedor. El valor predeterminado es 25.	Microsoft.Azure.Cosmos.Emulator.exe /DefaultPartitionCount=50
AllowNetworkAccess	Permite acceder al emulador a través de una red. También debe pasar /Key=<key_string> o /KeyFile=<file_name> para habilitar el acceso de red.	Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==
NoFirewall	No ajuste las reglas de firewall cuando se utilice la opción /AllowNetworkAccess.	Microsoft.Azure.Cosmos.Emulator.exe /NoFirewall
GenKeyFile	Genere una nueva clave de autorización y guárdela en el archivo especificado. La clave generada se puede utilizar con las opciones /Key o /KeyFile.	Microsoft.Azure.Cosmos.Emulator.exe /GenKeyFile=D:\Keys\keyfile
Consistency	Defina el nivel de coherencia predeterminado de la cuenta. El valor predeterminado es Session.	Microsoft.Azure.Cosmos.Emulator.exe /Consistency=Strong
?	Se muestra el mensaje de ayuda.

Administración del emulador con cmdlets de PowerShell

El emulador incluye un módulo de PowerShell para iniciar, detener, desinstalar y recuperar el estado del servicio. Ejecute el siguiente cmdlet para utilizar el módulo de PowerShell:

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

O bien, coloque el PSModules directorio en PSModulePath y impórtelo como se muestra en el siguiente comando:

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

Este es un resumen de los comandos de control del emulador desde PowerShell:

Get-CosmosDbEmulatorStatus

Obtiene el estado del emulador. Devuelve uno de estos ServiceControllerStatus valores:

• ServiceControllerStatus.StartPending
• ServiceControllerStatus.Running
• ServiceControllerStatus.Stopped

Si se produce un error, no se devuelve ningún valor.

Sintaxis

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

Parámetros

Nombre	Escribir	Descripción
AlternativeInstallLocation	String

Ejemplos

• Obtenga el estado de un emulador instalado en la carpeta D:\SomeFolder\AzureCosmosDBEmulator.

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

Start-CosmosDbEmulator

Inicia el emulador en el equipo local. De forma predeterminada, el comando espera hasta que el emulador está listo para aceptar solicitudes. Utilice la opción -NoWait, si desea que el cmdlet realice la devolución en cuanto inicie el emulador. Use los parámetros de Start-CosmosDbEmulator para especificar opciones, como el puerto NoSQL, el puerto directo y los números de puerto de MongoDB.

Sintaxis

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>]

Parámetros

Nombre	Escribir	Descripción
AllowNetworkAccess	SwitchParameter	Permitir el acceso desde todas las direcciones IP asignadas al host del emulador. También debe especificar un valor para Key o KeyFile para permitir el acceso a la red.
AlternativeInstallLocation	String	Ruta de acceso de ubicación alternativa al ejecutable del emulador.
CassandraPort	UInt16	Número de puerto que se va a usar para la API de Cassandra. El puerto predeterminado es 10350.
ComputePort	UInt16	Puerto que se va a usar para el servicio de puerta de enlace de interoperabilidad de proceso. El puerto de sondeo del punto de conexión HTTP de la puerta de enlace se calcula como ComputePort + 79. Por lo tanto, ComputePort y ComputePort + 79 debe estar abiertos y disponibles. Los puertos predeterminados son 8900, 8979.
Consistency	String	Establece el nivel de coherencia predeterminado del emulador en Session, Strong, Eventual o BoundedStaleness. El nivel predeterminado es Session.
Credential	PSCredential	Especifica una cuenta de usuario con permiso para realizar esta acción. Use un nombre de usuario, como User01 o Domain01\User01, o escriba tanto un objeto PSCredential, como uno del cmdlet Get-Credential. De forma predeterminada, el cmdlet usa las credenciales del usuario actual.
DataPath	String	Ruta de acceso para almacenar archivos de datos. La ubicación predeterminada de los archivos de datos es $env:LocalAppData\CosmosDbEmulator.
DefaultPartitionCount	UInt16	Número de particiones que se reservan por colección con particiones. El valor predeterminado es 25, que es el mismo que el valor predeterminado del recuento total de particiones.
DirectPort	UInt16	Lista de cuatro puertos que se van a usar para la conexión directa con el back-end del emulador. La lista predeterminada es 10251, 10252, 10253, y 10254.
EnableMongoDb	SwitchParameter	Especifica que la API para el punto de conexión de MongoDB está habilitada. El valor predeterminado es false.
EnableCassandra	SwitchParameter	Especifica que la API para el punto de conexión de Apache Cassandra está habilitada. El valor predeterminado es false.
EnableGremlin	SwitchParameter	Especifica que la API para el punto de conexión de Apache Gremlin está habilitada. El valor predeterminado es false.
EnableTable	SwitchParameter	Especifica que la API para el punto de conexión de Table está habilitada. El valor predeterminado es false.
EnableSqlCompute	SwitchParameter	Especifica que la API para el punto de conexión de NoSQL está habilitada. El valor predeterminado es false.
EnablePreview	SwitchParameter	Habilita las características del emulador que están en versión preliminar y que no están totalmente maduras para estar activadas de forma predeterminada.
FailOnSslCertificateNameMismatch	SwitchParameter	De forma predeterminada, el emulador vuelve a generar su certificado TLS/SSL autofirmado, si la SAN del certificado no incluye el nombre de dominio del host del emulador, la dirección IP local (v4), localhosty 127.0.0.1. En su lugar, esta opción hace que el emulador produzca un error en el inicio. A continuación, debe usar la opción New-CosmosDbEmulatorCertificate para crear e instalar un nuevo certificado TLS/SSL autofirmado.
GremlinPort	UInt16	Número de puerto que se va a usar para la API de Apache Gremlin. El número de puerto predeterminado es 8901.
TablePort	UInt16	Número de puerto que se va a usar para la API de Table. El número de puerto predeterminado es 8902.
SqlComputePort	UInt16	Número de puerto que se va a usar para la API de NoSQL. El número de puerto predeterminado es 8903.
Key	String	Clave de autorización para el emulador. Este valor debe ser la codificación base 64 de un vector de 64 bytes.
MongoPort	UInt16	Número de puerto que se va a usar para la API de MongoDB. El número de puerto predeterminado es 10250.
MongoApiVersion	String	Especifica la versión que se va a usar para la API de MongoDB. La versión predeterminada es 4.0.
NoFirewall	SwitchParameter	Especifica que no se deben agregar reglas de puerto de entrada al firewall del host del emulador.
NoTelemetry	SwitchParameter	Especifica que el cmdlet no debe recopilar datos para la sesión del emulador actual.
NoUI	SwitchParameter	Especifica que el cmdlet no debe presentar la interfaz de usuario ni el icono de la barra de tareas.
NoWait	SwitchParameter	Especifica que el cmdlet debe devolver en cuanto el emulador empiece a iniciarse. De forma predeterminada, el cmdlet espera hasta que se complete el inicio y el emulador está listo para recibir solicitudes antes de devolverlas.
PartitionCount	UInt16	Número total de particiones asignadas por el emulador.
Port	UInt16	Número de puerto para el servicio de puerta de enlace del emulador y la interfaz de usuario web. El número de puerto predeterminado es 8081.
SimulateRateLimiting	SwitchParameter
Timeout	UInt32
Trace	SwitchParameter

Ejemplos

• Inicie el emulador y espere hasta que esté listo para aceptar solicitudes.

  Start-CosmosDbEmulator
  

• Inicie el emulador con 5 particiones reservadas para cada colección con particiones. El número total de particiones se establece en el valor predeterminado: 25. Por lo tanto, el número total de colecciones con particiones que se pueden crear es 5 = 25 partitions / 5 partitions/collection. Cada colección con particiones está limitada a 50 GB = 5 partitions * 10 GB / partiton.

  @parameters = {
      DefaultPartitionCount = 5
  }
  Start-CosmosDbEmulator @parameters
  

• Inicia el emulador con números de puerto alternativos.

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

Stop-CosmosDbEmulator

Detiene el emulador. De forma predeterminada, este comando espera hasta que el emulador esté completamente apagado. Utilice la opción -NoWait, si desea que el cmdlet realice la devolución en cuanto el emulador comience el apagado.

Sintaxis

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

Parámetros

Nombre	Escribir	Descripción
AlternativeInstallLocation	String
Timeout	UInt32
NoWait	SwitchParameter	Especifica que el cmdlet debe devolverse en cuanto se inicie el apagado.
Trace	SwitchParameter

Ejemplos

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

Uninstall-CosmosDbEmulator

Desinstala el emulador y, opcionalmente, quita todo el contenido de $env:LOCALAPPDATA\CosmosDbEmulator. El cmdlet garantiza que el emulador se detiene antes de desinstalarlo.

Sintaxis

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

Parámetros

Nombre	Escribir	Descripción
RemoveData	SwitchParameter	Especifica que el cmdlet debe eliminar todos los datos después de quitar el emulador.

Ejemplos

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

Cambio del número de contenedores predeterminados

De forma predeterminada, puede crear hasta 25 contenedores de tamaño fijo (solo se admiten mediante kits de desarrollo de software (SDK) de Azure Cosmos DB o 5 contenedores ilimitados mediante el emulador. Al modificar el valor de PartitionCount, se pueden crear hasta 250 contenedores de tamaño fijo o 50 contenedores ilimitados, o cualquier combinación de los dos que no supere los 250 contenedores de tamaño fijo (un contenedor ilimitado = 5 contenedores de tamaño fijo). Sin embargo, no se recomienda configurar el emulador para que se ejecute con más de 200 contenedores de tamaño fijo. Esto se debe a la sobrecarga añadida a las operaciones de E/S del disco, que producen tiempos de expiración impredecibles al usar las API de punto de conexión.

Si intenta crear un contenedor después de superar el recuento de particiones actual, el emulador inicia una excepción ServiceUnavailable, con el siguiente mensaje.

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

Para cambiar el número de contenedores disponibles en el emulador, ejecute los siguientes pasos:

1. Elimine todos los datos del emulador local haciendo clic con el botón derecho en el icono del emulador de la bandeja del sistema y, luego, haciendo clic en Restablecer datos….

2. Elimine todos los datos del emulador de la carpeta %LOCALAPPDATA%\CosmosDBEmulator.

3. Salga de todas las instancias abiertas haciendo clic con el botón derecho en el icono del emulador de la bandeja del sistema y, luego, haciendo clic en Salir. Todas las instancias pueden tardar un minuto en salir.

4. Instalación de la versión más reciente del emulador.

5. Para iniciar el emulador con la marca PartitionCount, establezca un valor <= 250. Por ejemplo: C:\Program Files\emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100.

Pasos siguientes

• Más información sobre el emulador de Azure Cosmos DB
• Revise las notas de la versión del emulador.