Azure Cosmos DB エミュレーターのトラブルシューティング

[アーティクル]
04/13/2024

Azure Cosmos DB エミュレーターは、開発のためにクラウドサービスをエミュレートする環境を提供します。この記事のヒントを使用して、エミュレーターをインストールまたは使用するときに発生する可能性がある問題のトラブルシューティングに役立ちます。

トラブルシューティングチェックリスト

Azure Cosmos DB エミュレーターが期待どおりに動作しない場合に従う一般的なトラブルシューティング手順の一覧を次に示します。

データをリセットする

エミュレーターの新しいバージョンをインストールし、エラーが発生している場合は、データをリセットしてください。データをリセットするには、システムトレイから Azure Cosmos DB エミュレーターコンテキストメニューを開き、[ データのリセット] を選択します。

データをリセットしてもエラーが解決しない場合は、次のことができます。

エミュレーターをアンインストールします。
以前のバージョンのエミュレーターをアンインストールします (存在する場合)。
フォルダーを %ProgramFiles%\Azure Cosmos DB Emulator 削除します。
エミュレーターを再インストールします。

または、データのリセットが機能しない場合は、場所に %LOCALAPPDATA%\CosmosDBEmulator 移動し、フォルダーを削除します。

破損した Windows パフォーマンスカウンターを確認する

Azure Cosmos DB エミュレーターが応答を停止した場合は、フォルダーからダンプファイルを%LOCALAPPDATA%\CrashDumps収集し、ファイルを圧縮してから、Azure portalでサポートチケットを開きます。
応答が停止した場合 Microsoft.Azure.Cosmos.ComputeServiceStartupEntryPoint.exe 、このクラッシュはパフォーマンスカウンターが破損していることを示している可能性があります。カウンターの状態をチェックするには、次のコマンドを実行します。
```
lodctr /R
```

接続の問題を診断する

接続の問題が発生した場合は、トレースファイルを収集し、ファイルを圧縮してから、Azure portalでサポートチケットを開きます。
"サービス利用不可" メッセージを受け取った場合、エミュレーターがネットワークスタックを初期化していない可能性があります。ネットワークフィルタードライバーが問題を引き起こしている可能性があるため、 Pulse Secure Client または Juniper Networks クライアント がインストールされているかどうかを確認します。他のネットワークフィルタードライバーをアンインストールして問題を解決することもできます。または、を使用 /DisableRIO してエミュレーターを起動し、エミュレーターネットワーク通信を通常の Winsock に切り替えます。
などの "Forbidden", "message":"Request is being made with a forbidden encryption in transit protocol or cipher. Check account SSL/TLS minimum allowed protocol setting..."接続エラーメッセージが表示された場合、このエラーメッセージは、OS のグローバルな変更 (Insider Preview Build 20170 など) や、TLS 1.3 を既定のプロトコルとして有効にするブラウザー設定の変更を示している可能性があります。 "Microsoft.Azure.Documents.DocumentClientException: 転送プロトコルまたは暗号で禁止されている暗号化を使用して要求が行われています。 SDK を使用して Azure Cosmos DB エミュレーターに対して要求を実行すると、アカウント SSL/TLS の最小許可プロトコル設定が生成される可能性があります。このエラーは、Azure Cosmos DB エミュレーターが TLS 1.2 プロトコルのみをサポートしているためにも発生する可能性があります。推奨される回避策は、TLS 1.2 を既定値として設定します。

以下に例を示します。
1. IIS マネージャーで、[サイト>の既定の Web サイト] に移動します。
2. ポート 8081 のサイトバインドを見つけて、TLS 1.3 を無効にするように編集します。 [設定] オプションを使用して、Web ブラウザーの設定を更新することもできます。
  
  注:
  
  エミュレーターの実行中にコンピューターがスリープモードになるか、OS 更新プログラムを実行している場合は、"サービスは現在使用できません" というエラーメッセージが表示されることがあります。
3. エミュレーターデータをリセットするには、Windows 通知トレイに表示されるアイコンを右クリックし、[ データのリセット] を選択します。

トレースファイルを収集する

デバッグトレースを収集するには、コマンドプロンプトウィンドウで管理者として次のコマンドを実行します。

エミュレーターがインストールされているパスに移動します。
```
cd /d "%ProgramFiles%\Azure Cosmos DB Emulator"
```
エミュレーターをシャットダウンし、システムトレイをwatchして、プログラムがシャットダウンされていることを確認します。
```
Microsoft.Azure.Cosmos.Emulator.exe /shutdown
```
注:

プロセスが完了するまでに 1 分かかる場合があります。 Azure Cosmos DB エミュレーターのユーザーインターフェイスで [ 終了 ] を選択することもできます。
次のコマンドを実行してログ記録を開始します。
```
Microsoft.Azure.Cosmos.Emulator.exe /startwprtraces
```
エミュレーターを起動します。
```
Microsoft.Azure.Cosmos.Emulator.exe
```
問題を再現します。データエクスプローラーが動作しない場合は、ブラウザーが読み込まれるまで数秒待ってエラーを検出する必要があります。

ログ記録を停止します。

Microsoft.Azure.Cosmos.Emulator.exe /stopwprtraces

パスに %ProgramFiles%\Azure Cosmos DB Emulator 移動し、 docdbemulator_000001.etl ファイルを見つけます。
Azure portalでサポートチケットを開き、問題を再現するために必要な手順と共に .etl ファイルを含めます。

クライアントアプリケーションの証明書をインストールする

場合によっては、エクスポートされたエミュレーター証明書を取得し、クライアントアプリケーションで使用することが必要になる場合があります。正確なプロセスは SDK によって異なります。

TLS/SLL 証明書をエクスポートする

エミュレーター証明書をエクスポートして、Windows 証明書ストアと統合されていない言語とランタイム環境からエミュレーターエンドポイントを正常に使用します。エミュレーターを初めて実行した後、Windows 証明書マネージャーまたは PowerShell を使用して証明書をエクスポートできます。

フレンドリ名 DocumentDbEmulatorCertificate を使用して証明書を取得し、という名前 $certのシェル変数に証明書を格納します。
```
$cert = Get-ChildItem Cert:\LocalMachine\My | where{$_.FriendlyName -eq 'DocumentDbEmulatorCertificate'}
```
Export-Certificate を使用して、ホームフォルダー内の一時ファイルに証明書をエクスポートします。
```
$params = @{
    Cert = $cert
    Type = "CERT"
    FilePath = "$home/tmp-cert.cer"
    NoClobber = $true
}
Export-Certificate @params
```
注:

Windows では、ホームフォルダーは通常 C:\Users\[username]\、で、ホームドライブが C:であると仮定します。
certutil を使用して、証明書を Base-64 でエンコードされた X.509 証明書ファイルに変換します。
```
certutil -encode $home/tmp-cert.cer $home/cosmosdbcert.cer
```
一時ファイルを削除します。
```
Remove-Item $home/tmp-cert.cer
```

Java アプリケーションの証明書をインポートする

Java ベースのクライアントを使用する Java アプリケーションまたは MongoDB アプリケーションを実行する場合、Java の既定の証明書ストアに証明書をインストールする方が、パラメーターを渡す -Djavax.net.ssl.trustStore=<keystore> -Djavax.net.ssl.trustStorePassword="<password>" よりも簡単です。たとえば、含まれている Java Demo アプリケーション (https://localhost:8081/_explorer/index.html) は、既定の証明書ストアによって異なります。

「TLS/SSL 証明書の作成、エクスポート、インポート」の手順に従って、X.509 証明書を既定の Java 証明書ストアにインポートします。 keytool を実行するときに %JAVA_HOME% ディレクトリで作業していることを忘れないでください。証明書が証明書ストアにインポートされると、SQL 用のクライアントと Azure Cosmos DB の MongoDB 用 API を Azure Cosmos DB エミュレーターに接続できます。

または、次 bash のスクリプトを実行して証明書をインポートすることもできます。

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

CosmosDBEmulatorCertificate TLS/SSL 証明書がインストールされると、アプリケーションはローカルの Azure Cosmos DB エミュレーターに接続して使用できるようになります。

問題がある場合は、「 SSL/TLS 接続のデバッグ」を参照してください。ほとんどの場合、証明書が %JAVA_HOME%/jre/lib/security/cacerts ストアに インストールされていない可能性があります。たとえば、複数のバージョンの Java がインストールされている場合、アプリケーションで更新した証明書ストアとは異なる証明書ストアが使用されている可能性があります。

Python アプリケーションの証明書をインポートする

Python アプリケーションからエミュレーターに接続すると、TLS 検証は無効になります。既定では、Python SDK for Azure Cosmos DB for NoSQL は、ローカルエミュレーターに接続するときに TLS/SSL 証明書の使用を試みません。詳細については、「 Azure Cosmos DB for NoSQL クライアントライブラリ for Python」を参照してください。

TLS 検証を使用する場合は、ソケットオブジェクトの TLS/SSL ラッパーの例に従います。

Node.js アプリケーションの証明書をインポートする

Node.js SDK からエミュレーターに接続すると、TLS 検証は無効になります。既定では、NoSQL 用 API の Node.js SDK (バージョン 1.10.1 以降) は、ローカルエミュレーターに接続するときに TLS/SSL 証明書を使用しません。

TLS 検証を使用する場合は、 Node.js ドキュメントの例に従ってください。

証明書をローテーションする

エミュレーター証明書を強制的に再生成する場合は、引数を指定してエミュレーターを /ResetDataPath 開きます。このアクションにより、エミュレーターによってローカルに格納されているすべてのデータがワイプされます。コマンドライン引数の詳細については、「 Windows エミュレーターのコマンドライン引数」を参照してください。

ヒント

または、Windows システムトレイの Azure Cosmos DB エミュレーターのコンテキストメニューから [ データのリセット ] を選択します。

証明書を Java 証明書ストアにインストールした場合、または他の場所で使用した場合は、現在の証明書を使用して再インポートする必要があります。証明書を更新するまで、アプリケーションはローカルエミュレーターに接続できません。

次の方法で共有

Azure Cosmos DB エミュレーターのトラブルシューティング

トラブルシューティングチェックリスト

データをリセットする

破損した Windows パフォーマンスカウンターを確認する

接続の問題を診断する

トレースファイルを収集する

クライアントアプリケーションの証明書をインストールする

TLS/SLL 証明書をエクスポートする

Java アプリケーションの証明書をインポートする

Python アプリケーションの証明書をインポートする

Node.js アプリケーションの証明書をインポートする

証明書をローテーションする

フィードバック

その他のリソース

次の方法で共有

Azure Cosmos DB エミュレーターのトラブルシューティング

トラブルシューティング チェックリスト

データをリセットする

破損した Windows パフォーマンス カウンターを確認する

接続の問題を診断する

トレース ファイルを収集する

クライアント アプリケーションの証明書をインストールする

TLS/SLL 証明書をエクスポートする

Java アプリケーションの証明書をインポートする

Python アプリケーションの証明書をインポートする

Node.js アプリケーションの証明書をインポートする

証明書をローテーションする

フィードバック

その他のリソース

トラブルシューティングチェックリスト

破損した Windows パフォーマンスカウンターを確認する

トレースファイルを収集する

クライアントアプリケーションの証明書をインストールする