Emulador basado en Linux (versión preliminar)

2025-04-16

La próxima generación del emulador de Azure Cosmos DB está totalmente basada en Linux y está disponible como contenedor de Docker. Admite la ejecución en una amplia variedad de procesadores y sistemas operativos.

Importante

Esta versión del emulador solo admite la API para NoSQL en modo de puerta de enlace, con un subconjunto selecto de características. Para obtener más información, consulte compatibilidad con características.

Requisitos previos

Docker

Instalación

Obtenga la imagen de contenedor de Docker mediante docker pull. La imagen de contenedor se publica en el Registro de artefactos Microsoft como mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview.

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

En ejecución

Para ejecutar el contenedor, use docker run. Después, use docker ps para validar que el contenedor se está ejecutando.

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:

El emulador consta de dos componentes:

Explorador de datos: explore interactivamente los datos en el emulador. De manera predeterminada, esto se ejecuta en el puerto 1234
Emulador de Azure Cosmos DB: una versión local del servicio de base de datos de Azure Cosmos DB. De manera predeterminada, esto se ejecuta en el puerto 8081.

El punto de conexión de puerta de enlace del emulador suele estar disponible en el puerto 8081 en la dirección http://localhost:8081. Para navegar al explorador de datos, use la dirección http://localhost:1234 en el explorador web. El explorador de datos puede tardar unos segundos en estar disponible. Normalmente, el punto de conexión de puerta de enlace está disponible inmediatamente.

Importante

Los SDK de .NET y Java no admiten el modo HTTP en el emulador. Dado que esta versión del emulador comienza con HTTP de forma predeterminada, deberá habilitar explícitamente HTTPS al iniciar el contenedor (consulte a continuación). Para el SDK de Java, también tendrá que instalar certificados.

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

Comandos de Docker

En la tabla siguiente se resumen los comandos de Docker disponibles para configurar el emulador. En esta tabla se detallan los argumentos correspondientes, las variables de entorno, los valores permitidos, la configuración predeterminada y las descripciones de cada comando.

Requisito	Arg	Env	Valores permitidos	Valor predeterminado	Descripción
Imprimir la configuración en stdout desde el contenedor	`--help`, `-h`	N/D	N/D	N/D	Mostrar información sobre la configuración disponible
Configura el puerto del punto de conexión de Cosmos	`--port [INT]`	PUERTO	INT	8081	Puerto del punto de conexión de Cosmos en el contenedor. Todavía tiene que publicar este puerto (por ejemplo, `-p 8081:8081`).
Especificación del protocolo usado por el punto de conexión de Cosmos	`--protocol`	PROTOCOLO	`https`, `http`, `https-insecure`	`http`	Protocolo del punto de conexión de Cosmos en el contenedor.
Habilitación del explorador de datos	`--enable-explorer`	ENABLE_EXPLORER	`true`, `false`	`true`	Habilite la ejecución del Explorador de datos de Cosmos en el mismo contenedor.
Establecimiento del puerto usado por el explorador de datos	`--explorer-port`	EXPLORER_PORT	INT	1234	Puerto del Explorador de datos de Cosmos en el contenedor. Todavía tiene que publicar este puerto (por ejemplo, `-p 1234:1234`).
El usuario debe poder especificar el protocolo usado por el explorador; de lo contrario, el valor predeterminado es lo que usa el punto de conexión de Cosmos.	`--explorer-protocol`	EXPLORER_PROTOCOL	`https`, `http`, `https-insecure`	`<the value of --protocol>`	Protocolo del Explorador de datos de Cosmos en el contenedor. El valor predeterminado es la configuración de protocolo en el punto de conexión de Cosmos.
Especificar la clave a través del archivo	`--key-file [PATH]`	KEY_FILE	Ruta	`<default secret>`	Invalide la clave predeterminada con la clave especificada en el archivo. Debe montar este archivo en el contenedor (por ejemplo, si KEY_FILE=/mykey, agregaría una opción como la siguiente a la ejecución de Docker: `--mount type=bind,source=./myKey,target=/myKey`)
Establecimiento de la ruta de acceso de datos	`--data-path [PATH]`	DATA_PATH	RUTA	`/data`	Especifique un directorio para los datos. Se usa con frecuencia con la opción `docker run --mount` (por ejemplo, si DATA_PATH=/usr/cosmos/data, agregaría una opción como la siguiente a la ejecución de Docker: `--mount type=bind,source=./.local/data,target=/usr/cosmos/data`)
Especificar la ruta de acceso del certificado que se va a usar para https	`--cert-path [PATH]`	CERT_PATH	Ruta	`<default cert>`	Especifique una ruta de acceso a un certificado para proteger el tráfico. Debe montar este archivo en el contenedor (por ejemplo, si CERT_PATH=/mycert.pfx, agregaría una opción como la siguiente a la ejecución de Docker: `--mount type=bind,source=./mycert.pfx,target=/mycert.pfx`)
Especificar el secreto de certificado que se va a usar para https	N/D	CERT_SECRET	cadena	`<default secret>`	Secreto del certificado especificado en CERT_PATH.
Establecimiento del nivel de registro	`--log-level [LEVEL]`	LOG_LEVEL	`quiet`, `error`, `warn`, `info`, `debug`, `trace`	`info`	La verbosidad de los registros emitidos por el emulador y el explorador de datos.
Habilitación de la información de diagnóstico que se envía a Microsoft	`--enable-telemetry`	HABILITAR_TELEMETRÍA	`true`, `false`	`true`	Habilite el envío de registros a Microsoft para ayudarnos a mejorar el emulador.

