Referência da linha de comando e do PowerShell para o emulador do Windows (local)

Artigo
09/13/2023

APLICA-SE A: NoSQL MongoDB Cassandra Gremlin Table

O emulador do Azure Cosmos DB fornece um ambiente local que emula o serviço do Azure Cosmos DB para fins de desenvolvimento local. Após instalar o emulador, você pode controlar o emulador com comandos do PowerShell e da linha de comando. Este artigo descreve como usar os comandos da linha de comando e do PowerShell para iniciar e parar o emulador, configurar opções e executar outras operações. É necessário executar os comandos a partir do local de instalação.

Importante

Este artigo inclui apenas argumentos de linha de comando para o emulador local do Windows.

Gerenciar o emulador com sintaxe de linha de comando

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

Para exibir a lista de parâmetros, digite Microsoft.Azure.Cosmos.Emulator.exe /? no prompt de comando.

Parâmetro	Descrição	Exemplo de Comando
[No arguments]	Inicia o emulador com as configurações padrão.	Microsoft.Azure.Cosmos.Emulator.exe
[Ajuda]	Exibe a lista de argumentos de linha de comando com suporte.	`Microsoft.Azure.Cosmos.Emulator.exe /?`
`GetStatus`	Obtém o status do emulador. Cada código de saída indica um status: `1` = Iniciando, `2` = Executando e `3` = Parado. Um código de saída negativo indica que ocorreu um erro. Nenhum outro resultado é produzido.	`Microsoft.Azure.Cosmos.Emulator.exe /GetStatus`
`Shutdown`	Desliga o emulador.	`Microsoft.Azure.Cosmos.Emulator.exe /Shutdown`
`DataPath`	Especifica o caminho no qual armazenar os arquivos de dados. O valor padrão é `%LocalAppdata%\CosmosDBEmulator`.	`Microsoft.Azure.Cosmos.Emulator.exe /DataPath=E:\SomeDataFolder`
`Port`	Especifica o número da porta a ser usada para o emulador. O valor padrão é `8081`.	`Microsoft.Azure.Cosmos.Emulator.exe /Port=65000`
`ComputePort`	Especifica o número da porta a ser usada para o serviço de gateway de interoperabilidade de computação. A porta de investigação do ponto de extremidade HTTP do gateway é calculada como `ComputePort + 79`. Portanto, `ComputePort` e `ComputePort + 79` deve estar abertos e disponíveis. O valor padrão é `8900`.	`Microsoft.Azure.Cosmos.Emulator.exe /ComputePort=65100`
`EnableMongoDbEndpoint=3.2`	Habilita a API para MongoDB versão 3.2.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.2`
`EnableMongoDbEndpoint=3.6`	Habilita a API para MongoDB versão 3.6.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.6`
`EnableMongoDbEndpoint=4.0`	Habilita a API para MongoDB versão 4.0.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=4.0`
`MongoPort`	Especifica o número da porta a ser usado para a API para MongoDB. O valor padrão é `10255`.	`Microsoft.Azure.Cosmos.Emulator.exe /MongoPort=65200`
`EnableCassandraEndpoint`	Habilita a API para Apache Cassandra.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpoint`
`CassandraPort`	Especifica o número da porta a ser usada para o ponto de extremidade da API para Cassandra. O valor padrão é `10350`.	`Microsoft.Azure.Cosmos.Emulator.exe /CassandraPort=65300`
`EnableGremlinEndpoint`	Habilita a API para Apache Gremlin.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpoint`
`GremlinPort`	Número da porta a ser usado para ponto de extremidade da API para Apache Gremlin. O valor padrão é `8901`.	`Microsoft.Azure.Cosmos.Emulator.exe /GremlinPort=65400`
`EnableTableEndpoint`	Habilita a API para Tabela.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableTableEndpoint`
`TablePort`	O número da porta a ser usado para o ponto de extremidade da API para Tabela. O valor padrão é `8902`.	`Microsoft.Azure.Cosmos.Emulator.exe /TablePort=65500`
`KeyFile`	A chave de autorização de leitura do arquivo especificado. Use a opção `/GenKeyFile` para gerar um keyfile.	`Microsoft.Azure.Cosmos.Emulator.exe /KeyFile=D:\Keys\keyfile`
`ResetDataPath`	Remove recursivamente todos os arquivos no caminho especificado. Se você não especificar um caminho, o padrão será `%LOCALAPPDATA%\CosmosDbEmulator`.	`Microsoft.Azure.Cosmos.Emulator.exe /ResetDataPath`
`StartTraces`	Inicie a coleta de logs de depuração usando LOGMAN.	`Microsoft.Azure.Cosmos.Emulator.exe /StartTraces`
`StopTraces`	Encerre a coleta de logs de depuração usando LOGMAN.	`Microsoft.Azure.Cosmos.Emulator.exe /StopTraces`
`StartWprTraces`	Comece a coletar logs de rastreamento de depuração usando a ferramenta Windows Performance Recorder.	`Microsoft.Azure.Cosmos.Emulator.exe /StartWprTraces`
`StopWprTraces`	Encerre a coletar logs de rastreamento de depuração usando a ferramenta Windows Performance Recorder.	`Microsoft.Azure.Cosmos.Emulator.exe /StopWprTraces`
`FailOnSslCertificateNameMismatch`	Por padrão o emulador regenera o certificado TLS/SSL autoassinado dele, se o SAN do certificado não inclui nome de domínio do host do emulador, endereço IP local (v4), `localhost` e `127.0.0.1`. Com essa opção, o emulador falha na inicialização. Em seguida, você deve usar a opção `/GenCert` para criar e instalar um novo certificado TLS/SSL autoassinado.	`Microsoft.Azure.Cosmos.Emulator.exe /FailOnSslCertificateNameMismatch`
`GenCert`	Gerar e instalar um novo certificado TLS/SSL autoassinado. opcionalmente incluindo uma lista separada por vírgulas de nomes DNS adicionais para acessar o emulador pela rede.	`Microsoft.Azure.Cosmos.Emulator.exe /GenCert`
`DirectPorts`	Especifica as portas a serem usadas para conectividade direta. Os padrões são `10251`, `10252`, `10253` e `10254`.	`Microsoft.Azure.Cosmos.Emulator.exe /DirectPorts:65600,65700`
`Key`	Chave de autorização para o emulador. A chave deve ser a codificação de base 64 de um vetor de 64 bytes.	`Microsoft.Azure.Cosmos.Emulator.exe /Key:D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==`
`EnableRateLimiting`	Especifica que o comportamento de limitação da taxa de solicitação está habilitado.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableRateLimiting`
`DisableRateLimiting`	Especifica que o comportamento de limitação da taxa de solicitação está desabilitado.	`Microsoft.Azure.Cosmos.Emulator.exe /DisableRateLimiting`
`NoUI`	Não mostra a interface do usuário do emulador.	`Microsoft.Azure.Cosmos.Emulator.exe /NoUI`
`NoExplorer`	Não mostra o Data Explorer na inicialização.	`Microsoft.Azure.Cosmos.Emulator.exe /NoExplorer`
`PartitionCount`	Especifica o número máximo de contêineres particionados. Para obter mais informações, confira alterar o número de contêineres. O valor padrão é `25`. O máximo permitido é `250`.	`Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=15`
`DefaultPartitionCount`	Especifica o número padrão de partições para um contêiner particionado. O valor padrão é `25`.	`Microsoft.Azure.Cosmos.Emulator.exe /DefaultPartitionCount=50`
`AllowNetworkAccess`	Permite o acesso para o emulador através de uma rede. Também é necessário passar `/Key=<key_string>` ou /`KeyFile=<file_name>` para habilitar o acesso de rede.	`Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==`
`NoFirewall`	Não ajuste as regras de firewall quando a opção `/AllowNetworkAccess` for usada.	`Microsoft.Azure.Cosmos.Emulator.exe /NoFirewall`
`GenKeyFile`	Gere uma nova chave de autorização e salve no arquivo especificado. A chave gerada pode ser usada com as opções de `/Key` ou `/KeyFile`.	`Microsoft.Azure.Cosmos.Emulator.exe /GenKeyFile=D:\Keys\keyfile`
`Consistency`	Defina o nível de consistência padrão da conta. O valor padrão é Sessão.	`Microsoft.Azure.Cosmos.Emulator.exe /Consistency=Strong`
`?`	Mostre a mensagem de ajuda.

Gerenciar o emulador com cmdlets do PowerShell

O emulador vem com um módulo PowerShell para iniciar, parar, desinstalar e recuperar o status do serviço. Execute o seguinte cmdlet para usar o módulo do PowerShell:

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

ou coloque o diretório PSModules no seu PSModulePath e importe-o conforme mostrado no comando a seguir:

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

Veja um resumo dos comandos para controlar o emulador do PowerShell:

`Get-CosmosDbEmulatorStatus`

Obtém o status do emulador. Retorna um destes valores ServiceControllerStatus:

ServiceControllerStatus.StartPending
ServiceControllerStatus.Running
ServiceControllerStatus.Stopped

Se um erro for encontrado, nenhum valor será retornado.

Sintaxe

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

Parâmetros

Nome	Type	Descrição
`AlternativeInstallLocation`	`String`

Exemplos

Obtenha o status de um emulador instalado na pasta D:\SomeFolder\AzureCosmosDBEmulator.

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

`Start-CosmosDbEmulator`

Inicia o emulador no computador local. Por padrão, o comando aguarda até que o emulador esteja pronto para aceitar solicitações. Use a opção -NoWait, se quiser que o cmdlet seja retornado assim que ele iniciar o emulador. Use os parâmetros de Start-CosmosDbEmulator para especificar opções, como a porta NoSQL, a porta direta e os números de porta do MongoDB.

Sintaxe

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

Nome	Type	Descrição
`AllowNetworkAccess`	`SwitchParameter`	Permitir o acesso de todos os endereços IP atribuídos ao host do emulador. Você também deve especificar um valor para Key ou KeyFile para permitir o acesso à rede.
`AlternativeInstallLocation`	`String`	Caminho de local alternativo para o executável do emulador.
`CassandraPort`	`UInt16`	Número da porta a ser usado para a API para Cassandra. A porta padrão é `10350`.
`ComputePort`	`UInt16`	Porta a ser usada para o serviço de gateway de interoperabilidade de computação. A porta de investigação do ponto de extremidade HTTP do gateway é calculada como `ComputePort + 79`. Portanto, `ComputePort` e `ComputePort + 79` deve estar abertos e disponíveis. As portas padrão são `8900` e `8979`.
`Consistency`	`String`	Define o nível de consistência padrão do emulador como Sessão, Forte, Eventual ou BoundedStaleness. O nível padrão é Sessão.
`Credential`	`PSCredential`	Especifica uma conta de usuário que tem permissão para executar esta ação. Use um nome de usuário, como `User01` ou `Domain01\User01`, ou insira um `PSCredential` objeto, como um do cmdlet `Get-Credential`. Por padrão, o cmdlet usa as credenciais do usuário atual.
`DataPath`	`String`	Caminho para armazenar arquivos de dados. O local padrão para arquivos de dados é `$env:LocalAppData\CosmosDbEmulator`.
`DefaultPartitionCount`	`UInt16`	A quantidade de partições a serem reservadas por coleção particionada. O padrão é 25, que é o mesmo que o valor padrão da contagem total de partições.
`DirectPort`	`UInt16`	Uma lista de quatro portas a serem usadas para conectividade direta com o back-end do emulador. A lista padrão é `10251`, `10252`, `10253` e `10254`.
`EnableMongoDb`	`SwitchParameter`	Especifica que o ponto de extremidade da API para MongoDB está habilitado. O padrão é false.
`EnableCassandra`	`SwitchParameter`	Especifica que o ponto de extremidade da API para Apache Cassandra está habilitado. O padrão é false.
`EnableGremlin`	`SwitchParameter`	Especifica que o ponto de extremidade da API para Apache Gremlin está habilitado. O padrão é false.
`EnableTable`	`SwitchParameter`	Especifica que o ponto de extremidade da API para Tabela está habilitado. O padrão é false.
`EnableSqlCompute`	`SwitchParameter`	Especifica que o ponto de extremidade da API para NoSQL está habilitado. O padrão é false.
`EnablePreview`	`SwitchParameter`	Habilita os recursos do emulador que estão em versão prévia e não estão totalmente amadurecidos para serem ativados por padrão.
`FailOnSslCertificateNameMismatch`	`SwitchParameter`	Por padrão o emulador regenera o certificado TLS/SSL autoassinado dele, se o SAN do certificado não inclui nome de domínio do host do emulador, endereço IP local (v4), `localhost` e `127.0.0.1`. Essa opção faz com que o emulador falhe na inicialização. Em seguida, você deve usar a opção `New-CosmosDbEmulatorCertificate` para criar e instalar um novo certificado TLS/SSL autoassinado.
`GremlinPort`	`UInt16`	Número da porta a ser usado para a API para Apache Gremlin. O número da porta padrão é `8901`.
`TablePort`	`UInt16`	O número da porta a ser usado para a API para Tabela. O número da porta padrão é `8902`.
`SqlComputePort`	`UInt16`	O número da porta a ser usado para a API para NoSQL. O número da porta padrão é `8903`.
`Key`	`String`	Chave de autorização para o emulador. Este valor deve ser a codificação base-64 de um vetor de 64 bytes.
`MongoPort`	`UInt16`	O número da porta a ser usado para a API para MongoDB. O número da porta padrão é `10250`.
`MongoApiVersion`	`String`	Especifica qual versão usar para a API para MongoDB. A versão padrão é `4.0`.
`NoFirewall`	`SwitchParameter`	Especifica que nenhuma regra de porta de entrada deve ser adicionada ao firewall do host do emulador.
`NoTelemetry`	`SwitchParameter`	Especifica que o cmdlet não deve coletar dados para a sessão atual do emulador.
`NoUI`	`SwitchParameter`	Especifica que o cmdlet não deve apresentar a interface do usuário ou o ícone da barra de tarefas.
`NoWait`	`SwitchParameter`	Especifica que o cmdlet deve retornar assim que o emulador começar a ser iniciado. Por padrão, o cmdlet aguarda até que a inicialização seja concluída e o emulador esteja pronto para receber solicitações antes de retornar.
`PartitionCount`	`UInt16`	O número total de partições alocadas pelo emulador.
`Port`	`UInt16`	Número da porta para o Serviço de Gateway do emulador e a interface do usuário da Web. O número da porta padrão é `8081`.
`SimulateRateLimiting`	`SwitchParameter`
`Timeout`	`UInt32`
`Trace`	`SwitchParameter`

Exemplos

Inicie o emulador e aguarde até que ele seja totalmente iniciado e esteja pronto para aceitar solicitações.
```
Start-CosmosDbEmulator
```
Inicie o emulador com cinco partições reservadas para cada coleção particionada. O número total de partições é definido como o padrão: 25. Portanto, o número total de coleções particionadas que podem ser criadas é 5 = 25 partitions / 5 partitions/collection. Cada coleção particionada é limitada a 50 GB = 5 partitions * 10 GB / partiton.
```
@parameters = {
    DefaultPartitionCount = 5
}
Start-CosmosDbEmulator @parameters
```

Inicia o emulador com números de portas alternativos.

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

`Stop-CosmosDbEmulator`

Parada do emulador. Por padrão, esse comando aguarda até que o emulador seja completamente desligado. Use a opção -NoWait, se quiser que o cmdlet seja retornado assim que o emulador iniciar o desligamento.

Sintaxe

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

Parâmetros

Nome	Type	Descrição
`AlternativeInstallLocation`	`String`
`Timeout`	`UInt32`
`NoWait`	`SwitchParameter`	Especifica que o cmdlet deve retornar assim que o desligamento começar.
`Trace`	`SwitchParameter`

Exemplos

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

`Uninstall-CosmosDbEmulator`

Desinstala o emulador e, opcionalmente, remove o conteúdo completo de $env:LOCALAPPDATA\CosmosDbEmulator O cmdlet garante que o emulador seja parado antes de desinstalá-lo.

Sintaxe

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

Parâmetros

Nome	Type	Descrição
`RemoveData`	`SwitchParameter`	Especifica que o cmdlet deve excluir todos os dados depois de remover o emulador.

Exemplos

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

Alterar o número de contêineres padrão

Por padrão, você pode criar até 25 contêineres de tamanho fixo (com suporte apenas usando os SDKs do Azure Cosmos DB) ou os cinco contêineres ilimitados usando o emulador. Ao modificar o valor do PartitionCount, você poderá criar até 250 contêineres de tamanho fixo ou 50 contêineres ilimitados ou qualquer combinação dos dois que não excedam 250 contêineres de tamanho fixo (em que um contêiner ilimitado = cinco contêineres de tamanho fixo). No entanto, não é recomendado configurar o emulador para executar com mais de 200 contêineres de tamanho fixo. Por causa da sobrecarga que isso adiciona a operações de E/S de disco, que resulta em tempo limite imprevisível ao usar o ponto de extremidade de APIs.

Se você tentar criar contêiner depois que a contagem de partição atual tiver sido excedida, o emulador lançará uma exceção de ServiceUnavailable, com a mensagem de erro a seguir.

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 alterar o número de contêineres disponíveis no emulador, execute as seguintes etapas:

Exclua todos os dados locais do emulador clicando com o botão direito no ícone do emulador na bandeja do sistema e clicando em Redefinir Dados....
Excluir todos os dados de emulador desta pasta %LOCALAPPDATA%\CosmosDBEmulator.
Saia de todas as instâncias clicando com o botão direito no ícone do emulador na bandeja do sistema e clicando em Sair. Pode levar um minuto para que todas as instâncias saiam.
Instalar a versão mais recente do emulador.
Inicie o emulador com o sinalizador PartitionCount definindo um valor <– 250. Por exemplo: C:\Program Files\emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100.

Referência da linha de comando e do PowerShell para o emulador do Windows (local)

Gerenciar o emulador com sintaxe de linha de comando

Gerenciar o emulador com cmdlets do PowerShell

`Get-CosmosDbEmulatorStatus`

Sintaxe

Parâmetros

Exemplos

`Start-CosmosDbEmulator`

Sintaxe

Parâmetros

Exemplos

`Stop-CosmosDbEmulator`

Sintaxe

Parâmetros

Exemplos

`Uninstall-CosmosDbEmulator`

Sintaxe

Parâmetros

Exemplos

Alterar o número de contêineres padrão

Próximas etapas

Recursos adicionais