Azure Cosmos DB シェルのトラブルシューティング ガイド

読み取り専用診断から始めて、資格情報、アカウントのアクセス許可、ネットワーク規則、またはソフトウェアのインストールを変更する前に、失敗したレイヤーを特定します。

診断から始める

シェル内で、次のコマンドを実行します。

version
doctor --no-update-check --format=json
whoami

doctor は、接続、ナビゲーション、または設定を変更せずに有界チェックを実行し、切断中に機能します。 成功、警告、失敗、またはスキップされた各結果を確認します。 スキップされたプローブでは、アカウントが正常であることや、アクセスが許可されていることを示すものではありません。

選択したコンテナーを明示的にテストするには、リソース名を置き換えます。

doctor --database=MyDatabase --container=MyContainer --query --no-update-check
can-i query --database=MyDatabase --container=MyContainer

これらのクエリ プローブは RU を使用します。 doctor --armは、Azure Resource Manager チェックを明示的に要求します。 既定の更新チェックでは、制限付きのパブリック GitHub リリース参照が実行されます。--no-update-checkは、その参照を無効にします。 診断は、プローブに対して対話型認証を開始しません。

既知の資格情報と選択したスコープの情報を確認するには、doctor who を使用します。 whoami には、割り当てられた RBAC ロールではなく、使用可能な ID 情報が記述されています。

インストールに関する問題

オペレーティング システムターミナルで cosmosdbshellが見つからない場合:

  1. 拡張機能マネージド シェル、.NET グローバル ツール、またはダウンロードしたバイナリをインストールしたかどうかを確認します。 拡張機能で管理されるシェルは、必ずしもターミナル PATH上にあるとは限りません。

  2. グローバル ツールの場合は、次を実行します:

    dotnet --list-sdks
    dotnet tool list --global
    

    グローバル ツールのインストールには、.NET SDK 10.0 以降が必要です。 ツールの一覧に CosmosDBShell が表示されているかどうかを確認します。

  3. ツール ディレクトリが PATH に含まれていることを確認します: Windows では $HOME/.dotnet/tools、macOS と Linux では %USERPROFILE%\.dotnet\tools。 永続的な PATH の変更後に新しいターミナルを開きます。

  4. バイナリ インストールの場合は、完全な実行可能パスを使用し、ダウンロードしたアーカイブがオペレーティング システムと CPU アーキテクチャと一致することを確認します。 自己完結パッケージにはランタイムが含まれます。_fdd_ パッケージでは、ランタイムが個別に必要です。

  5. 拡張機能で管理されたインストールの場合は、Azure Cosmos DB Shell の起動を実行し、インストールまたは修復のプロンプトに従います。

アーカイブが不完全な場合は、その特定のアーカイブを 公式リリースから再度ダウンロードします。 インストール エラーを診断するために、関連のない拡張フォルダーを削除したり、資格情報ストアをクリアしたりしないでください。

インストールおよび更新コマンドについては、「Azure Cosmos DB シェルのインストール」を参照してください。

認証とアクセス許可

サインインに失敗するか、誤った ID でサインインされる

whoamiと資格情報関連のdoctor結果を確認します。 既定の資格情報チェーンでは、想定とは異なる ID が選択されることがあります。

明示的な対話型テナント認証には、シェル内で接続します。

connect https://<account-name>.documents.azure.com/ --tenant=<tenant-id>

アカウント名とテナント ID を置き換え、ブラウザーでのサインインを完了します。 次に、アカウント ルートで info --format=json を確認して、目的の accountId と uriを確認します。

マネージド ID の場合は、シェルがサポートされているAzure環境で実行されていること、および目的の ID が有効および承認されていることを確認します。 --managed-identity=<client-id> をユーザー割り当て ID に使用します。

キー、アクセス トークン、接続文字列をサポート チケットやチャットに貼り付けないでください。 再接続によって共有 MCP 状態が変更され、保留中の確認が無効になるため、他のクライアントと連携してください。

認可が失敗する

認証と承認を分離します。 サインインが成功しても、データ アクセスは許可されません。

  • データ プレーン アクセスを調査するには、 can-i read またはスコープ付き can-i query を使用します。
  • データ操作用のAzure Cosmos DBネイティブ データ プレーン ロールを確認します。 管理プレーン アカウントの閲覧者の割り当てだけでは、ドキュメントのクエリ権限は付与されません。
  • Azure Resource Manager操作の個別の管理プレーンのアクセス許可を確認します。
  • 割り当てられたプリンシパル、スコープ、テナント、および目的のアカウントが一致することを確認します。

can-i write は削除アクセスに基づくヒューリスティックであり、すべての書き込み操作の認定ではありません。 can-i manage は常に indeterminate です。コマンドは管理アクセスを安全に証明しません。

