Partager via

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

  • Article

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 lorsque vous installez ou utilisez l’émulateur.

Liste de 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établir des données

Si vous avez installé une nouvelle version de l’émulateur et que vous rencontrez des erreurs, veillez à réinitialiser 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 résout pas les erreurs, vous pouvez :

  • Désinstallez l’émulateur.
  • Désinstallez les versions antérieures de l’émulateur (si elles existent).
  • 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 cesse de répondre, cet incident peut indiquer que les compteurs de performances sont endommagés. Pour case activée le compteur status, exécutez la commande suivante :

    lodctr /R

Diagnostiquer les problèmes de connectivité

  • Si vous rencontrez un problème de connectivité, collectez les 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 n’initialise peut-être pas 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 être à l’origine du 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. Un message d’erreur similaire, tel que « Microsoft.Azure.Documents.DocumentClientException : Request is being made with a forbidden encryption in transit protocol or cipher. Vérifier le paramètre de protocole minimum autorisé SSL/TLS du compte » peut être généré si vous utilisez le Kit de développement logiciel (SDK) pour exécuter une requête 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 solution par défaut.

    Par exemple :

    1. Dans le Gestionnaire iis, accédez à Sites>Web Sites 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 .

      Remarque

      Si votre ordinateur passe 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 « Le service est actuellement indisponible » peut s’afficher.

    3. Pour réinitialiser les données de l’émulateur, cliquez avec le bouton droit sur l’icône qui s’affiche 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 :

  1. Accédez au chemin d’accès dans lequel l’émulateur est installé :

    cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"

  2. Arrêtez l’émulateur et watch la barre d’état système pour vous assurer que le programme est arrêté :

    Microsoft.Azure.Cosmos.Emulator.exe /shutdown

    Remarque

    Le processus peut prendre une minute. Vous pouvez également sélectionner Quitter dans l’interface utilisateur de l’émulateur Azure Cosmos DB.

  3. Démarrez la journalisation en exécutant la commande suivante :

    Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces

  4. Démarrez l’émulateur :

    Microsoft.Azure.Cosmos.Emulator.exe

  5. Reproduisez le problème. Si l’Explorateur de données ne fonctionne pas, vous devez attendre seulement quelques secondes que le navigateur se charge pour pouvoir détecter l’erreur.

  6. Arrêter la journalisation :

    Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces

  7. Accédez au %ProgramFiles%\Azure Cosmos DB Emulator chemin d’accès et recherchez le fichier docdbemulator_000001.etl .

  8. Ouvrez un ticket de support dans le Portail Azure et incluez le fichier .etl avec toutes les étapes nécessaires 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 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 magasin de certificats Windows. 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.

  1. 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'}

  2. Utilisez Export-Certificate pour exporter le certificat vers un fichier temporaire dans votre dossier de base.

    $params = @{
    Cert = $cert
    Type = "CERT"
    FilePath = "$home/tmp-cert.cer"
    NoClobber = $true
}
Export-Certificate @params

    Remarque

    Dans Windows, le dossier de base est généralement C:\Users\[username]\, en supposant que votre lecteur de base est C:.

  3. 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

  4. 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, il est plus facile d’installer le certificat dans le magasin de certificats Java par défaut que de transmettre les -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 fournies dans 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 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, si plusieurs versions de Java sont installées, 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 n’essaie pas d’utiliser le certificat TLS/SSL lorsqu’il se connecte à l’émulateur local. Pour plus d’informations, consultez 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 socket.

Importer un certificat pour les applications Node.js

Lorsque vous vous connectez à l’émulateur à partir de Node.js kits SDK, la vérification TLS est désactivée. Par défaut, le sdkNode.js (version 1.10.1 ou ultérieure) pour 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 documentationNode.js.

Faire pivoter les 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 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.