Solución de problemas del emulador de Azure Cosmos DB

Artículo
04/13/2024

El emulador de Azure Cosmos DB proporciona un entorno que emula el servicio en la nube para el desarrollo. Use las sugerencias de este artículo para ayudar a solucionar problemas que puede experimentar al instalar o usar el emulador.

Lista de comprobación de solución de problemas

Esta es una lista de los pasos comunes de solución de problemas que se deben seguir si el emulador de Azure Cosmos DB no funciona según lo previsto.

Restablecer datos

Si instaló una nueva versión del emulador y experimenta errores, asegúrese de restablecer los datos. Para restablecer los datos, abra el menú contextual del emulador de Azure Cosmos DB desde la bandeja del sistema y seleccione Restablecer datos.

Si restablecer los datos no corrige los errores, puede hacer lo siguiente:

Desinstale el emulador.
Desinstale las versiones anteriores del emulador (si existen).
Quite la %ProgramFiles%\Azure Cosmos DB Emulator carpeta .
Vuelva a instalar el emulador.

Como alternativa, si restablecer los datos no funciona, vaya a la %LOCALAPPDATA%\CosmosDBEmulator ubicación y elimine la carpeta.

Revisar los contadores de rendimiento de Windows dañados

Si el emulador de Azure Cosmos DB deja de responder, recopile los archivos de volcado de la %LOCALAPPDATA%\CrashDumps carpeta, comprima los archivos y abra una incidencia de soporte técnico en Azure Portal.
Si Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe deja de responder, este bloqueo podría indicar que los contadores de rendimiento están dañados. Para comprobar el estado del contador, ejecute el siguiente comando:
```
lodctr /R
```

Diagnóstico de problemas de conectividad

Si experimenta un problema de conectividad, recopile archivos de seguimiento, comprima los archivos y abra una incidencia de soporte técnico en Azure Portal.
Si recibe un mensaje "Servicio no disponible", es posible que el emulador no inicialice la pila de red. Compruebe si tiene instalado Pulse Secure Client o Juniper Networks Client porque sus controladores de filtro de red podrían estar causando el problema. También puede intentar desinstalar otros controladores de filtro de red para corregir el problema. Como alternativa, inicie el emulador mediante /DisableRIO para cambiar la comunicación de red del emulador a Winsock normal.
Si recibe un mensaje de error de conectividad como "Forbidden", "message":"Request is being made with a forbidden encryption in transit protocol or cipher. Check account SSL/TLS minimum allowed protocol setting...", este mensaje de error podría indicar cambios globales en el sistema operativo (por ejemplo, Insider Preview Build 20170) o cambios en la configuración del explorador que habilita TLS 1.3 como protocolo predeterminado. Un mensaje de error similar, como "Microsoft.Azure.Documents.DocumentClientException: La solicitud se realiza con un cifrado prohibido en el protocolo de tránsito o el cifrado. Compruebe la configuración del protocolo SSL/TLS mínimo permitido de la cuenta" si usa el SDK para ejecutar una solicitud en el emulador de Azure Cosmos DB. Este error también puede producirse porque el emulador de Azure Cosmos DB solo admite el protocolo TLS 1.2. La solución alternativa recomendada es establecer TLS 1.2 como valor predeterminado.

Por ejemplo:
1. En el Administrador de IIS, vaya a Sitios>web predeterminados.
2. Busque los enlaces de sitio para el puerto 8081 y edítelos para deshabilitar TLS 1.3. También puede actualizar la configuración del explorador web mediante la opción Configuración .
  
  Nota:
  
  Si el equipo entra en modo de suspensión o ejecuta cualquier actualización del sistema operativo mientras se ejecuta el emulador, es posible que vea un mensaje de error "El servicio no está disponible actualmente".
3. Para restablecer los datos del emulador, haga clic con el botón derecho en el icono que aparece en la bandeja de notificaciones de Windows y seleccione Restablecer datos.

Recopilación de archivos de seguimiento

Para recopilar seguimientos de depuración, ejecute los siguientes comandos como administrador en una ventana del símbolo del sistema:

Vaya a la ruta de acceso en la que está instalado el emulador:
```
cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"
```
Apague el emulador y observe la bandeja del sistema para asegurarse de que el programa está apagado:
```
Microsoft.Azure.Cosmos.Emulator.exe /shutdown
```
Nota:

El proceso puede tardar un minuto en finalizar. También puede seleccionar Salir en la interfaz de usuario del emulador de Azure Cosmos DB.
Para iniciar el registro, ejecute el comando siguiente:
```
Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces
```
Inicie el emulador:
```
Microsoft.Azure.Cosmos.Emulator.exe
```
Reproduce el problema. Si el explorador de datos no funciona, debe esperar solo unos segundos para que el explorador se cargue para poder detectar el error.

Detener el registro:

Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces

Vaya a la %ProgramFiles%\Azure Cosmos DB Emulator ruta de acceso y busque el archivo docdbemulator_000001.etl .
Abra una incidencia de soporte técnico en Azure Portal e incluya el archivo .etl junto con los pasos necesarios para reproducir el problema.