トークンの有効期限が切れる

資格情報の種類とサニタイズされた診断結果を確認します。 トークンベースの資格情報は更新できますが、シェルで静的トークンを更新することはできません。 コンピューターの時刻同期を確認し、必要に応じて適切な認証フローを介して再接続します。 最初の手順として資格情報ストアを削除しないでください。

ネットワークとエンドポイントの問題

DNS、TLS、または接続エラーの場合:

  1. Azure ポータルで、構成されているエンドポイントとアカウント エンドポイントを比較します。
  2. doctor を実行し、DNS、TLS、認証、またはアクセスのどこで失敗したかを特定してください。
  3. マシンに必要な VPN またはプライベート ネットワーク接続があることを確認します。
  4. アカウントのファイアウォール規則とプライベート エンドポイント DNS をネットワーク管理者と確認します。
  5. TLS 検証を無効にしたり、回避策としてパブリック アクセスを開いたりせずに、該当する場合はプロキシ設定を確認します。

シェルは、アカウント ネットワークの制限をバイパスしません。 ping エラーだけでは、HTTPS データ エンドポイントが使用できないとは判断できません。 プライベート エンドポイントの場合は、一般的な修復としてパブリック DNS リゾルバーに切り替えないでください。

ローカル エミュレーターの場合は、文書化されている localhost エンドポイントとエミュレーターのセットアップを使用します。 テキスト localhost を含む任意のホスト名は、ローカル エミュレーターとして扱われません。

コマンドとクエリの問題

コマンドまたはオプションが認識されない

同じシェル インスタンスで version、 help、および help <command> を実行します。 インストールされているバージョンと リリース ノートを比較します。

現在のコマンドには、ポイント読み取りの print 、ドキュメントの置換のための replace 、フィールドの変更の patch が含まれます。 コンテナーの作成には、mkcon Items /tenantId などの位置指定パーティション キー パスが使用されます。でっち上げの -pk 作成フラグは使用されません。

クエリ結果バインドには、--max-itemsを使用し、query --maxは使用しません。 継続トークンは、対話型クエリ フラグではなく、MCP 構造化引数です。

クエリが失敗するか、項目が返されない

アカウントと明示的なリソース名を確認し、フィールド名を選択する前に実際のスキーマをサンプリングします。

schema --database=MyDatabase --container=MyContainer --sample=20
query "SELECT TOP 1 c.id FROM c" --database=MyDatabase --container=MyContainer --max=1

クエリ言語は、MongoDB 構文や無制限のリレーショナル SQL ではなく、Azure Cosmos DBのNoSQL方言です。 プロパティの大文字と小文字の区別、値の型、引用符、サポートされている関数を確認します。

既知の正確な項目については、ID と完全なパーティション キーの両方で print を使用します。 数値キー、数値検索文字列キー、null、未定義は異なる値です。 print では、クエリに暗黙的にフォールバックすることはありません。

クエリが遅い、または RU を消費しすぎる

出力を制限し、必要なフィールドのみを投影し、検証済みプロパティでフィルター処理します。 --max 返されたアイテムの境界。すべてのクエリの合計作業時間やコストではありません。

query --explainを使用して、最初のページの実行と観察されたインデックス メトリックを検査します。 RU を消費し、完全な実行プランまたは完全なクエリ パフォーマンス測定ではありません。 メトリックが見つからない場合、エンジンがスキャンを実行したことを証明することはできません。

アカウントのスループットとスロットリング、およびネットワーク接続を確認します。 クライアントのコンカレンシーを増やしても、プロビジョニングされたスループットは増加しません。 これらの問題を修復するためのシェル固有の cosmosDB.queryTimeout 拡張機能の設定はありません。

インポート、一括処理、および書き込みの失敗

importとbulkはジョブ全体でトランザクションではありません。 以前の正常な書き込みはコミットされたままであり、インフライト書き込みはエラーの後に完了する可能性があります。

  • 再試行する前に、構造化された結果、カウント、代表的なエラー、および発生した料金を調べます。
  • import --dry-runを使用して、オフラインで入力を検証します。 成功しても、ターゲットがキー、アクセス許可、ID、またはサービスの制約を受け入れることは証明されません。
  • 繰り返される ID をファイル順に処理する必要があるインポートには、 --concurrency=1 を使用します。
  • 一括ジャーナルを使用して、成功、失敗、および不確実な操作を区別します。 再生が効果を複製できるかどうかを評価するまで、 --retry-uncertain を使用しないでください。
  • ETag が一致しない場合は、停止し、変更された項目を検査します。 条件を削除したり、ETag を自動的に更新したりしないでください。
  • batchの場合は、すべての操作が同じ完全なパーティション キーに属していること、およびバッチがサポートされている操作とサービスの制限に適合していることを確認します。

