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

[アーティクル]
11/20/2024

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

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

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

データのリセット

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

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

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

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

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

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

接続に関する問題を診断する

接続の問題が発生した場合は、トレースファイルをファイルを圧縮してから、Azure ポータルでサポートチケットを開。
"サービスを利用できません" というメッセージが表示された場合、エミュレーターがネットワークスタックを初期化していない可能性があります。ネットワークフィルタードライバーによって問題が発生している可能性があるため、 Pulse Secure Client または Juniper Networks Client がインストールされているかどうかを確認します。他のネットワークフィルタードライバーをアンインストールして問題を解決することもできます。または、 /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 の Site Bindings を見つけて編集し、TLS 1.3 を無効にします。 Settings オプションを使用して、Web ブラウザーの設定を更新することもできます。
  
  Note
  
  エミュレーターの実行中にコンピューターがスリープモードになったり、OS の更新プログラムが実行されたりすると、"サービスは現在使用できません" というエラーメッセージが表示されることがあります。
3. エミュレーターデータをリセットするには、Windows 通知トレイに表示されるアイコンを右クリックし、 Reset Data を選択します。

トレースファイルの収集

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

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

プロセスが完了するまでに 1 分かかる場合があります。 Azure Cosmos DB エミュレーターのユーザーインターフェイスで Exit を選択することもできます。
次のコマンドを実行してログ記録を開始します。
```
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 ポータルでサポートチケットを開き問題を再現するために必要な手順と共に .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
```
Note

Windows では、ホームドライブがC:であると仮定すると、通常、ホームフォルダーはC:\Users\[username]\されます。
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 デモアプリケーション (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 検証は無効になります。既定では、Azure Cosmos DB for NoSQL 向けの Python SDK では、ローカルエミュレーターに接続するときに TLS/SSL 証明書を使用しようとしません。詳細については、Python 用の Azure Cosmos DB for NoSQL クライアントライブラリに関する記事を参照してください。

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 エミュレーターのコンテキストメニューから Reset Data を選択します。

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

次の方法で共有

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

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

データのリセット

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

接続に関する問題を診断する

トレースファイルの収集

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

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

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

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

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

証明書のローテーション

フィードバック

その他のリソース

次の方法で共有

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

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

データのリセット

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

接続に関する問題を診断する

トレース ファイルの収集

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

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

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

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

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

証明書のローテーション

フィードバック

その他のリソース

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

トレースファイルの収集

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