Instalación de certificados para aplicaciones cliente

En ocasiones, es posible que tenga que tomar el certificado del emulador exportado y usarlo con una aplicación cliente. El proceso exacto varía según el SDK.

Exportación del certificado TLS/SLL

Exporte el certificado del emulador para usar correctamente el punto de conexión del emulador desde lenguajes y entornos en tiempo de ejecución que no se integran con el Almacén de certificados de Windows. Puede exportar el certificado mediante el Administrador de certificados de Windows o PowerShell después de ejecutar el emulador por primera vez.

Recupere el certificado con el nombre DocumentDbEmulatorCertificate descriptivo y almacene el certificado en una variable de shell denominada $cert.
```
$cert = Get-ChildItem Cert:\LocalMachine\My | where{$_.FriendlyName -eq 'DocumentDbEmulatorCertificate'}
```
Use Export-Certificate para exportar el certificado a un archivo temporal en la carpeta principal.
```
$params = @{
    Cert = $cert
    Type = "CERT"
    FilePath = "$home/tmp-cert.cer"
    NoClobber = $true
}
Export-Certificate @params
```
Nota:

En Windows, la carpeta principal suele ser C:\Users\[username]\, suponiendo que la unidad principal sea C:.
Use certutil para convertir el certificado en un archivo de certificado X.509 codificado en Base 64.
```
certutil -encode $home/tmp-cert.cer $home/cosmosdbcert.cer
```
Quite el archivo temporal.
```
Remove-Item $home/tmp-cert.cer
```

Importación de certificados para aplicaciones Java

Al ejecutar aplicaciones Java o aplicaciones de MongoDB que usan un cliente basado en Java, instalar el certificado en el almacén de certificados predeterminado de Java es más fácil que pasar los -Djavax.net.ssl.trustStore=<keystore> -Djavax.net.ssl.trustStorePassword="<password>" parámetros. Por ejemplo, la aplicación de demostración de Java (https://localhost:8081/_explorer/index.html) incluida depende del almacén de certificados predeterminado.

Siga las instrucciones de Creación, exportación e importación de certificados TLS/SSL para importar el certificado X.509 en el almacén de certificados de Java predeterminado. Recuerde que está trabajando en el directorio %JAVA_HOME% al ejecutar keytool. Después de importar el certificado en el almacén de certificados, los clientes para la API de SQL y Azure Cosmos DB para MongoDB pueden conectarse al emulador de Azure Cosmos DB.

Como alternativa, puede ejecutar el siguiente bash script para importar el certificado:

#!/bin/bash

# If the emulator was started with /AllowNetworkAccess, replace the following 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
# Delete the cert if it already exists
sudo $JAVA_HOME/bin/keytool -cacerts -delete -alias cosmos_emulator
# Import the cert
sudo $JAVA_HOME/bin/keytool -cacerts -importcert -alias cosmos_emulator -file $EMULATOR_CERT_PATH

Una vez instalado el CosmosDBEmulatorCertificate certificado TLS/SSL, la aplicación debe poder conectarse a y usar el emulador local de Azure Cosmos DB.

Si tiene algún problema, consulte Depuración de conexiones SSL/TLS. En la mayoría de los casos, es posible que el certificado no esté instalado en el almacén %JAVA_HOME%/jre/lib/security/cacerts. Por ejemplo, si hay más de una versión instalada de Java, es posible que la aplicación use un almacén de certificados diferente del que ha actualizado.

Importación de certificados para aplicaciones de Python

Al conectarse al emulador desde aplicaciones de Python, la comprobación de TLS está deshabilitada. De forma predeterminada, el SDK de Python para Azure Cosmos DB for NoSQL no intentará usar el certificado TLS/SSL cuando se conecte al emulador local. Para obtener más información, consulte la biblioteca cliente de Azure Cosmos DB for NoSQL para Python.

Si desea usar la validación de TLS, siga los ejemplos del contenedor TLS/SSL para objetos de socket.

Importación de certificado para aplicaciones de Node.js

Al conectarse al emulador desde los SDK de Node.js, se deshabilitará la verificación de TLS. De forma predeterminada, el SDK de Node.js (versión 1.10.1 o posterior) de la API para NoSQL no intenta usar el certificado TLS/SSL cuando se conecta al emulador local.

Si deseara usar la validación de TLS, siga los ejemplos de la documentación de Node.js.

Rotación de certificados

Puede forzar la regeneración de los certificados del emulador abriendo el emulador con el /ResetDataPath argumento . Esta acción borra todos los datos almacenados localmente por el emulador. Para obtener más información sobre los argumentos de la línea de comandos, vea Argumentos de la línea de comandos del emulador de Windows.

Sugerencia

Como alternativa, seleccione Restablecer datos en el menú contextual del emulador de Azure Cosmos DB en la bandeja del sistema de Windows.

Si instaló los certificados en el almacén de certificados de Java o los usó en otro lugar, debe volver a importarlos mediante los certificados actuales. La aplicación no se puede conectar al emulador local en tanto no se actualicen los certificados.

Compartir a través de