Instalación y uso del emulador de Azure Cosmos DB para desarrollo y pruebas locales

Artículo
03/18/2023
Tiempo de lectura: 14 minutos

SE APLICA A: NoSQL MongoDB Cassandra Gremlin Table

El Emulador de Azure Cosmos DB proporciona un entorno local que emula el servicio de Azure Cosmos DB con fines de desarrollo. Mediante el Emulador de Azure Cosmos DB, puede desarrollar y probar su aplicación localmente, sin crear una suscripción de Azure o realizar algún gasto. Cuando esté satisfecho con el funcionamiento de la aplicación en el Emulador, puede cambiar a una cuenta de Azure Cosmos DB en la nube. En este artículo se describe cómo instalar y usar el emulador en entornos Windows, Linux, macOS y Docker para Windows.

Descarga del emulador

Para empezar, descargue e instale la versión más reciente del emulador de Azure Cosmos DB en el equipo local. En el artículo dedicado a las notas de la versión del emulador se enumeran todas las versiones disponibles y las actualizaciones de características que se realizaron en cada versión.

Descarga del emulador de Azure Cosmos DB

Puede desarrollar aplicaciones mediante el emulador de Azure Cosmos DB con la cuenta mediante API para NoSQL, Apache Cassandra, MongoDB, Apache Gremlin y Table. Actualmente, el explorador de datos del emulador solo admite la visualización de datos SQL. Los datos creados con las aplicaciones cliente de MongoDB, Gremlin/Graph y Cassandra no se pueden ver. Para obtener más información, consulte cómo conectarse al punto de conexión del emulador desde distintas API.

¿Cómo funciona el emulador?

El Emulador de Azure Cosmos DB proporciona una emulación de gran fidelidad del servicio Azure Cosmos DB. Cuenta con una funcionalidad equivalente a la de Azure Cosmos DB, que incluye la creación y la consulta de datos, el aprovisionamiento y el escalado de contenedores, así como la ejecución de procedimientos almacenados y desencadenadores. Puede desarrollar y probar aplicaciones mediante el emulador de Azure Cosmos DB e implementarlas en Azure a escala global actualizando el punto de conexión de Azure Cosmos DB.

Aunque la emulación del servicio Azure Cosmos DB es fiel, la implementación del emulador es diferente de la del servicio. Por ejemplo, el emulador utiliza componentes del sistema operativo estándar; por ejemplo, utiliza el sistema de archivos local para la persistencia y la pila del protocolo HTTPS para la conectividad. Cuando se usa el emulador, no son aplicables las funcionalidades que se basan en la infraestructura de Azure, como la replicación global, la latencia de milisegundos de un solo dígito para lectura/escritura y los niveles de coherencia ajustables.

Diferencias entre el emulador y el servicio en la nube

Dado que el emulador de Azure Cosmos DB proporciona un entorno emulado que se ejecuta en una estación de trabajo de desarrollador local, hay algunas diferencias de funcionalidad entre el emulador y una cuenta de Azure Cosmos en la nube:

Actualmente, el panel Explorador de datos del emulador es totalmente compatible solo con los clientes de la API para NoSQL. La vista del explorador de datos y las operaciones de las API de Azure Cosmos DB, como MongoDB, Table, Graph y Cassandra API no son totalmente compatibles.
El emulador solo admite una única cuenta fija y una clave principal ya conocida. No se puede regenerar la clave cuando se usa el emulador de Azure Cosmos DB; sin embargo, puede cambiar la clave predeterminada mediante la opción de la línea de comandos.
Con el emulador, solo puede crear una cuenta de Azure Cosmos DB en modo de rendimiento aprovisionado. Actualmente no se admite el modo sin servidor.
El emulador no es un servicio escalable y no admite un gran número de contenedores. Cuando se usa el emulador de Azure Cosmos DB, de forma predeterminada se pueden crear hasta 25 contenedores de tamaño fijo a 400 RU/s (solo compatibles con los SDK de Azure Cosmos DB) o 5 contenedores ilimitados. Para obtener más información sobre cómo cambiar este valor, consulte el artículo sobre la configuración del valor de PartitionCount.
El emulador no ofrece diferentes niveles de coherencia de Azure Cosmos DB como hace el servicio en la nube.
El emulador no ofrece replicación en varias regiones.
Es posible que la copia del emulador de Azure Cosmos DB no tenga siempre los cambios más recientes del servicio Azure Cosmos DB, por lo que debe consultar la herramienta de planeamiento de capacidad de Azure Cosmos DB para calcular con precisión las necesidades de capacidad de proceso (RU) de la aplicación.
El emulador admite un tamaño máximo de la propiedad ID de 254 caracteres.

Instalación del emulador

Antes de instalar el emulador, asegúrese de que cumple los siguientes requisitos de hardware y software:

