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

APLICAÇÕES A: SQL API API para Cassandra Gremlin API API de Tabela Azure Cosmos DB API para a 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 Azure Cosmos DB Emulator, pode mudar para usar uma conta Azure Cosmos na nuvem. Este artigo descreve como instalar e usar o emulador em ambientes Windows, Linux, macOS e Windows estivadores.

Transferir o emulador

Para começar, faça o download 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 Azure Cosmos DB Emulator

Você pode desenvolver aplicações usando Azure Cosmos DB Emulator com as contas SQL, Cassandra, MongoDB, Gremlin e 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, fornecimento e dimensionamento de contentores, e a execução de procedimentos e gatilhos armazenados. Você pode desenvolver e testar aplicações usando o Azure Cosmos DB Emulator, 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 Emulator Azure Cosmos 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 Azure Cosmos DB Emulator 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 de Data Explorer no emulador suporta totalmente apenas SQL clientes da API. A Data Explorer visão e operações para APIs DB Azure Cosmos, tais como MongoDB, Table, Graph e Cassandra APIs não estão totalmente apoiadas.

  • O emulador suporta apenas uma única conta fixa e uma chave primária bem conhecida. Não é possível regenerar a chave quando utilizar o DB DB Azure Cosmos Emulator, 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 Azure Cosmos DB Emulator, 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 o artigo de 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 Windows Server 2016, 2019 ou Windows 10 os so anfitriões são apoiados. 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, faça o download e instale a versão mais recente do Azure Cosmos DB Emulator no seu computador local. Se encontrar problemas 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 em Windows, Docker para Windows, Linux ou macOS, conforme descrito nas próximas secções deste artigo.

Verifique se há atualizações de emuladores

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_LOCATIONparâmetro como a linha de comando. Os dados criados numa versão do Azure Cosmos DB Emulator não é garantido que sejam 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 Azure Cosmos DB Emulator.

Use o emulador no Windows

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

Select the Start button or press the Windows key, begin typing Azure Cosmos DB Emulator, and select the emulator from the list of applications

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

Azure Cosmos DB local emulator task bar notification

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.

Azure Cosmos local emulator data explorer launcher

Utilize o emulador no Linux ou no macOS

Atualmente, o Emulator de Azure Cosmos só pode ser executado em Windows. Se estiver a utilizar o Linux ou o macOS, recomendamos que utilize o Emulator Linux (Preview) ou execute o emulador numa máquina virtual Windows hospedada num hipervisor, como Paralelos ou VirtualBox.

Nota

Sempre que reinicia a Windows máquina virtual 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 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 em ipconfig.exe vez de localhost.

  3. A partir do Windows VM, lance o Azure Cosmos DB Emulator 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

Use 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 nome localhost.

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

    Open the context menu for that particular item, select Get Item and under Trust - When using this certificate option, select 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.HttpClientFactoryseguinte:

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 acessá-lo 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 opção /AllowNetworkAccess 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 ou /Key=contents_of_file.

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 Azure Cosmos DB Emulator suporta apenas uma comunicação segura via TLS. O Azure Cosmos DB Emulator suporta uma única conta fixa e uma chave de autenticação bem conhecida para a autenticação de chaves primárias. 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 Azure Cosmos DB Emulator 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.

Ligação 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 SQL API 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 Azure Cosmos DB Emulator a funcionar no seu ambiente de trabalho, pode utilizar a API da Azure Cosmos 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 Azure Cosmos DB Emulator a funcionar no seu ambiente de trabalho, pode utilizar o Azure Cosmos DB API de Tabela 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=trueambiente.

  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 comando de 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 DB DB do Azure Cosmos Emulator na bandeja do sistema e, em seguida, selecione Exit. Pode demorar um minuto para que todas as instâncias possam sair.

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

  3. Na lista de aplicações, percorra o Azure Cosmos DB Emulator, selecione-o, clique em Desinstalar e, em seguida, 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: