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

Artigo
09/12/2023

APLICA-SE A: NoSQL MongoDB Cassandra Gremlin Tabela

O emulador do Azure Cosmos DB fornece um ambiente local que emula o serviço do Azure Cosmos DB para fins de desenvolvimento local. Depois de instalar o emulador, pode controlar o emulador com a linha de comandos e os comandos do PowerShell. Este artigo descreve como utilizar a linha de comandos e os comandos do PowerShell para iniciar e parar o emulador, configurar opções e executar outras operações. Tem de executar os comandos a partir da localização de instalação.

Importante

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

Gerir o emulador com a sintaxe da linha de comandos

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

Para ver a lista de parâmetros, escreva Microsoft.Azure.Cosmos.Emulator.exe /? na linha de comandos.

Parâmetro	Description	Comando de Exemplo
[Sem argumentos]	Inicia o emulador com predefinições.	Microsoft.Azure.Cosmos.Emulator.exe
[Ajuda]	Mostra a lista dos argumentos da linha de comandos suportados.	`Microsoft.Azure.Cosmos.Emulator.exe /?`
`GetStatus`	Obtém o estado do emulador. Cada código de saída indica um estado: `1` = Iniciar, = `2`Em Execução e `3` = Parado. Um código de saída negativo indica que ocorreu um erro. Não é produzido outro resultado.	`Microsoft.Azure.Cosmos.Emulator.exe /GetStatus`
`Shutdown`	Encerra o emulador.	`Microsoft.Azure.Cosmos.Emulator.exe /Shutdown`
`DataPath`	Especifica o caminho onde pretende armazenar os ficheiros de dados. O valor predefinido é `%LocalAppdata%\CosmosDBEmulator`.	`Microsoft.Azure.Cosmos.Emulator.exe /DataPath=E:\SomeDataFolder`
`Port`	Especifica o número de porta a utilizar para o emulador. O valor predefinido é `8081`.	`Microsoft.Azure.Cosmos.Emulator.exe /Port=65000`
`ComputePort`	Especifica o número de porta a utilizar para o serviço de gateway interop de computação. A porta de pesquisa de ponto final HTTP do gateway é calculada como `ComputePort + 79`. Por conseguinte, `ComputePort` tem `ComputePort + 79` de estar aberto e disponível. O valor predefinido é `8900`.	`Microsoft.Azure.Cosmos.Emulator.exe /ComputePort=65100`
`EnableMongoDbEndpoint=3.2`	Ativa a API para MongoDB versão 3.2.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.2`
`EnableMongoDbEndpoint=3.6`	Ativa a API para a versão 3.6 do MongoDB.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=3.6`
`EnableMongoDbEndpoint=4.0`	Ativa a API para a versão 4.0 do MongoDB.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableMongoDbEndpoint=4.0`
`MongoPort`	Especifica o número de porta a utilizar para a API para MongoDB. O valor predefinido é `10255`.	`Microsoft.Azure.Cosmos.Emulator.exe /MongoPort=65200`
`EnableCassandraEndpoint`	Ativa a API para Apache Cassandra.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableCassandraEndpoint`
`CassandraPort`	Especifica o número de porta a utilizar para a API para o ponto final do Cassandra. O valor predefinido é `10350`.	`Microsoft.Azure.Cosmos.Emulator.exe /CassandraPort=65300`
`EnableGremlinEndpoint`	Ativa a API para o Apache Gremlin.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableGremlinEndpoint`
`GremlinPort`	Número de porta a utilizar para a API para o Ponto Final do Apache Gremlin. O valor predefinido é `8901`.	`Microsoft.Azure.Cosmos.Emulator.exe /GremlinPort=65400`
`EnableTableEndpoint`	Ativa a API para Tabela.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableTableEndpoint`
`TablePort`	Número de porta a utilizar para a API para o Ponto Final da Tabela. O valor predefinido é `8902`.	`Microsoft.Azure.Cosmos.Emulator.exe /TablePort=65500`
`KeyFile`	Leia a chave de autorização do ficheiro especificado. Utilize a opção `/GenKeyFile` para gerar um keyfile.	`Microsoft.Azure.Cosmos.Emulator.exe /KeyFile=D:\Keys\keyfile`
`ResetDataPath`	Remove recursivamente todos os ficheiros no caminho especificado. Se não especificar um caminho, a predefinição é `%LOCALAPPDATA%\CosmosDbEmulator`.	`Microsoft.Azure.Cosmos.Emulator.exe /ResetDataPath`
`StartTraces`	Comece a recolher registos de rastreio de depuração com o LOGMAN.	`Microsoft.Azure.Cosmos.Emulator.exe /StartTraces`
`StopTraces`	Pare de recolher registos de rastreio de depuração com o LOGMAN.	`Microsoft.Azure.Cosmos.Emulator.exe /StopTraces`
`StartWprTraces`	Comece a recolher registos de rastreio de depuração com a ferramenta Gravação de Desempenho do Windows .	`Microsoft.Azure.Cosmos.Emulator.exe /StartWprTraces`
`StopWprTraces`	Pare de recolher registos de rastreio de depuração com a ferramenta Gravação de Desempenho do Windows .	`Microsoft.Azure.Cosmos.Emulator.exe /StopWprTraces`
`FailOnSslCertificateNameMismatch`	Por predefinição, o emulador regenera o certificado TLS/SSL autoassinado, se o SAN do certificado não incluir o nome de domínio do anfitrião do emulador, o endereço IP local (v4), `localhost`e `127.0.0.1`. Com esta opção, o emulador falha no arranque. Em seguida, deve utilizar 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 aceder ao emulador através da rede.	`Microsoft.Azure.Cosmos.Emulator.exe /GenCert`
`DirectPorts`	Especifica as portas a utilizar para conectividade direta. As predefiniçõ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 tem de ser a codificação 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 pedidos está ativado.	`Microsoft.Azure.Cosmos.Emulator.exe /EnableRateLimiting`
`DisableRateLimiting`	Especifica que o comportamento de limitação da taxa de pedidos está desativado.	`Microsoft.Azure.Cosmos.Emulator.exe /DisableRateLimiting`
`NoUI`	Não mostrar a interface de utilizador do emulador.	`Microsoft.Azure.Cosmos.Emulator.exe /NoUI`
`NoExplorer`	Não mostrar o explorador de dados no arranque.	`Microsoft.Azure.Cosmos.Emulator.exe /NoExplorer`
`PartitionCount`	Especifica o número máximo de contentores particionados. Para obter mais informações, veja Alterar o número de contentores. O valor predefinido é `25`. O máximo permitido é `250`.	`Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=15`
`DefaultPartitionCount`	Especifica o número predefinido de partições para um contentor particionado. O valor predefinido é `25`.	`Microsoft.Azure.Cosmos.Emulator.exe /DefaultPartitionCount=50`
`AllowNetworkAccess`	Permite o acesso ao emulador através de uma rede. Também tem de transmitir `/Key=<key_string>` ou /`KeyFile=<file_name>` para ativar o acesso à rede.	`Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=D67PoU0bcK/kgPKFHu4W+3SUY9LNcwcFLIUHnwrkA==`
`NoFirewall`	Não ajuste as regras da firewall quando `/AllowNetworkAccess` for utilizada a opção.	`Microsoft.Azure.Cosmos.Emulator.exe /NoFirewall`
`GenKeyFile`	Gerar uma nova chave de autorização e guardá-la no ficheiro especificado. A chave gerada pode ser utilizada com as `/Key` opções ou `/KeyFile` .	`Microsoft.Azure.Cosmos.Emulator.exe /GenKeyFile=D:\Keys\keyfile`
`Consistency`	Defina o nível de consistência predefinida para a conta. O valor predefinido é Sessão.	`Microsoft.Azure.Cosmos.Emulator.exe /Consistency=Strong`
`?`	Mostrar a mensagem de ajuda.