Requisitos de software:
- Actualmente se admiten los sistemas operativos de host Windows Server 2016, 2019 o Windows 10. En estos momentos no se admite el sistema operativo de host con Active Directory habilitado.
- Sistema operativo de 64 bits
Requisitos mínimos de hardware:
- 2 GB de RAM
- 10 GB de espacio disponible en el disco duro
Para instalar, configurar y ejecutar el Emulador de Azure Cosmos DB, debe tener privilegios administrativos en el equipo. El emulador agregará un certificado y también establecerá las reglas de firewall para ejecutar sus servicios. Por lo tanto, se necesitan derechos de administrador para que se puedan ejecutar esas operaciones.

Para empezar, descargue e instale la versión más reciente del emulador de Azure Cosmos DB en el equipo local. Si tiene problemas al instalar el emulador, consulte el artículo de solución de problemas del emulador para corregirlos.

En función de los requisitos del sistema, puede ejecutar el emulador en Windows, Docker para Windows, Linux o macOS, tal como se describe en las siguientes secciones de este artículo.

Búsqueda de actualizaciones del emulador

Cada versión del emulador incluye un conjunto de actualizaciones de características o correcciones de errores. Para ver las versiones disponibles, consulte el artículo de notas de la versión del emulador.

Después de la instalación, si ha usado la configuración predeterminada, los datos correspondientes al emulador se habrán guardado en la ubicación %LOCALAPPDATA%\CosmosDBEmulator. Puede establecer otra ubicación mediante la configuración de la ruta de acceso de datos opcional; es decir, /DataPath=PREFERRED_LOCATION como parámetro de línea de comandos. No se garantiza que los datos que se crean en una versión del emulador de Azure Cosmos DB estén disponibles cuando se utilice una versión diferente. Si necesita conservar los datos a largo plazo, es recomendable que los almacene en una cuenta de Azure Cosmos DB y no en el emulador de Azure Cosmos DB.

Uso del emulador en Windows

El emulador de Azure Cosmos DB se instala de forma predeterminada en C:\Program Files\Azure Cosmos DB Emulator. Para iniciar el emulador de Azure Cosmos DB en Windows, seleccione el botón Inicio o presione la tecla Windows. Comience a escribir Emulador de Azure Cosmos DB y seleccione el emulador de la lista de aplicaciones.

Seleccione el botón Inicio o presione la tecla Windows, comience a escribir

Cuando el emulador se ha iniciado, aparece un icono en el área de notificación de la barra de tareas de Windows. El explorador de datos de Azure Cosmos DB se abre automáticamente en el explorador web, en la dirección URL https://localhost:8081/_explorer/index.html.

Notificación en la barra de tareas del emulador local de Azure Cosmos DB

También puede iniciar y detener el emulador desde la línea de comandos o mediante comandos de PowerShell. Para más información, consulte el artículo de referencia de la herramienta de la línea de comandos.

El Emulador de Azure Cosmos DB se ejecuta de forma predeterminada en la máquina local ("localhost") que escucha en el puerto 8081. La dirección aparece como https://localhost:8081/_explorer/index.html. Si cierra el explorador y desea volver a abrirlo más adelante, puede abrir la dirección URL en el explorador o iniciarlo desde el icono del Emulador de Azure Cosmos DB de la bandeja de Windows, tal como se muestra a continuación.

Iniciador del Explorador de datos del emulador local de Azure Cosmos DB

Uso del emulador en Linux o macOS

Actualmente, el emulador de Azure Cosmos DB solo se puede ejecutar en Windows. Si usa Linux o macOS, recomendamos que use el emulador de Linux (versión preliminar) o ejecute el emulador en una máquina virtual Windows hospedada en un hipervisor como Parallels o VirtualBox.

Nota:

Cada vez que reinicie la máquina virtual Windows hospedada en un hipervisor, tendrá que volver a importar el certificado, porque cambia la dirección IP de la máquina virtual. No tendrá que hacerlo si ha configurado la máquina virtual para conservar la dirección IP.

Siga estos pasos para usar el emulador en entornos Linux o macOS:

Ejecute el siguiente comando desde la máquina virtual Windows y tome nota de la dirección IPv4:
```
ipconfig.exe
```
Dentro de la aplicación, cambie la dirección URL del punto de conexión para usar la dirección IPv4 devuelta por ipconfig.exe en lugar de localhost.
En la máquina virtual Windows, inicie el emulador de Azure Cosmos DB desde la línea de comandos con las siguientes opciones. Para obtener más información sobre los parámetros que se admiten en la línea de comandos, consulte la referencia de la herramienta de línea de comandos del emulador:
```
Microsoft.Azure.Cosmos.Emulator.exe /AllowNetworkAccess /Key=C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==
```
Por último, debe resolver el proceso de confianza del certificado entre la aplicación que se ejecuta en el entorno Linux o Mac y el emulador. Puede usar una de las dos opciones siguientes para resolver el certificado:
1. Importar el certificado TLS/SSL del emulador en el entorno Linux o Mac o bien
2. Deshabilitar la validación TLS/SSL en la aplicación