Compatibilidad de características

Este emulador está en desarrollo activo y versión preliminar. Como resultado, no se admiten todas las características de Azure Cosmos DB. Algunas características tampoco se admitirán en el futuro. En esta tabla se incluye el estado de varias características y su nivel de compatibilidad.

Característica	Soporte técnico
Batch API	✅ Soportado
Bulk API	✅ Soportado
Fuente de cambios	⚠ todavía no se ha implementado
Creación y lectura de documentos con datos utf	✅ Soportado
Crear una colección	✅ Soportado
Creación de una colección dos veces en conflicto	✅ Compatible
Creación de una colección con una directiva de índice personalizada	⚠ todavía no se ha implementado
Creación de una colección con expiración de ttl	⚠ todavía no se ha implementado
Crear una base de datos	✅ Soportado
Creación de una base de datos dos veces en conflicto	✅ Compatible
Creación de un documento	✅ Compatible
Crear colección particionada	⚠ todavía no se ha implementado
Eliminar colección	✅ Compatible
Eliminar base de datos	✅ Soportado
Eliminación de un documento	✅ Compatible
Obtención y cambio del rendimiento de la recopilación	⚠ todavía no se ha implementado
Insertar documento grande	✅ Soportado
Documento de revisión	⚠ todavía no se ha implementado
Consultar colección particionada en paralelo	⚠ todavía no se ha implementado
Consulta con agregados	⚠ todavía no se ha implementado
Consulta con y filtro	⚠ todavía no se ha implementado
Consulta con y filtrado y proyección	⚠ todavía no se ha implementado
Consulta con igualdad	✅ Soportado
Consulta con igual en el identificador	✅ Soportado
Consulta con combinaciones	⚠ todavía no se ha implementado
Consulta con orden por	✅ Soportado
Consulta con orden para la colección con particiones	⚠ todavía no se ha implementado
Consulta con orden por números	✅ Soportado
Consulta con orden por cadenas	⚠ todavía no se ha implementado
Consulta con paginación	⚠ todavía no se ha implementado
Consulta con operadores de intervalos de fecha y hora	⚠ todavía no se ha implementado
Consulta con operadores de intervalo en números	⚠ todavía no se ha implementado
Consulta con operadores de intervalo en cadenas	⚠ todavía no se ha implementado
Consulta con combinación única	⚠ todavía no se ha implementado
Consulta con operadores de cadena, matemáticos y de matriz	⚠ todavía no se ha implementado
Consulta con subdocumentos	⚠ todavía no se ha implementado
Consulta con dos combinaciones	⚠ todavía no se ha implementado
Consulta con dos combinaciones y filtro	⚠ todavía no se ha implementado
Leer colección	✅ Soportado
Leer fuente de recopilación	⚠ todavía no se ha implementado
Leer la base de datos	✅ Compatible
Leer fuente de base de datos	⚠ todavía no se ha implementado
Lectura de un documento	✅ Soportado
Leer flujo de documentos	✅ Soportado
Reemplazar documento	✅ Compatible
Unidades de solicitud	⚠ todavía no se ha implementado
procedimientos almacenados	❌ no planeado
Desencadenadores	❌ no planeado
UDFs	❌ no planeado
Actualizar una colección	⚠ todavía no se ha implementado
Actualizar documento	✅ Soportado