Gerir o emulador com cmdlets do PowerShell

O emulador inclui um módulo do PowerShell para iniciar, parar, desinstalar e obter o estado do serviço. Execute o seguinte cmdlet para utilizar o módulo do PowerShell:

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

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

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

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

`Get-CosmosDbEmulatorStatus`

Obtém o estado do emulador. Devolve um destes ServiceControllerStatus valores:

ServiceControllerStatus.StartPending
ServiceControllerStatus.Running
ServiceControllerStatus.Stopped

Se for encontrado um erro, não é devolvido nenhum valor.

Sintaxe

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

Parâmetros

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

Exemplos

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

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

`Start-CosmosDbEmulator`

Inicia o emulador no computador local. Por predefinição, o comando aguarda até que o emulador esteja pronto para aceitar pedidos. Utilize a opção -NoWait se pretender que o cmdlet regresse assim que iniciar o emulador. Utilize os parâmetros de para especificar opções, como a porta NoSQL, a porta direta e os números de Start-CosmosDbEmulator 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	Tipo	Description
`AllowNetworkAccess`	`SwitchParameter`	Permitir o acesso de todos os Endereços IP atribuídos ao anfitrião do emulador. Também tem de especificar um valor para Chave ou KeyFile para permitir o acesso à rede.
`AlternativeInstallLocation`	`String`	Caminho de localização alternativo para o executável do emulador.
`CassandraPort`	`UInt16`	Número de porta a utilizar para a API para Cassandra. A porta predefinida é `10350`.
`ComputePort`	`UInt16`	Porta a utilizar para o serviço de gateway interop de computação. A porta de pesquisa de ponto final HTTP do gateway é calculada como `ComputePort + 79`. Por conseguinte, `ComputePort` tem `ComputePort + 79` de estar aberto e disponível. As portas predefinidas são `8900`, `8979`.
`Consistency`	`String`	Define o nível de consistência predefinido do emulador como Sessão, Forte, Eventual ou BoundedStaleness. O nível predefinido é Sessão.
`Credential`	`PSCredential`	Especifica uma conta de utilizador com permissão para efetuar esta ação. Utilize um nome de utilizador, como `User01` ou `Domain01\User01`, ou introduza um objeto, como um `PSCredential` do `Get-Credential` cmdlet . Por predefinição, o cmdlet utiliza as credenciais do utilizador atual.
`DataPath`	`String`	Caminho para armazenar ficheiros de dados. A localização predefinida para ficheiros de dados é `$env:LocalAppData\CosmosDbEmulator`.
`DefaultPartitionCount`	`UInt16`	O número de partições a reservar por coleção particionada. A predefinição é 25, que é o mesmo que o valor predefinido da contagem total de partições.
`DirectPort`	`UInt16`	Uma lista de quatro portas a utilizar para conectividade direta ao back-end do emulador. A lista predefinida é `10251`, `10252`, `10253`e `10254`.
`EnableMongoDb`	`SwitchParameter`	Especifica que a API para o ponto final do MongoDB está ativada. A predefinição é false.
`EnableCassandra`	`SwitchParameter`	Especifica que a API para o ponto final do Apache Cassandra está ativada. A predefinição é false.
`EnableGremlin`	`SwitchParameter`	Especifica que a API para o ponto final do Apache Gremlin está ativada. A predefinição é false.
`EnableTable`	`SwitchParameter`	Especifica que a API para o ponto final de Tabela está ativada. A predefinição é false.
`EnableSqlCompute`	`SwitchParameter`	Especifica que a API para o ponto final NoSQL está ativada. A predefinição é false.
`EnablePreview`	`SwitchParameter`	Ativa as funcionalidades do emulador que estão em pré-visualização e que não estão totalmente maduras para estarem ativadas por predefinição.
`FailOnSslCertificateNameMismatch`	`SwitchParameter`	Por predefinição, o emulador regenera o certificado TLS/SSL autoassinado, se o SAN do certificado não incluir o nome de domínio do anfitrião do emulador, o endereço IP local (v4), `localhost`e `127.0.0.1`. Esta opção faz com que o emulador falhe no arranque. Em seguida, deve utilizar a opção `New-CosmosDbEmulatorCertificate` para criar e instalar um novo certificado TLS/SSL autoassinado.
`GremlinPort`	`UInt16`	Número de porta a utilizar para a API para Apache Gremlin. O número de porta predefinido é `8901`.
`TablePort`	`UInt16`	Número de porta a utilizar para a API para Tabela. O número de porta predefinido é `8902`.
`SqlComputePort`	`UInt16`	Número de porta a utilizar para a API para NoSQL. O número de porta predefinido é `8903`.
`Key`	`String`	Chave de autorização para o emulador. Este valor tem de ser a codificação base 64 de um vetor de 64 bytes.
`MongoPort`	`UInt16`	Número de porta a utilizar para a API para MongoDB. O número de porta predefinido é `10250`.
`MongoApiVersion`	`String`	Especifica a versão a utilizar para a API para MongoDB. A versão predefinida é `4.0`.
`NoFirewall`	`SwitchParameter`	Especifica que não devem ser adicionadas regras de porta de entrada à firewall do anfitrião do emulador.
`NoTelemetry`	`SwitchParameter`	Especifica que o cmdlet não deve recolher dados para a sessão do emulador atual.
`NoUI`	`SwitchParameter`	Especifica que o cmdlet não deve apresentar a interface de utilizador ou o ícone da barra de tarefas.
`NoWait`	`SwitchParameter`	Especifica que o cmdlet deve ser devolvido assim que o emulador começar a iniciar. Por predefinição, o cmdlet aguarda até o arranque estar concluído e o emulador está pronto para receber pedidos antes de regressar.
`PartitionCount`	`UInt16`	O número total de partições alocadas pelo emulador.
`Port`	`UInt16`	Número de porta do Serviço de Gateway do emulador e da IU da Web. O número de porta predefinido é `8081`.
`SimulateRateLimiting`	`SwitchParameter`
`Timeout`	`UInt32`
`Trace`	`SwitchParameter`

Exemplos

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

Inicia o emulador com números de porta alternativos.

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

`Stop-CosmosDbEmulator`

Para o emulador. Por predefinição, este comando aguarda até que o emulador seja totalmente encerrado. Utilize a opção -NoWait, se quiser que o cmdlet seja devolvido assim que o emulador começar a encerrar.

Sintaxe

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

Parâmetros

Nome	Tipo	Description
`AlternativeInstallLocation`	`String`
`Timeout`	`UInt32`
`NoWait`	`SwitchParameter`	Especifica que o cmdlet deve ser devolvido assim que o encerramento 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 assegura que o emulador está parado antes de desinstalá-lo.

Sintaxe

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

Parâmetros

Nome	Tipo	Description
`RemoveData`	`SwitchParameter`	Especifica que o cmdlet deve eliminar todos os dados depois de remover o emulador.

Exemplos

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

Alterar o número de contentores predefinidos

Por predefinição, pode criar até 25 contentores de tamanho fixo (apenas suportados com SDKs do Azure Cosmos DB) ou 5 contentores ilimitados com o emulador. Ao modificar o valor PartitionCount , pode criar até 250 contentores de tamanho fixo ou 50 contentores ilimitados ou qualquer combinação dos dois que não exceda 250 contentores de tamanho fixo (em que um contentor ilimitado = 5 contentores de tamanho fixo). No entanto, não é recomendado configurar o emulador para ser executado com mais de 200 contentores de tamanho fixo. Devido à sobrecarga que adiciona às operações de E/S do disco, o que resulta em tempos limite imprevisíveis ao utilizar as APIs de ponto final.

Se tentar criar um contentor após a contagem de partições atual ter sido excedida, o emulador gera uma exceção ServiceUnavailable, com a seguinte mensagem.

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 contentores disponíveis no emulador, execute os seguintes passos:

Elimine todos os dados do emulador local ao clicar com o botão direito do rato no ícone do emulador no tabuleiro do sistema e, em seguida, ao clicar em Repor Dados....
Elimine todos os dados do emulador nesta pasta %LOCALAPPDATA%\CosmosDBEmulator.
Saia de todas as instâncias abertas ao clicar com o botão direito do rato no ícone do emulador no tabuleiro do sistema e, em seguida, ao clicar em Sair. Pode demorar um minuto para que todas as instâncias possam sair.
Instale a versão mais recente do emulador.
Inicie o emulador com o sinalizador PartitionCount ao definir um valor <= 250. Por exemplo: C:\Program Files\emulator> Microsoft.Azure.Cosmos.Emulator.exe /PartitionCount=100.

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

Gerir o emulador com a sintaxe da linha de comandos

Gerir 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 contentores predefinidos

Passos seguintes

Recursos adicionais