Emulador baseado em Linux - vNext (visualização)

2025-04-03

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

Importante

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

Pré-requisitos

Docker

Instalação

Obtenha a imagem do contentor do Docker usando docker pull. A imagem do contêiner é publicada no Microsoft Artifact Registry como mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview.

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

Correr

Para executar o contêiner, use docker run. Depois, 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>

Nota

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.

Normalmente, o ponto de extremidade do gateway do emulador está disponível na porta 8081 no endereço http://localhost:8081. Para navegar até o explorador de dados, 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 esta 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	Arg	Env	Valores permitidos	Predefinido	Descrição
Imprima as configurações para stdout a partir do contêiner	`--help`, `-h`	N/A	N/A	N/A	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 Cosmos no contêiner. Você ainda precisa publicar essa porta (por exemplo, `-p 8081:8081`).
Especifica o protocolo utilizado pelo ponto de extremidade Cosmos	`--protocol`	PROTOCOLO	`https`, `http`, `https-insecure`	`http`	O protocolo do ponto de extremidade Cosmos no contêiner.
Ativar o explorador de dados	`--enable-explorer`	ATIVAR_EXPLORADOR	`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 utilizador deve ser capaz de especificar o protocolo utilizado pelo explorador; caso contrário, deverá ser utilizado o protocolo que o endpoint Cosmos está a usar.	`--explorer-protocol`	Protocolo Explorador	`https`, `http`, `https-insecure`	`<the value of --protocol>`	O protocolo do Cosmos Data Explorer no contêiner. Por padrão, usa-se a configuração do protocolo no ponto de extremidade do Cosmos.
Especifique a chave via arquivo	`--key-file [PATH]`	FICHEIRO_CHAVE	CAMINHO	`<default secret>`	Substitua a chave padrão pela chave especificada no arquivo. Você precisa montar esse arquivo no contêiner (por exemplo, se KEY_FILE=/mykey, você adicionaria uma opção como a seguinte à sua execução do docker: `--mount type=bind,source=./myKey,target=/myKey`)
Definir o caminho de dados	`--data-path [PATH]`	CAMINHO_DE_DADOS	CAMINHO	`/data`	Especifique um diretório para dados. Frequentemente usado com a opção `docker run --mount` (por exemplo, se o DATA_PATH=/usr/cosmos/data, deve adicionar uma opção como a seguinte ao seu comando docker: `--mount type=bind,source=./.local/data,target=/usr/cosmos/data`)
Especifique o caminho de certificado a ser usado para https	`--cert-path [PATH]`	CAMINHO_CERTIFICADO	CAMINHO	`<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, você adicionaria uma opção como a seguinte à execução do docker: `--mount type=bind,source=./mycert.pfx,target=/mycert.pfx`)
Especifique o segredo de certificado a ser usado para https	N/A	CERT_SECRET	cadeia (de caracteres)	`<default secret>`	O segredo para o certificado especificado em CERT_PATH.
Definir o nível de log	`--log-level [LEVEL]`	Nível de Registo	`quiet`, `error`, `warn`, `info`, `debug`, `trace`	`info`	A verbosidade dos logs emitidos pelo emulador e pelo explorador de dados.
Habilitar o envio de informações de diagnóstico para a Microsoft	`--enable-telemetry`	ATIVAR_TELEMETRIA	`true`, `false`	`true`	Habilite o envio de logs para a Microsoft para nos ajudar a melhorar o emulador.

Suporte de funcionalidades

Este emulador está em desenvolvimento ativo e em pré-visualização. Como resultado, nem todos os recursos do Azure Cosmos DB são suportados. No futuro, alguns recursos também deixarão de ser suportados. Esta tabela inclui o estado de vários recursos e seu nível de suporte.