Limitaciones

Además de las características que aún no se admiten o no están planeadas, la lista siguiente incluye las limitaciones actuales del emulador.

El SDK de .NET para Azure Cosmos DB no admite la ejecución masiva en el emulador.
Los SDK de .NET y Java no admiten el modo HTTP en el emulador.

Instalación de certificados para el SDK de Java

Al usar el SDK de Java para Azure Cosmos DB con esta versión del emulador en modo https, es necesario instalar sus certificados en el almacén de confianza de Java local.

Obtención del certificado

En una ventana bash, ejecute lo siguiente:

# 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

Instalación del certificado

Vaya al directorio de la instalación de Java donde se encuentra el archivo cacerts (reemplace a continuación por el directorio correcto):

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

Importe el certificado (es posible que se le pida una contraseña, el valor predeterminado es "changeit"):

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

Si recibe un error porque el alias ya existe, elimínelo y vuelva a ejecutar lo anterior:

keytool -cacerts -delete -alias cosmos_emulator

Uso en el flujo de trabajo de integración continua

Hay muchas ventajas para usar contenedores de Docker en canalizaciones de CI/CD, especialmente para sistemas con estado como bases de datos. Esto podría ser en términos de rentabilidad, rendimiento, confiabilidad y coherencia de los conjuntos de pruebas.

El emulador se puede incorporar como parte de las canalizaciones de CI/CD. Puede hacer referencia a este repositorio de GitHub que proporciona ejemplos de cómo usar el emulador como parte de un flujo de trabajo de CI de Acciones de GitHub para aplicaciones .NET, Python, Java y Go en x64 y ARM64 arquitecturas (que se muestran para el ejecutor de Linux mediante ubuntu).

Este es un ejemplo de un flujo de trabajo de CI de Acciones de GitHub que muestra cómo configurar el emulador como un contenedor de servicios de Acciones de GitHub como parte de un trabajo en el flujo de trabajo. GitHub se encarga de iniciar el contenedor de Docker y lo destruye cuando se completa el trabajo, sin necesidad de intervención manual (por ejemplo, mediante el 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 trabajo se ejecuta en un ejecutor de Ubuntu y usa la mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-preview imagen de Docker como contenedor de servicios. Usa variables de entorno para configurar la cadena de conexión, el nombre de la base de datos y el nombre del contenedor. Dado que en este caso el trabajo se ejecuta directamente en la máquina del ejecutor de Acciones de GitHub, el paso Ejecutar pruebas del trabajo puede acceder al emulador es accesible mediante localhost:8081 (8081 es el puerto expuesto por el emulador).

El paso Exportar certificado del emulador de Cosmos DB es específico de las aplicaciones Java, ya que el SDK de Java de Azure Cosmos DB no admite HTTP actualmente el modo en el emulador. La variable de entorno PROTOCOL se establece en https en la sección services y este paso exporta el certificado del emulador y lo importa al almacén de claves de Java. Lo mismo se aplica también a .NET.

Información sobre los problemas

Si tiene problemas con el uso de esta versión del emulador, abra un problema en el repositorio de GitHub (https://github.com/Azure/azure-cosmos-db-emulator-docker) y etiquete con la etiqueta cosmosEmulatorVnextPreview.