Emulador baseado em Linux (versão prévia)

2025-04-18

A próxima geração do emulador do Azure Cosmos DB é inteiramente baseada em Linux e está disponível como um contêiner do Docker. Ele dá suporte à execução em uma ampla variedade de processadores e sistemas operacionais.

Importante

Esta versão do emulador dá suporte apenas à API para NoSQL no modo de gateway, com um subconjunto de recursos selecionado. Para obter mais informações, consulte suporte de funcionalidades.

Pré-requisitos

Docker

Instalação

Obter a imagem de contêiner do Docker usando docker pull. A imagem do contêiner é publicada no Registro de Artefato da Microsoft como mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview.

docker pull mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview

Executando

Para executar o contêiner, use docker run. Posteriormente, use docker ps para validar se o contêiner está em execução.

docker run --detach --publish 8081:8081 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview

docker ps

CONTAINER ID   IMAGE                                                             COMMAND                  CREATED         STATUS         PORTS                                                                                  NAMES
c1bb8cf53f8a   mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview  "/bin/bash -c /home/…"   5 seconds ago   Up 5 seconds   0.0.0.0:1234->1234/tcp, :::1234->1234/tcp, 0.0.0.0:8081->8081/tcp, :::8081->8081/tcp   <container-name>

Observação

O emulador é composto por dois componentes:

Data explorer – explore interativamente os dados no emulador. Por padrão, isso é executado na porta 1234
Emulador do Azure Cosmos DB – uma versão local do serviço de banco de dados do Azure Cosmos DB. Por padrão, isso é executado na porta 8081.

O ponto de extremidade do gateway do emulador normalmente está disponível na porta 8081 no endereço http://localhost:8081. Para navegar até o data explorer, use o endereço http://localhost:1234 no navegador da Web. Pode levar alguns segundos para que o data explorer esteja disponível. O ponto de extremidade do gateway normalmente está disponível imediatamente.

Importante

Os SDKs .NET e Java não suportam o modo HTTP no emulador. Como essa versão do emulador começa com HTTP por padrão, você precisará habilitar explicitamente o HTTPS ao iniciar o contêiner (veja abaixo). Para o Java SDK, você também precisará instalar certificados.

docker run --detach --publish 8081:8081 --publish 1234:1234 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview --protocol https

Comandos do Docker

A tabela a seguir resume os comandos do Docker disponíveis para configurar o emulador. Esta tabela detalha os argumentos correspondentes, variáveis de ambiente, valores permitidos, configurações padrão e descrições de cada comando.

Requisito	Argh	Env	Valores permitidos	Padrão	Descrição
Imprimir as configurações para stdout do contêiner	`--help`, `-h`	N/D	N/A	N/D	Exibir informações sobre a configuração disponível
Definir a porta do ponto de extremidade do Cosmos	`--port [INT]`	PORTO	INT	8081	A porta do ponto de extremidade do Cosmos no contêiner. Você ainda precisa publicar essa porta (por exemplo, `-p 8081:8081`).
Especificar o protocolo usado pelo ponto de extremidade do Cosmos	`--protocol`	PROTOCOLO	`https`, `http`, `https-insecure`	`http`	O protocolo do ponto de extremidade do Cosmos no contêiner.
Habilitar o explorador de dados	`--enable-explorer`	ENABLE_EXPLORER	`true`, `false`	`true`	Habilite a execução do Cosmos Data Explorer no mesmo contêiner.
Definir a porta usada pelo data explorer	`--explorer-port`	EXPLORER_PORT	INT	1234	A porta do Cosmos Data Explorer no contêiner. Você ainda precisa publicar essa porta (por exemplo, `-p 1234:1234`).
O usuário deve ser capaz de especificar o protocolo usado pelo gerenciador, caso contrário, padrão para o que o ponto de extremidade do Cosmos está usando	`--explorer-protocol`	EXPLORER_PROTOCOL	`https`, `http`, `https-insecure`	`<the value of --protocol>`	O protocolo do Cosmos Data Explorer no contêiner. O padrão é a configuração do protocolo no ponto de extremidade do Cosmos.
Especificar a chave por meio do arquivo	`--key-file [PATH]`	KEY_FILE	Caminho	`<default secret>`	Substitua a chave padrão pela chave especificada no arquivo. Você precisará montar este arquivo no contêiner (por exemplo, se KEY_FILE=/mykey, você deve adicionar um parâmetro como o seguinte ao comando docker run: `--mount type=bind,source=./myKey,target=/myKey`)
Definir o caminho de dados	`--data-path [PATH]`	DATA_PATH	Caminho	`/data`	Especifique um diretório para dados. Usado com frequência com a opção `docker run --mount` (por exemplo, se DATA_PATH=/usr/cosmos/data, você adicionará uma opção como a seguinte à execução do docker: `--mount type=bind,source=./.local/data,target=/usr/cosmos/data`)
Especificar o caminho do certificado a ser usado para https	`--cert-path [PATH]`	CERT_PATH	PATH	`<default cert>`	Especifique um caminho para um certificado para proteger o tráfego. Você precisa montar esse arquivo no contêiner (por exemplo, se CERT_PATH=/mycert.pfx, adicione uma opção como a seguinte ao executar o docker: `--mount type=bind,source=./mycert.pfx,target=/mycert.pfx`)
Especificar o segredo do certificado a ser usado para https	N/D	CERT_SECRET	string	`<default secret>`	O segredo do certificado especificado no CERT_PATH.
Definir o nível de log	`--log-level [LEVEL]`	LOG_LEVEL	`quiet`, `error`, `warn`, `info`, `debug`, `trace`	`info`	A verbosidade dos logs emitidos pelo emulador e pelo data explorer.
Habilitar informações de diagnóstico que estão sendo enviadas à Microsoft	`--enable-telemetry`	ATIVAR_TELEMETRIA	`true`, `false`	`true`	Habilite o envio de logs para a Microsoft para nos ajudar a melhorar o emulador.

