Instale e utilize o Emulador Azure Cosmos DB para desenvolvimento e testes locais

APLICA A: SQL API Cassandra API API API API Table API Azure Cosmos DB API para MongoDB

O Emulador do Azure Cosmos DB fornece um ambiente local que emula o serviço do Azure Cosmos DB para fins de desenvolvimento. Ao utilizar o Emulador do Azure Cosmos DB, pode programar e testar a sua aplicação localmente, sem criar uma subscrição do Azure ou incorrer em custos. Quando estiver satisfeito com o funcionamento da sua aplicação no Emulador Azure Cosmos DB, pode mudar para usar uma conta Azure Cosmos na nuvem. Este artigo descreve como instalar e utilizar o emulador em ambientes Windows, Linux, macOS e Windows Docker.

Transferir o emulador

Para começar, descarregue e instale a versão mais recente do Azure Cosmos DB Emulator no seu computador local. O artigo de lançamento do emulador lista todas as versões disponíveis e as atualizações de funcionalidades que foram feitas em cada versão.

Descarregue o Emulador Azure Cosmos DB

Você pode desenvolver aplicações usando Azure Cosmos DB Emulator com as contas SQL, Cassandra, MongoDB, Gremline Table API. Atualmente, o explorador de dados no emulador suporta totalmente a visualização de dados SQL; os dados criados com recurso a aplicações de clientes MongoDB, Gremlin/Graph e Cassandra não são visualizados neste momento. Para saber mais, consulte como ligar-se ao ponto final do emulador de diferentes APIs.

Como funciona o emulador?

O Emulador do Azure Cosmos DB fornece uma emulação de alta-fidelidade do serviço Azure Cosmos DB. Suporta funcionalidades equivalentes como a DB Azure Cosmos, que inclui a criação de dados, consulta de dados, provisões e dimensionamento de contentores, e a execução de procedimentos e gatilhos armazenados. Você pode desenvolver e testar aplicações usando o Emulador Azure Cosmos DB, e implantá-las para Azure à escala global, atualizando o ponto final de ligação Azure Cosmos DB.

Apesar de a emulação do serviço do Azure Cosmos DB ser fiel, a implementação do emulador é diferente do serviço. Por exemplo, o emulador utiliza componentes standard do SO, como o sistema de ficheiros local para persistência e a pilha de protocolo HTTPS para conectividade. Funcionalidade que se baseia na infraestrutura Azure como a replicação global, latência milissegundo de um dígito para leituras/escritas, e níveis de consistência incapazes não são aplicáveis quando se utiliza o emulador.

Pode migrar dados entre o Emulador Azure Cosmos DB e o serviço DB Azure Cosmos utilizando a Ferramenta de Migração de Dados Azure Cosmos DB.

Diferenças entre o emulador e o serviço de nuvem

Como o Emulador DB Azure Cosmos proporciona um ambiente emulado que funciona na estação de trabalho do desenvolvedor local, existem algumas diferenças na funcionalidade entre o emulador e uma conta Azure Cosmos na nuvem:

  • Atualmente, o painel do Data Explorer no emulador suporta totalmente apenas os clientes API SQL. A visão e operações do Data Explorer para APIs DB Azure Cosmos, tais como MongoDB, Tabela, Gráfico e ApIs cassandra não estão totalmente suportados.

  • O emulador suporta apenas uma única conta fixa e uma chave primária bem conhecida. Não é possível regenerar a tecla quando utilizar o Emulador Azure Cosmos DB, no entanto pode alterar a tecla predefinida utilizando a opção de linha de comando.

  • Com o emulador, pode criar uma conta Azure Cosmos apenas em modo de produção a provisionado; atualmente não suporta o modo sem servidor.

  • O emulador não é um serviço escalável e não suporta um grande número de contentores. Ao utilizar o Emulador Azure Cosmos DB, por padrão, pode criar até 25 recipientes de tamanho fixo a 400 RU/s (apenas suportados com Azure Cosmos DB SDKs), ou 5 contentores ilimitados. Para obter mais informações sobre como alterar este valor, consulte definir o artigo valor partitionCount.

  • O emulador não oferece diferentes níveis de consistência Azure Cosmos DB como o serviço de nuvem oferece.

  • O emulador não oferece replicação multi-região.

  • Como a cópia do seu Azure Cosmos DB Emulator pode nem sempre estar atualizada com as mudanças mais recentes no serviço DB Azure Cosmos, deve sempre consultar o planejador de capacidades DB da Azure Cosmos para estimar com precisão as necessidades de produção (RUs) da sua aplicação.

  • O emulador suporta um tamanho máximo de propriedade de ID de 254 caracteres.

