Résoudre les problèmes liés à l’émulateur Azure Cosmos DB

Article
11/20/2024

L’émulateur Azure Cosmos DB fournit un environnement qui émule le service cloud pour le développement. Utilisez les conseils de cet article pour résoudre les problèmes que vous pouvez rencontrer lors de l’installation ou de l’utilisation de l’émulateur.

Liste de contrôle pour la résolution des problèmes

Voici une liste des étapes de dépannage courantes à suivre si l’émulateur Azure Cosmos DB ne fonctionne pas comme prévu.

Réinitialiser les données

Si vous avez installé une nouvelle version de l’émulateur et que vous rencontrez des erreurs, vérifiez que vous réinitialisez les données. Pour réinitialiser les données, ouvrez le menu contextuel de l’émulateur Azure Cosmos DB dans la barre d’état système, puis sélectionnez Réinitialiser les données.

Si la réinitialisation des données ne corrige pas les erreurs, vous pouvez :

Désinstallez l’émulateur.
Désinstallez les versions antérieures de l’émulateur (le cas échéant).
Supprimez le %ProgramFiles%\Azure Cosmos DB Emulator dossier.
Réinstallez l’émulateur.

Sinon, si la réinitialisation des données ne fonctionne pas, accédez à l’emplacement %LOCALAPPDATA%\CosmosDBEmulator , puis supprimez le dossier.

Passer en revue les compteurs de performances Windows endommagés

Si l’émulateur Azure Cosmos DB cesse de répondre, collectez les fichiers de vidage à partir du %LOCALAPPDATA%\CrashDumps dossier, compressez les fichiers, puis ouvrez un ticket de support dans le Portail Azure.
Si Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe elle cesse de répondre, ce blocage peut indiquer que les compteurs de performances sont endommagés. Pour vérifier l’état du compteur, exécutez la commande suivante :
```
lodctr /R
```

Diagnostiquer les problèmes de connectivité

Si vous rencontrez un problème de connectivité, collectez des fichiers de trace, compressez les fichiers, puis ouvrez un ticket de support dans le Portail Azure.
Si vous recevez un message « Service indisponible », l’émulateur risque de ne pas initialiser la pile réseau. Vérifiez si le client Pulse Secure ou le client Juniper Networks est installé, car leurs pilotes de filtre réseau peuvent entraîner le problème. Vous pouvez également essayer de désinstaller d’autres pilotes de filtre réseau pour résoudre le problème. Vous pouvez également démarrer l’émulateur en utilisant /DisableRIO pour basculer la communication réseau de l’émulateur vers Winsock standard.
Si vous recevez un message d’erreur de connectivité tel que "Forbidden", "message":"Request is being made with a forbidden encryption in transit protocol or cipher. Check account SSL/TLS minimum allowed protocol setting...", ce message d’erreur peut indiquer des modifications globales dans le système d’exploitation (par exemple, Insider Preview Build 20170) ou des modifications dans les paramètres du navigateur qui activent TLS 1.3 comme protocole par défaut. Message d’erreur similaire, tel que « Microsoft.Azure.Documents.DocumentClientException : La requête est effectuée avec un chiffrement interdit dans le protocole de transit ou le chiffrement. Vérifiez le paramètre de protocole SSL/TLS minimal autorisé du compte » peut être généré si vous utilisez le Kit de développement logiciel (SDK) pour exécuter une demande sur l’émulateur Azure Cosmos DB. Cette erreur peut également se produire, car l’émulateur Azure Cosmos DB prend uniquement en charge le protocole TLS 1.2. La solution de contournement recommandée consiste à définir TLS 1.2 comme valeur par défaut.

Par exemple :
1. Dans le Gestionnaire des services Internet, accédez aux sites> web par défaut.
2. Recherchez les liaisons de site pour le port 8081 et modifiez-les pour désactiver TLS 1.3. Vous pouvez également mettre à jour les paramètres du navigateur web à l’aide de l’option Paramètres .
  
  Note
  
  Si votre ordinateur entre en mode veille ou exécute des mises à jour du système d’exploitation pendant l’exécution de l’émulateur, un message d’erreur « Service n’est pas disponible » peut s’afficher.
3. Pour réinitialiser les données de l’émulateur, cliquez avec le bouton droit sur l’icône qui apparaît dans la barre d’état des notifications Windows, puis sélectionnez Réinitialiser les données.

Collecter les fichiers de trace

Pour collecter les traces de débogage, exécutez les commandes suivantes en tant qu’administrateur dans une fenêtre d’invite de commandes :

Accédez au chemin d’accès dans lequel l’émulateur est installé :
```
cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"
```
Arrêtez l’émulateur et regardez la barre d’état système pour vous assurer que le programme est arrêté :
```
Microsoft.Azure.Cosmos.Emulator.exe /shutdown
```
Note

La fin du processus peut prendre une minute. Vous pouvez également sélectionner Quitter dans l’interface utilisateur de l’émulateur Azure Cosmos DB.
Démarrez la journalisation en exécutant la commande suivante :
```
Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces
```
Démarrez l’émulateur :
```
Microsoft.Azure.Cosmos.Emulator.exe
```
Reproduisez le problème. Si l’Explorateur de données ne fonctionne pas, vous devez attendre seulement quelques secondes pour que le navigateur puisse charger pour pouvoir détecter l’erreur.

Arrêtez la journalisation :

Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces

Accédez au %ProgramFiles%\Azure Cosmos DB Emulator chemin d’accès et recherchez le fichier docdbemulator_000001.etl .
Ouvrez un ticket de support dans le Portail Azure et incluez le fichier .etl avec toutes les étapes requises pour reproduire le problème.

Installer des certificats pour les applications clientes

Parfois, vous devrez peut-être prendre le certificat d’émulateur exporté et l’utiliser avec une application cliente. Le processus exact varie selon le Kit de développement logiciel (SDK).

Exporter un certificat TLS/SLL

Exportez le certificat de l’émulateur pour utiliser correctement le point de terminaison de l’émulateur à partir de langages et d’environnements d’exécution qui ne s’intègrent pas au Windows Certificate Store. Vous pouvez exporter le certificat à l’aide du Gestionnaire de certificats Windows ou de PowerShell après avoir exécuté l’émulateur pour la première fois.

Récupérez le certificat à l’aide du nom DocumentDbEmulatorCertificate convivial et stockez le certificat dans une variable d’interpréteur de commandes nommée $cert.
```
$cert = Get-ChildItem Cert:\LocalMachine\My | where{$_.FriendlyName -eq 'DocumentDbEmulatorCertificate'}
```
Utilisez Export-Certificate pour exporter le certificat vers un fichier temporaire dans votre dossier d’accueil.
```
$params = @{
    Cert = $cert
    Type = "CERT"
    FilePath = "$home/tmp-cert.cer"
    NoClobber = $true
}
Export-Certificate @params
```
Note

Dans Windows, le dossier d’accueil est généralement C:\Users\[username]\, en supposant que votre lecteur de base est C:.
Utilisez certutil pour convertir le certificat en fichier de certificat X.509 codé en base 64.
```
certutil -encode $home/tmp-cert.cer $home/cosmosdbcert.cer
```
Supprimez le fichier temporaire.
```
Remove-Item $home/tmp-cert.cer
```

Importer un certificat pour les applications Java

Lorsque vous exécutez des applications Java ou des applications MongoDB qui utilisent un client Java, l’installation du certificat dans le magasin de certificats par défaut Java est plus facile que la transmission des -Djavax.net.ssl.trustStore=<keystore> -Djavax.net.ssl.trustStorePassword="<password>" paramètres. Par exemple, l’application de démonstration Java incluse (https://localhost:8081/_explorer/index.html) dépend du magasin de certificats par défaut.

Suivez les instructions de création, exportation et importation de certificats TLS/SSL pour importer le certificat X.509 dans le magasin de certificats Java par défaut. N’oubliez pas que vous travaillez dans le répertoire %JAVA_HOME% lors de l’exécution de keytool. Une fois le certificat importé dans le magasin de certificats, les clients pour l’API SQL et l’API Azure Cosmos DB pour MongoDB peuvent se connecter à l’émulateur Azure Cosmos DB.

Vous pouvez également exécuter le script suivant bash pour importer le certificat :

#!/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

Une fois le CosmosDBEmulatorCertificate certificat TLS/SSL installé, votre application doit être en mesure de se connecter à l’émulateur Azure Cosmos DB local et de l’utiliser.

Si vous rencontrez des problèmes, consultez Débogage des connexions SSL/TLS. Dans la plupart des cas, le certificat n’est peut-être pas installé dans le magasin %JAVA_HOME%/jre/lib/security/cacerts. Par exemple, s’il existe plusieurs versions installées de Java, votre application peut utiliser un magasin de certificats différent de celui que vous avez mis à jour.

Importer un certificat pour les applications Python

Lorsque vous vous connectez à l’émulateur à partir d’applications Python, la vérification TLS est désactivée. Par défaut, le kit de développement logiciel (SDK) Python pour Azure Cosmos DB for NoSQL ne tente pas d’utiliser le certificat TLS/SSL lorsqu’il se connecte à l’émulateur local. Pour plus d’informations, consultez Démarrage rapide : bibliothèque de client Azure Cosmos DB for NoSQL pour Python.

Si vous souhaitez utiliser la validation TLS, suivez les exemples du wrapper TLS/SSL pour les objets de socket.

Importer un certificat pour les applications Node.js

Lorsque vous vous connectez à l’émulateur depuis des kits de développement logiciel (SDK) Node.js, la vérification TLS est désactivée. Par défaut, le sdk Node.js (version 1.10.1 ou ultérieure) de l’API pour NoSQL n’essaie pas d’utiliser le certificat TLS/SSL lorsqu’il se connecte à l’émulateur local.

Si vous souhaitez utiliser la validation TLS, suivez les exemples de la documentation Node.js.

Effectuer une rotation des certificats

Vous pouvez forcer la régénération des certificats de l’émulateur en ouvrant l’émulateur avec l’argument /ResetDataPath . Cette action efface toutes les données stockées localement par l’émulateur. Pour plus d’informations sur les arguments de ligne de commande, consultez les arguments de ligne de commande de l’émulateur Windows.

Conseil

Vous pouvez également sélectionner Réinitialiser les données dans le menu contextuel de l’émulateur Azure Cosmos DB dans la barre d’état système Windows.

Si vous avez installé les certificats dans le magasin de certificats Java ou les avez utilisés ailleurs, vous devez les réimporter à l’aide des certificats actuels. Votre application ne peut pas se connecter à l’émulateur local tant que vous n’avez pas mis à jour les certificats.

Partager via