Suporte a funcionalidades

Esse emulador está em desenvolvimento ativo e versão prévia. Como resultado, nem todos os recursos do Azure Cosmos DB têm suporte. Alguns recursos também não terão suporte no futuro. Esta tabela inclui o estado de vários recursos e seu nível de suporte.

Recurso	Suporte
API do Lote	✅ Com suporte
API em massa	✅ Com suporte
Feed de Alterações	⚠️ Ainda não implementado
Criar e ler documento com dados utf	✅ Com suporte
Criar coleção	✅ Com suporte
Criar conflito de coleção duas vezes	✅ Com suporte
Criar coleção com a política de índice personalizada	⚠️ Ainda não implementado
Criar coleção com expiração de ttl	⚠️ Ainda não implementado
Criar banco de dados	✅ Com suporte
Criar banco de dados duas vezes em conflito	✅ Com suporte
Criar documento	✅ Com suporte
Criar coleção particionada	⚠️ Ainda não implementado
Excluir coleção	✅ Suportado
Excluir banco de dados	✅ Com suporte
Excluir documento	✅ Com suporte
Obter e alterar o desempenho da coleção	⚠️ Ainda não implementado
Inserir documento grande	✅ Com suporte
Documento de patch	⚠️ Ainda não implementado
Consultar coleção particionada em paralelo	⚠️ Ainda não implementado
Consulta com agregações	⚠️ Ainda não implementado
Consultar com e filtrar	⚠️ Ainda não implementado
Consultar com e filtrar e projeção	⚠️ Ainda não implementado
Consulta com igualdade	✅ Com suporte
Consulta com iguais na ID	✅ Com suporte
Consultar com junções	⚠️ Ainda não implementado
Consulta com ordem por	✅ Suportado
Consulta com ordem por para coleção particionada	⚠️ Ainda não implementado
Consultar com ordem por números	✅ Com suporte
Consultar com ordem por cadeias de caracteres	⚠️ Ainda não implementado
Consulta com paginação	⚠️ Ainda não implementado
Horários de data de consulta com operadores de intervalo	⚠️ Ainda não implementado
Consulta com operadores de intervalo em números	⚠️ Ainda não implementado
Consulta com operadores de intervalo em cadeias de caracteres	⚠️ Ainda não implementado
Consulta com junção única	⚠️ Ainda não implementado
Consulta com operadores de matriz e matemática de cadeia de caracteres	⚠️ Ainda não implementado
Consulta com subdocumentos	⚠️ Ainda não implementado
Consultar com duas junções	⚠️ Ainda não implementado
Consultar com duas junções e filtrar	⚠️ Ainda não implementado
Coleção de leitura	✅ Com suporte
Feed de coleta de leitura	⚠️ Ainda não implementado
Ler banco de dados	✅ Suportado
Ler fluxo do banco de dados	⚠️ Ainda não implementado
Ler documento	✅ Com suporte
Ler fluxo de documentos	✅ Com suporte
Substituir documento	✅ Com suporte
Unidades de Solicitação	⚠️ Ainda não implementado
Procedimentos armazenados	❌ Não planejado
Gatilhos	❌ Não planejado
UDFs	❌ Não planejado
Atualizar coleção	⚠️ Ainda não implementado
Atualizar documento	✅ Com suporte

Limitações

Além dos recursos ainda não compatíveis ou não planejados, a lista a seguir inclui as limitações atuais do emulador.

O SDK do .NET para Azure Cosmos DB não dá suporte à execução em massa no emulador.
Os SDKs .NET e Java não suportam o modo HTTP no emulador.

Instalando certificados para Java SDK

Ao usar o Java SDK para Azure Cosmos DB com essa versão do emulador no modo https, é necessário instalar seus certificados no seu repositório confiável Java local.

Obter certificado

Em uma janela bash, execute o seguinte:

# If the emulator was started with /AllowNetworkAccess, replace localhost with the actual IP address of it:
EMULATOR_HOST=localhost
EMULATOR_PORT=8081
EMULATOR_CERT_PATH=/tmp/cosmos_emulator.cert
openssl s_client -connect ${EMULATOR_HOST}:${EMULATOR_PORT} </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > $EMULATOR_CERT_PATH

Instalar certificado

Navegue até o diretório da instalação do Java onde o arquivo cacerts está localizado (substitua abaixo pelo diretório correto):

cd "C:/Program Files/Eclipse Adoptium/jdk-17.0.10.7-hotspot/bin"

Importe o certificado (pode ser solicitada uma senha, o valor padrão é "changeit"):

keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH

Se você receber um erro porque o alias já existe, exclua-o e execute o procedimento acima novamente:

keytool -cacerts -delete -alias cosmos_emulator

Usar no fluxo de trabalho de integração contínua

Há muitos benefícios em usar contêineres do Docker em pipelines de CI/CD, especialmente para sistemas com estado, como bancos de dados. Isso pode ser em termos de custo-benefício, desempenho, confiabilidade e consistência de seus conjuntos de testes.

O emulador pode ser incorporado como parte de pipelines de CI/CD. Você pode consultar este repositório GitHub que fornece exemplos de como usar o emulador como parte de um fluxo de trabalho de CI do GitHub Actions para aplicativos .NET, Python, Java e Go em arquiteturas x64 e ARM64 (demonstrado para executor no Linux usando ubuntu).

Aqui está um exemplo de um fluxo de trabalho de CI do GitHub Actions que mostra como configurar o emulador como um contêiner de serviço do GitHub Actions como parte de um trabalho no fluxo de trabalho. O GitHub cuida de iniciar o contêiner do Docker e o destrói quando o trabalho é concluído, sem a necessidade de intervenção manual (como usar o docker run comando).

name: CI demo app

on:
  push:
    branches: [main]
    paths:
      - 'java-app/**'
  pull_request:
    branches: [main]
    paths:
      - 'java-app/**'

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    services:
      cosmosdb:
        image: mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview
        ports:
          - 8081:8081
        env:
          PROTOCOL: https
        
    env:
      COSMOSDB_CONNECTION_STRING: ${{ secrets.COSMOSDB_CONNECTION_STRING }}
      COSMOSDB_DATABASE_NAME: ${{ vars.COSMOSDB_DATABASE_NAME }}
      COSMOSDB_CONTAINER_NAME: ${{ vars.COSMOSDB_CONTAINER_NAME }}

    steps:

      - name: Set up Java
        uses: actions/setup-java@v3
        with:
          distribution: 'microsoft'
          java-version: '21.0.0'

      - name: Export Cosmos DB Emulator Certificate
        run: |

          sudo apt update && sudo apt install -y openssl

          openssl s_client -connect localhost:8081 </dev/null | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > cosmos_emulator.cert

          cat cosmos_emulator.cert

          $JAVA_HOME/bin/keytool -cacerts -importcert -alias cosmos_emulator -file cosmos_emulator.cert -storepass changeit -noprompt
      
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Run tests
        run: cd java-app && mvn test

Esse trabalho é executado em um executor do Ubuntu e usa a imagem do mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview Docker como um contêiner de serviço. Ele usa variáveis de ambiente para configurar a cadeia de conexão, o nome do banco de dados e o nome do contêiner. Como nesse caso o trabalho está sendo executado diretamente no computador executor do GitHub Actions, a etapa Executar testes no trabalho pode acessar o emulador está acessível usando localhost:8081 (8081 é a porta exposta pelo emulador).

A etapa Exportar Certificado do Emulador do Cosmos DB é específica para aplicativos Java, pois o SDK java do Azure Cosmos DB atualmente não dá suporte HTTP ao modo no emulador. A PROTOCOL variável de ambiente é definida https na services seção e essa etapa exporta o certificado do emulador e o importa para o repositório de chaves Java. O mesmo também se aplica ao .NET.

Problemas de relatórios

Se você encontrar problemas com o uso desta versão do emulador, abra um problema no repositório GitHub (https://github.com/Azure/azure-cosmos-db-emulator-docker) e marque-o com o rótulo cosmosEmulatorVnextPreview.