Opción 1: Importar el certificado TLS/SSL del emulador

En las secciones siguientes se muestra cómo importar el certificado TLS/SSL del emulador en entornos Linux y macOS.

Entorno de Linux

Si trabaja en Linux, .NET se apoya en OpenSSL para realizar la validación:

Exporte el certificado en formato PFX. La opción PFX está disponible al elegir exportar la clave privada.
Copie el archivo PFX en el entorno Linux.

Conversión del archivo PFX en un archivo CRT

openssl pkcs12 -in YourPFX.pfx -clcerts -nokeys -out YourCTR.crt

Copie el archivo CRT en la carpeta que contiene los certificados personalizados de la distribución de Linux. Normalmente, en las distribuciones de Debian, se encuentra en /usr/local/share/ca-certificates/.
```
cp YourCTR.crt /usr/local/share/ca-certificates/
```
Actualice los certificados TLS/SSL, que actualizarán la carpeta /etc/ssl/certs/.
```
update-ca-certificates
```

Entorno de macOS

Siga estos pasos si trabaja en Mac:

Exporte el certificado en formato PFX. La opción PFX está disponible al elegir exportar la clave privada.
Copie el archivo PFX en el entorno Mac.
Abra la aplicación Keychain Access e importe el archivo PFX.
Abra la lista de certificados e identifique el que tiene el nombre localhost.
Abra el menú contextual de ese elemento, seleccione Get Item (Obtener elemento) y en la opción Trust>When using this certificate (Confiar > Al usar este certificado), seleccione Always Trust (Confiar siempre).

Opción 2: Deshabilitar la validación SSL en la aplicación

Solo se recomienda deshabilitar la validación SSL con fines de desarrollo, y no debe realizarse cuando se ejecuta en un entorno de producción. En los siguientes ejemplos se muestra cómo deshabilitar la validación SSL para las aplicaciones .NET y Node.js.

Con cualquier aplicación que se ejecute en un marco compatible con .NET Standard 2.1 o posterior, se puede aprovechar CosmosClientOptions.HttpClientFactory:

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);

Con cualquier aplicación que se ejecute en un marco compatible con .NET Standard 2.0, se puede aprovechar CosmosClientOptions.HttpClientFactory:

CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
{
    HttpClientFactory = () =>
    {
        HttpMessageHandler httpMessageHandler = new HttpClientHandler()
        {
            ServerCertificateCustomValidationCallback = (req, cert, chain, errors) => true
        };

        return new HttpClient(httpMessageHandler);
    },
    ConnectionMode = ConnectionMode.Gateway
};


CosmosClient client = new CosmosClient(endpoint, authKey, cosmosClientOptions);

En el caso de las aplicaciones de Node.js, puede modificar el archivo package.json para establecer NODE_TLS_REJECT_UNAUTHORIZED al iniciar la aplicación:

"start": NODE_TLS_REJECT_UNAUTHORIZED=0 node app.js

Habilitación del acceso al emulador en una red local

Supongamos que tiene varias máquinas con una sola red, configura el emulador en una máquina y desea acceder a él desde otro máquina. En tal caso, debe habilitar el acceso al emulador en una red local.

Puede ejecutar el emulador en una red local. Para habilitar el acceso de red, especifique la opción /AllowNetworkAccess en la línea de comandos, que también requiere que especifique /Key=key_string o /KeyFile=file_name. Puede usar /GenKeyFile=file_name para generar un archivo con una clave aleatoria por adelantado. Después, puede pasarlo a /KeyFile=file_name o /Key=contents_of_file.

La primera vez que se habilita el acceso de red, el usuario debe apagar el emulador y eliminar su directorio de datos %LOCALAPPDATA%\CosmosDBEmulator.

Autenticación de conexiones cuando se usa el emulador

Al igual que con Azure Cosmos DB en la nube, todas las solicitudes que se realicen en el Emulador de Azure Cosmos DB deben autenticarse. El emulador de Azure Cosmos DB solo admite la comunicación segura a través de TLS. Este emulador admite una sola cuenta fija y una clave de autenticación reconocida para la autenticación de clave principal. Esta cuenta y clave son las únicas credenciales que se admiten para su uso con el Emulador de Azure Cosmos DB. Son las siguientes:

Account name: localhost:<port>
Account key: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==

Nota:

La clave principal admitida por el emulador de Azure Cosmos DB está destinada a su uso exclusivo con el emulador. No puede usar su clave y cuenta de producción de Azure Cosmos DB con el Emulador de Azure Cosmos DB.

