Emulador basado en Linux (versión preliminar)
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
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
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 |
| Establecimiento del 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 | PATH | <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 | PATH | /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 | PATH | <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 | string | <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 |
El nivel de detalle 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 |
ENABLE_TELEMETRY | 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 | ✅ Compatible |
| Bulk API | ✅ Compatible |
| Fuente de cambios | ⚠ todavía no se ha implementado |
| Creación y lectura de documentos con datos utf | ✅ Compatible |
| Crear una colección | ✅ Compatible |
| 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 | ✅ Compatible |
| Creación de una base de datos dos veces en conflicto | ✅ Compatible |
| Creación de un documento | ✅ Compatible |
| Crear colección de particiones | ⚠ todavía no se ha implementado |
| Eliminar colección | ✅ Compatible |
| Eliminar base de datos | ✅ Compatible |
| 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 | ✅ Compatible |
| Documento de revisión | ⚠ todavía no se ha implementado |
| Colección con particiones consulta 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 | ✅ Compatible |
| Consulta con igual en el identificador | ✅ Compatible |
| Consulta con combinaciones | ⚠ todavía no se ha implementado |
| Consulta con orden por | ✅ Compatible |
| Consulta con orden para la colección con particiones | ⚠ todavía no se ha implementado |
| Consulta con orden por números | ✅ Compatible |
| 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 | ✅ Compatible |
| 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 | ✅ Compatible |
| Leer fuente de documentos | ✅ Compatible |
| Reemplazar documento | ✅ Compatible |
| Unidades de solicitud | ⚠ todavía no se ha implementado |
| procedimientos almacenados | ❌ no planeado |
| Desencadenadores | ❌ no planeado |
| UDF | ❌ no planeado |
| Actualizar una colección | ⚠ todavía no se ha implementado |
| Actualizar documento | ✅ Compatible |
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 instalarlo 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
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.