Caraterística	Suporte
API de lote	✅ Suportado
API em massa	✅ Suportado
Alterar feed	✅ Suportado
Criar e ler documentos com dados utf	✅ Suportado
Criar coleção	✅ Suportado
Conflito por criar coleção duas vezes	✅ Suportado
Criar coleção com política de índice personalizada	⚠️ Ainda não implementado
Criar coleção com expiração TTL	✅ Suportado
Criar base de dados	✅ Suportado
Conflito ao criar a base de dados duas vezes	✅ Suportado
Criar documento	✅ Suportado
Criar coleção particionada	✅ Suportado
Excluir coleção	✅ Suportado
Excluir banco de dados	✅ Suportado
Eliminar documento	✅ Suportado
Obter e alterar o desempenho da coleção	⚠️ Ainda não implementado
Inserir documento grande	✅ Suportado
Documento de patch	✅ Suportado
Consultar coleção particionada em paralelo	⚠️ Ainda não implementado
Consulta com agregados	⚠️ Ainda não implementado
Consultar e filtrar	⚠️ Ainda não implementado
Consulta com filtro e projeção	⚠️ Ainda não implementado
Consulta com igualdade	✅ Suportado
Consulta com igual em id	✅ Suportado
Consulta com junções	⚠️ Ainda não implementado
Consulta com ordenação por	✅ Suportado
Consulta por ordem para coleção particionada	⚠️ Ainda não implementado
Consulta com ordem por números	✅ Suportado
Consulta com ordem por cadeias de caracteres	⚠️ Ainda não implementado
Consulta com paginação	⚠️ Ainda não implementado
Consulta com operadores de intervalo de datas e horas	⚠️ 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 simples	⚠️ Ainda não implementado
Consulta com matemática de cadeia de caracteres e operadores de matriz	⚠️ Ainda não implementado
Consulta com subdocumentos	⚠️ Ainda não implementado
Consulta com duas junções	⚠️ Ainda não implementado
Consulta com duas junções e filtro	⚠️ Ainda não implementado
Ler a Coleção	✅ Suportado
Ler fluxo de coleção	⚠️ Ainda não implementado
Ler base de dados	✅ Suportado
Ler feed de banco de dados	⚠️ Ainda não implementado
Ler o documento	✅ Suportado
Ler fluxo de documentos	✅ Suportado
Substituir documento	✅ Suportado
Unidades de Solicitação	⚠️ Ainda não implementado
Procedimentos armazenados	❌ Não previsto
Acionadores	❌ Não previsto
FDU	❌ Não previsto
Atualizar coleção	⚠️ Ainda não implementado
Atualizar documento	✅ Suportado

Limitações

Além dos recursos ainda não suportados 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 oferece 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 esta versão do emulador no modo https, é necessário instalar seus certificados em seu armazenamento confiável Java local.

Obter certificado

Em uma bash janela, 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 de sua instalação java onde cacerts o arquivo 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-lhe pedida uma palavra-passe, o valor predefinido é "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 acima novamente:

keytool -cacerts -delete -alias cosmos_emulator

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

Há muitos benefícios em usar contentores Docker em pipelines de CI/CD, especialmente para sistemas com estado, como bases 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 dos pipelines CI/CD. Você pode consultar este repositório GitHub que fornece exemplos de como usar o emulador como parte de um workflow de CI das GitHub Actions para aplicações .NET, Python, Java e Go em ambas as arquiteturas x64 e ARM64 (demonstrado para o runner Linux usando ubuntu).

Aqui está um exemplo de um fluxo de trabalho de CI de Ações do GitHub que mostra como configurar o emulador como um contêiner de serviço de Ações do GitHub 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

Este trabalho é executado num agente 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 neste caso o trabalho está sendo executado diretamente na máquina executora do GitHub Actions, a etapa Executar testes no trabalho pode acessar o emulador é acessível usando localhost:8081 (8081 é a porta exposta pelo emulador).

A etapa Exportar Certificado de Emulador do Cosmos DB é específica para aplicativos Java, já que o SDK Java do Azure Cosmos DB atualmente não oferece suporte ao HTTP modo no emulador. A PROTOCOL variável de ambiente é definida como https na services seção e esta etapa exporta o certificado do emulador e o importa para o keystore Java. O mesmo se aplica ao .NET também.

Comunicar problemas

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.