Instale o emulador

Antes de instalar o emulador, certifique-se de que tem os seguintes requisitos de hardware e software:

  • Requisitos de software:

    • Atualmente o Windows Server 2016, 2019 ou o Windows 10 host OS são suportados. O sistema operativo anfitrião com Ative Directory ativado não está atualmente suportado.
    • Sistema operativo de 64 bits
  • Requisitos mínimos de hardware:

    • 2 GB de RAM
    • 10 GB de espaço disponível no disco rígido
  • Para instalar, configurar e executar o Emulador do Azure Cosmos DB, tem de ter privilégios de administrador no computador. O emulador adicionará um certificado e também definirá as regras de firewall para executar os seus serviços. Por conseguinte, os direitos administrativos são necessários para que o emulador possa executar tais operações.

Para começar, descarregue e instale a versão mais recente do Azure Cosmos DB Emulator no seu computador local. Se encontrar algum problema ao instalar o emulador, consulte o artigo de resolução de problemas do emulador para depurar.

Dependendo dos requisitos do seu sistema, pode executar o emulador no Windows, Docker para Windows, Linux ou macOS, conforme descrito nas próximas secções deste artigo.

Verifique se há atualizações do emulador

Cada versão do emulador vem com um conjunto de atualizações de funcionalidades ou correções de erros. Para ver as versões disponíveis, leia o artigo de notas de lançamento do emulador.

Após a instalação, se tiver utilizado as definições predefinidas, os dados correspondentes ao emulador são guardados na localização do %LOCALAPPDATA%\CosmosDBEmulator. Pode configurar uma localização diferente utilizando as definições opcionais do caminho dos dados; que é o /DataPath=PREFERRED_LOCATION parâmetro da linha de comando. Os dados criados numa versão do Azure Cosmos DB Emulator não estão garantidos para serem acessíveis quando se utiliza uma versão diferente. Se precisar de persistir os seus dados a longo prazo, recomenda-se que guarde esses dados numa conta Azure Cosmos, em vez do Emulador Azure Cosmos DB.

Utilize o emulador no Windows

O Emulador Azure Cosmos DB é instalado no C:\Program Files\Azure Cosmos DB Emulator local por defeito. Para iniciar o Emulador DB Azure Cosmos no Windows, selecione o botão Iniciar ou prima a tecla Windows. Comece a escrever Emulador do Azure Cosmos DB e selecione o emulador na lista de aplicações.

Selecione o botão Iniciar ou prima a tecla Windows, comece a digitar o Emulador Azure Cosmos DB e selecione o emulador da lista de aplicações

Quando o emulador tiver começado, verá um ícone na área de notificação da barra de tarefas do Windows. Abre automaticamente o explorador de dados Azure Cosmos no seu navegador neste https://localhost:8081/_explorer/index.html URL URL.

Azure Cosmos DB notificação de barra de tarefa local

Também pode iniciar e parar o emulador a partir da linha de comando ou dos comandos PowerShell. Para obter mais informações, consulte o artigo de referência da ferramenta da linha de comando.

Por predefinição, o Emulador do Azure Cosmos DB é executado no computador local ("localhost") que está a escutar na porta 8081. O endereço é apresentado como https://localhost:8081/_explorer/index.html. Se fechar o explorador e quiser abri-lo novamente mais tarde, pode abrir o URL no browser ou iniciá-lo a partir do Emulador do Azure Cosmos DB no Ícone de Tabuleiro de Windows, conforme mostrado abaixo.