Nota:

Si ha iniciado el emulador con la opción /Key, use la clave generada en lugar de la clave predeterminada C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==. Para más información sobre la opción /Key, consulte la referencia de la herramienta de la línea de comandos.

Conexión a diferentes API con el emulador

API para NoSQL

Cuando tenga el emulador de Azure Cosmos DB funcionando en su escritorio, puede usar cualquier SDK de Azure Cosmos DB admitido o la API REST de Azure Cosmos DB para interactuar con el emulador. El emulador de Azure Cosmos DB también incluye un explorador de datos integrado que permite crear contenedores para API para NoSQL o MongoDB. Mediante el explorador de datos, puede ver y editar elementos sin escribir ningún código.

// Connect to the Azure Cosmos DB Emulator running locally
CosmosClient client = new CosmosClient(
   "https://localhost:8081", 
    "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==");

API para MongoDB

Cuando tenga el emulador de Azure Cosmos DB funcionando en su escritorio, podrá usar la API de Azure Cosmos DB para MongoDB para interactuar con el emulador. Inicie el emulador desde el símbolo del sistema como administrador con "/EnableMongoDbEndpoint". Luego, use la siguiente cadena de conexión para conectarse a la API para la cuenta de MongoDB:

mongodb://localhost:C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==@localhost:10255/admin?ssl=true

API para Table

Cuando tenga el emulador de Azure Cosmos DB funcionando en su escritorio, podrá usar el SDK de API para Table de Azure Cosmos DB para interactuar con el emulador. Inicie el emulador desde el símbolo del sistema como administrador con "/EnableTableEndpoint". A continuación, ejecute el siguiente código para conectarse a la cuenta de la API para Table:

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 para Cassandra

Inicie el emulador desde un símbolo del sistema como administrador con "/EnableCassandraEndpoint". Como alternativa, también puede establecer la variable de entorno AZURE_COSMOS_EMULATOR_CASSANDRA_ENDPOINT=true.

Instale Python 2.7
Instale la CLI/CQLSH de Cassandra

Ejecute los siguientes comandos en una ventana normal del símbolo del sistema:

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

En el shell de CQLSH, ejecute los siguientes comandos para conectarse al punto de conexión 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 para Gremlin

Inicie el emulador desde un símbolo del sistema como administrador con "/EnableGremlinEndpoint". Como alternativa, también puede establecer la variable de entorno AZURE_COSMOS_EMULATOR_GREMLIN_ENDPOINT=true

Install apache-tinkerpop-gremlin-console-3.6.0.
En el explorador de datos del emulador, cree una base de datos "db1" y una colección "coll1"; como clave de partición, elija "/name".

Ejecute los siguientes comandos en una ventana normal del símbolo del sistema:

cd /d C:\sdk\apache-tinkerpop-gremlin-console-3.6.0-bin\apache-tinkerpop-gremlin-console-3.6.0

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

En el shell de Gremlin, ejecute los siguientes comandos para conectarse al punto de conexión 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()

Desinstalación del emulador local

Utilice los pasos siguientes para desinstalar el emulador:

Cierre todas las instancias abiertas del emulador local; para ello, haga clic con el botón derecho en el icono del emulador de Azure Cosmos DB en la bandeja del sistema y seleccione Salir. Todas las instancias pueden tardar un minuto en salir.
En el cuadro de búsqueda de Windows, escriba Aplicaciones & características y seleccione Aplicaciones & características (configuración del sistema).
En la lista de aplicaciones, desplácese a Azure Cosmos DB Emulator (Emulador de Azure Cosmos DB), selecciónela, haga clic en Desinstalar, confirme y seleccione Desinstalar de nuevo.

Pasos siguientes

En este artículo, ha aprendido a usar el emulador local para el desarrollo gratuito de aplicaciones en un entorno local. Ahora puede avanzar a los siguientes artículos:

Instalación y uso del emulador de Azure Cosmos DB para desarrollo y pruebas locales

Descarga del emulador

¿Cómo funciona el emulador?

Diferencias entre el emulador y el servicio en la nube

Instalación del emulador

Búsqueda de actualizaciones del emulador

Uso del emulador en Windows

Uso del emulador en Linux o macOS

Opción 1: Importar el certificado TLS/SSL del emulador

Entorno de Linux

Entorno de macOS

Opción 2: Deshabilitar la validación SSL en la aplicación

Habilitación del acceso al emulador en una red local

Autenticación de conexiones cuando se usa el emulador

Conexión a diferentes API con el emulador

API para NoSQL

API para MongoDB

API para Table

API para Cassandra

API para Gremlin

Desinstalación del emulador local

Pasos siguientes

Recursos adicionales

Recursos adicionales