コマンド構文とトランザクション セマンティクスについては、「 トランザクションと一括操作」を参照してください。

Visual Studio Codeの問題

  • 起動コマンドがありません。 Microsoft Azure Cosmos DB拡張機能 ID ms-azuretools.vscode-cosmosdbがインストールされ、有効になっていることを確認します。 Azure Cosmos DB Shell の起動を実行します。
  • シェルのバージョンが正しくありません。 cosmosDB.shell.path確認し、起動したシェルでversionを実行します。 そのコピーは、ターミナルの PATH上のものとは異なる場合があります。
  • エクスプローラーまたはクエリ エディターは機能しますが、シェルは機能しません。 シェルの接続を個別に確認します。 エディターとシェルが資格情報またはナビゲーションを共有していると想定しないでください。
  • MCP 設定は変更されましたが、サーバーは表示されません。 MCP なしで起動されたシェルを終了し、cosmosDB.shell.MCP.enabled を有効にしてから再度起動します。

サポートされている設定については、Visual Studio Code統合を参照してください。

MCP サーバーの問題

クライアントが接続できない

MCP が有効になっている状態でシェルが実行されていることを確認します。 独立して起動されるプロセスには、次のものが必要です。

cosmosdbshell --mcp

http://127.0.0.1:6128/ では Streamable HTTP を使用し、従来の SSE クライアントには /sse を使用します。 クライアントを使用して MCP の初期化とツールの検出を確認します。 シェルは stdio サーバーではなく、 /health REST チェックを提供しません。

ポートが占有されている場合は、関連のないプロセスをそのままにして、別のポートを選択します。

cosmosdbshell --mcp 6129

一致するようにクライアント URL を更新します。 拡張機能によって起動されたシェルの場合は、代わりに cosmosDB.shell.MCP.port を使用して再起動します。

ツールが使用できないか、実行を拒否する

検出されたツール スキーマを調べます。 sproc、udf、trigger、watch、およびステートフルなバッチ/バルク サブコマンドは、MCP では使用できません。

破壊的操作は、必要なユーザー確認なしでは失敗します。 接続またはナビゲーションを変更すると、保留中の承認も無効になります。 目的のターゲットを再検証してください。別の実行ルートを介して拒否をバイパスしないでください。

結果が不完全であるか、呼び出しが応答待ちになる

MCP クエリと項目リストの結果がページングされます。 null 以外の continuationToken を、同じオプションで continuation として変更せずに渡します。 resultIncomplete: trueを持つ null トークンは、再開できないトランケーションを意味します。 要求を絞り込むか、上限を増やします。

呼び出しはシェルの実行ゲートを共有します。 クライアントの並列処理を増やすのではなく、保留中の確認または実行時間の長いコマンドがないか確認します。 レガシ SSE は、過剰な未処理の要求に対して HTTP 429 を返すことができます。 Retry-Afterに従います。

ヘルプを取得する

シェルの欠陥については、シェルの問題トラッカーで、インストールされているバージョン、オペレーティング システム、インストール方法、サニタイズされたエラー、および関連する診断判定を報告します。 共有する前に、レポートにシークレット、リソース名、ドキュメント データが含まれていないか確認します。

アカウント側のサービスの問題については、Azure サポートを利用してください。 組織のサポート プロセスに適した診断情報のみを含めます。

AI ツール

これらのアクションを使用して、症状とサニタイズされた診断についてアシスタントと話し合います。

ドキュメントのみの取得には、Microsoft Learn MCP サーバーを使用します。 コンパクト ガイド インデックスの場合は、 Shell ドキュメント インデックス (llms.txt) を使用します。 インデックスによってクローラーのアクセス許可が変更されたり、取得が保証されたりすることはありません。

シェル MCP には個別のセットアップが必要であり、構成されたアクセス許可でデータを読み取ったり変更したりできるため、承認する前にツールの呼び出しを確認してください。 資格情報や機密データを共有しないでください。

AI エージェントを接続する
シェル MCP のセットアップと認証の要件を確認してください。

Markdown として読み取る
アシスタントに貼り付けるためにテキスト バージョンを開きます。

ChatGPT に質問する
バージョンとサニタイズされたエラーを使用して症状を診断します。

Claudeに質問する
バージョンとサニタイズされたエラーを使用して症状を診断します。

ChatGPT と Claude は、パブリック記事の URL とスターター プロンプトのみを受け取ります。 ここで、サインインを求められる場合があります。 取得に失敗した場合は、Markdown テキストをコピーしてください。 これらのリンクでデータベース アクセスを構成することはできません。 構成を変更する前に、関連するログとチェックを使用して診断結果を裏付けます。