Lançador local de explorador de dados Azure Cosmos

Utilize o emulador no Linux ou no macOS

Atualmente, o Emulador Azure Cosmos DB só pode ser executado no Windows. Se estiver a utilizar o Linux ou o macOS, pode executar o emulador numa máquina virtual Windows hospedada num hipervisor, como Paralelos ou VirtualBox.

Nota

Sempre que reinicia a máquina virtual do Windows que está hospedada num hipervisor, tem de reimportar o certificado porque o endereço IP da máquina virtual muda. A importação do certificado não é necessária no caso de ter configurado a máquina virtual para preservar o endereço IP.

Utilize os seguintes passos para utilizar o emulador em ambientes Linux ou macOS:

  1. Executar o seguinte comando a partir da máquina virtual do Windows e tome nota do endereço IPv4:

    ipconfig.exe
    
  2. Dentro da sua aplicação, altere o URL do ponto final para utilizar o endereço IPv4 devolvido ipconfig.exe em vez de localhost .

  3. A partir do Windows VM, lance o Emulador Azure Cosmos DB a partir da linha de comando utilizando as seguintes opções. Para obter mais informações sobre os parâmetros suportados pela linha de comando, consulte a referência da ferramenta da linha de comando do emulador:

    Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
    
  4. Finalmente, você precisa resolver o processo de confiança do certificado entre a aplicação em execução no ambiente Linux ou Mac e o emulador. Pode utilizar uma das duas opções seguintes para resolver o certificado:

    1. Importar o certificado emulador TLS/SSL para o ambiente Linux ou Mac ou
    2. Desativar a validação TLS/SSL na aplicação

Opção 1: Importar o certificado emulador TLS/SSL

As seguintes secções mostram como importar o certificado emulador TLS/SSL para ambientes Linux e macOS.

Ambiente linux

Se estiver a trabalhar no Linux, relés .NET no OpenSSL para fazer a validação:

  1. Exportar o certificado em formato PFX. A opção PFX está disponível na escolha de exportar a chave privada.

  2. Copie o ficheiro PFX para o seu ambiente Linux.

  3. Converter o ficheiro PFX num ficheiro CRT

    openssl pkcs12 -in YourPFX.pfx -clcerts -nokeys -out YourCTR.crt
    
  4. Copie o ficheiro CRT para a pasta que contém certificados personalizados na sua distribuição Linux. Comumente nas distribuições de Debian, está localizado em /usr/local/share/ca-certificates/ .

    cp YourCTR.crt /usr/local/share/ca-certificates/
    
  5. Atualize os certificados TLS/SSL, que atualizarão a /etc/ssl/certs/ pasta.

    update-ca-certificates
    

ambiente macOS

Utilize os seguintes passos se estiver a trabalhar no Mac:

  1. Exportar o certificado em formato PFX. A opção PFX está disponível na escolha de exportar a chave privada.

  2. Copie o ficheiro PFX para o seu ambiente Mac.

  3. Abra a aplicação Keychain Access e importe o ficheiro PFX.

  4. Abra a lista de Certificados e identifique o com o localhost nome.

  5. Abra o menu de contexto para esse item em particular, selecione Get Item e em Trust Ao utilizar > esta opção de certificado, selecione Always Trust.

    Abra o menu de contexto para esse item em particular, selecione Get Item e em Trust - Quando utilizar esta opção de certificado, selecione Always Trust

Opção 2: Desativar a validação SSL na aplicação

A desativação da validação SSL só é recomendada para fins de desenvolvimento e não deve ser feita quando funciona num ambiente de produção. Os exemplos a seguir mostram como desativar a validação SSL para aplicações .NET e Node.js.

Para qualquer aplicação em execução num quadro compatível com .NET Standard 2.1 ou posterior, podemos aproveitar o CosmosClientOptions.HttpClientFactory seguinte:

CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
{
    HttpClientFactory = () =>
    {
        HttpMessageHandler httpMessageHandler = new HttpClientHandler()
        {
            ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
        };

        return new HttpClient(httpMessageHandler);
    },
    ConnectionMode = ConnectionMode.Gateway
};


CosmosClient client = new CosmosClient(endpoint, authKey, cosmosClientOptions);

Permitir o acesso ao emulador numa rede local

Se tiver várias máquinas utilizando uma única rede, e se configurar o emulador numa máquina e quiser aceder a ela a partir de outra máquina. Nesse caso, é necessário permitir o acesso ao emulador numa rede local.

Pode executar o emulador numa rede local. Para permitir o acesso à rede, especifique a /AllowNetworkAccess opção na linha de comando,que também requer que especifique /Key=key_string ou /KeyFile=file_name . Pode utilizar /GenKeyFile=file_name para gerar um ficheiro com uma chave aleatória. Então podes passar isso para /KeyFile=file_name /Key=contents_of_file ou.

Para permitir o acesso à rede pela primeira vez, o utilizador deve desligar o emulador e eliminar o diretório de dados do emulador %LOCALAPPDATA%\CosmosDBEmulator.

Autenticar ligações ao utilizar o emulador

Tal como no Azure Cosmos DB na cloud, todos os pedidos que fizer relativamente ao Emulador do Azure Cosmos DB têm de ser autenticados. O Emulador Azure Cosmos DB suporta apenas uma comunicação segura via TLS. O Emulador DB Azure Cosmos suporta uma única conta fixa e uma chave de autenticação bem conhecida para a autenticação da chave primária. Esta conta e chave são as únicas credenciais permitidas para utilização com o Emulador do Azure Cosmos DB. A saber:

Account name: localhost:<port>
Account key: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

Nota

A chave primária suportada pelo Emulador Azure Cosmos DB destina-se a ser utilizada apenas com o emulador. Não é possível utilizar a conta e chave do Azure Cosmos DB com o Emulador do Azure Cosmos DB.

Nota

Se tiver iniciado o emulador com a opção /Chave, utilize a chave gerada em vez da tecla predefinida C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== . Para obter mais informações sobre a opção /Chave, consulte a referência da ferramenta da linha de comando.

Ligue-se a diferentes APIs com o emulador

API SQL

Assim que tiver o emulador do Azure Cosmos DB em execução no seu ambiente de trabalho, pode utilizar qualquer SDK do Azure Cosmos DB ou API REST do Azure Cosmos DB suportados para interagir com o emulador. O Azure Cosmos DB Emulator também inclui um explorador de dados incorporado que permite criar recipientes para API SQL ou Azure Cosmos DB para Mongo DB API. Ao utilizar o explorador de dados, pode visualizar e editar itens sem escrever qualquer código.

// Connect to the Azure Cosmos DB Emulator running locally
CosmosClient client = new CosmosClient(
   "https://localhost:8081", 
    "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==");

API do Azure Cosmos DB para MongoDB

Assim que tiver o Emulador Azure Cosmos DB a funcionar no seu ambiente de trabalho, pode utilizar a API da Azure Cosmos DB para a MongoDB interagir com o emulador. Inicie o emulador a partir do pedido de comando como administrador com "/EnableMongoDbEndpoint". Em seguida, utilize o seguinte fio de ligação para ligar à conta API mongodb:

mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true

API de Tabela

Assim que tiver o Emulador Azure Cosmos DB a funcionar no seu ambiente de trabalho, pode utilizar a Azure Cosmos DB Table API SDK para interagir com o emulador. Inicie o emulador a partir do pedido de comando como administrador com "/EnableTableEndpoint". Em seguida, executar o seguinte código para ligar à conta API tabela:

using Microsoft.WindowsAzure.Storage;
using Microsoft.WindowsAzure.Storage.Table;
using CloudTable = Microsoft.WindowsAzure.Storage.Table.CloudTable;
using CloudTableClient = Microsoft.WindowsAzure.Storage.Table.CloudTableClient;

string connectionString = "DefaultEndpointsProtocol=http;AccountName=localhost;AccountKey=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==;TableEndpoint=http://localhost:8902/;";

CloudStorageAccount account = CloudStorageAccount.Parse(connectionString);
CloudTableClient tableClient = account.CreateCloudTableClient();
CloudTable table = tableClient.GetTableReference("testtable");
table.CreateIfNotExists();
table.Execute(TableOperation.Insert(new DynamicTableEntity("partitionKey", "rowKey")));

API de Cassandra

Inicie o emulador a partir de um pedido de comando do administrador com "/EnableCassandraEndpoint". Em alternativa, também pode definir a variável AZURE_COSMOS_EMULATOR_CASSANDRA_ENDPOINT=true ambiente.

  1. Instalar Python 2.7

  2. Instalar Cassandra CLI/CQLSH

  3. Executar os seguintes comandos numa janela de pedido de comando regular:

    set Path=c:\Python27;%Path%
    cd /d C:\sdk\apache-cassandra-3.11.3\bin
    set SSL_VERSION=TLSv1_2
    set SSL_VALIDATE=false
    cqlsh localhost 10350 -u localhost -p C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw== --ssl
    
  4. Na concha CQLSH, executar os seguintes comandos para ligar ao ponto final de Cassandra:

    CREATE KEYSPACE MyKeySpace WITH replication = {'class':'MyClass', 'replication_factor': 1};
    DESCRIBE keyspaces;
    USE mykeyspace;
    CREATE table table1(my_id int PRIMARY KEY, my_name text, my_desc text);
    INSERT into table1 (my_id, my_name, my_desc) values( 1, 'name1', 'description 1');
    SELECT * from table1;
    EXIT
    

API do Gremlin

Inicie o emulador a partir de um pedido de comandodo administrador com "/EnableGremlinEndpoint". Em alternativa, também pode definir a variável ambiental AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=true

  1. Instale apache-tinkerpop-gremlin-consola-3.3.4.

  2. A partir do explorador de dados do emulador, cria-se uma base de dados "db1" e uma coleção "coll1"; para a chave de partição, escolha "/nome"

  3. Executar os seguintes comandos numa janela de pedido de comando regular:

    cd /d C:\sdk\apache-tinkerpop-gremlin-console-3.3.4-bin\apache-tinkerpop-gremlin-console-3.3.4
    
    copy /y conf\remote.yaml conf\remote-localcompute.yaml
    notepad.exe conf\remote-localcompute.yaml
      hosts: [localhost]
      port: 8901
      username: /dbs/db1/colls/coll1
      password: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
      connectionPool: {
      enableSsl: false}
      serializer: { className: org.apache.tinkerpop.gremlin.driver.ser.GraphSONMessageSerializerV1d0,
      config: { serializeResultToString: true  }}
    
    bin\gremlin.bat
    
  4. Na concha de Gremlin, executar os seguintes comandos para ligar ao ponto final de Gremlin:

    :remote connect tinkerpop.server conf/remote-localcompute.yaml
    :remote console
    :> g.V()
    :> g.addV('person1').property(id, '1').property('name', 'somename1')
    :> g.addV('person2').property(id, '2').property('name', 'somename2')
    :> g.V()
    

Desinstalar o emulador local

Utilize os seguintes passos para desinstalar o emulador:

  1. Saia de todas as instâncias abertas do emulador local clicando à direita no ícone emulador Azure Cosmos DB na bandeja do sistema e, em seguida, selecione Saída. Pode demorar um minuto para que todas as instâncias possam sair.

  2. Na caixa de pesquisa do Windows, escreva apps & funcionalidades e selecione apps & resultado (definições do sistema).

  3. Na lista de aplicações, percorra o Emulador Azure Cosmos DB, selecione-o, clique em Desinstalar, e depois confirme e selecione Desinstalar novamente.

Passos seguintes

Neste artigo, aprendeu a usar o emulador local para o desenvolvimento local gratuito. Pode agora passar para os próximos artigos: