Azure Cosmos DB シェルのクイック スタート

このガイドでは、アカウントに接続し、その正当性を確認し、コンテナーを検査し、有界クエリを実行します。 オプションの手順では、サンプル データベースを作成し、項目の操作とファイルのやり取りを示します。

Prerequisites

  • Azure Cosmos DB Shell をインストールします。
  • Azure Cosmos DB アカウントとそのデータにアクセスするためのアクセス許可。 省略可能な書き込みの例には、非運用環境用アカウントを使用します。
  • 構成されたファイアウォールとプライベート ネットワーク規則を介して、コンピューターがアカウントに到達できることを確認します。
  • Microsoft Entra 認証の場合は、対象のテナント ID と適切な Azure Cosmos DB データ プレーンのアクセス許可が必要です。 リソース管理アクションには、個別の管理プレーンアクセス許可が必要な場合があります。

接続してアカウントを確認する

オペレーティング システムのターミナルからシェルを起動:

cosmosdbshell

シェル内で次のコマンドを実行します。 アカウント名とテナント ID を置き換えてから、ブラウザーでサインインを完了します。

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

このアカウント ルート スコープで、 accountId と uri を確認し、目的のアカウントが識別されていることを確認します。 一致しない場合は停止してください。 pwd には、アカウント ID ではなく、データベース/コンテナーのナビゲーション パスが表示されます。

構成済みの開発 ID やシステム割り当てマネージド ID など、既存の既定の資格情報チェーンの場合は、 --tenantを省略します。

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

サポートされているAzure環境のユーザー割り当てマネージド ID の場合は、--managed-identity=<client-id>を使用します。 接続では、アクセス許可は自動的に付与されません。

アカウント キーよりもMicrosoft Entra IDを優先します。 接続文字列を使用する場合は、文字列全体を引用符で囲み、ソース管理やチャットに含めないでください。 シェル履歴では、接続コマンドが保持されることがあります。

データベースとコンテナーを検出する

データベースを一覧表示し、データベースの実際の名前の 1 つを MyDatabase に置き換える:

ls
ls --database=MyDatabase

そのデータベースから既存のコンテナーを選択し、その名前を MyContainerに置き換え、境界付けられたサンプルを調べます。

schema --database=MyDatabase --container=MyContainer --sample=20

パーティション キーのパス、フィールド名、および観察された型を確認します。 スキーマ推論では、コンテナー内のすべてのドキュメントではなく、サンプリングされたドキュメントが記述されます。

対話形式で移動することもできます。

cd /MyDatabase/MyContainer
pwd

残りの読み取り例では、ターゲットを明示的に指定します。 この方法では、別の MCP クライアントまたはコマンドによって変更される可能性があるナビゲーションに依存することを避けられます。

境界付きクエリを実行する

最大 5 つの ID を返します。

query "SELECT TOP 5 c.id FROM c" --database=MyDatabase --container=MyContainer --max=5

対話型 query には既定の結果制限がないため、正の --maxを指定します。 クエリは、小さな結果が返された場合でも RU を使用します。 必要なフィールドのみをProjectします。

項目の正確な ID と完全なパーティション キーがわかっている場合は、クエリではなく print ポイント読み取りを使用します。 パーティション キー値の型を保持します。たとえば、数値 680 と文字列 '"680"' は、異なるパーティションを対象とします。

アクセスの診断

アカウントの設定または資格情報を変更する前に、読み取り専用診断を実行します。

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

doctor は、合格、警告、失敗、スキップされたチェックを区別します。 既定の更新チェックは、パブリック GitHub リリースを確認します。--no-update-checkはその参照を無効にします。 can-i query は小さなクエリ プローブを実行し、RU を使用します。 プローブは、割り当てられたアクセス許可の完全な監査ではありません。

サンプルの書き込みを試す

この省略可能なセクションは、データを作成する予定のある非運用アカウントでのみ使用します。 このサンプルでは、 ShellDemoという名前の新しいデータベース、 Itemsという名前のコンテナー、およびパーティション キーとして /tenantId を使用します。

Important

次のコマンドは、リソースを作成し、データを書き込みます。 プロビジョニング済みスループット アカウントでは、この例ではデータベースの自動スケーリングと専用コンテナーのスループットを構成します。どちらも料金が発生する可能性があります。 未使用のリソース名を使用し、接続されているアカウントを確認してから続行します。

サンプル リソースを作成する

未使用のデータベース名を選択する前に、アカウント ルートに戻り、アカウントを確認し、データベースを一覧表示します。

cd
info --format=json
ls

mkdb には、アカウント ルート スコープが必要です。 各作成コマンドを個別に実行し、その結果を確認してから続行します。 作成時に既存のリソースが報告された場合は、再利用するのではなく、停止し、未使用の名前を選択します。

プロビジョニング済みスループット アカウントの場合:

mkdb ShellDemo --scale=auto --ru=1000
cd /ShellDemo
mkcon Items /tenantId --scale=manual --ru=400

サーバーレス アカウントでは、代わりにスループット オプションを省略してください。

mkdb ShellDemo
cd /ShellDemo
mkcon Items /tenantId

アカウントに適したシーケンスのみを実行します。 いずれかのリソースが既に存在する場合は、関連のないデータを変更するのではなく、中止し、未使用の名前を選択します。

アイテムの作成と読み取り

1 つのサンプル項目を作成し、ポイント読み取りで確認します。

mkitem '{"id":"sample-1","tenantId":"demo","status":"new","quantity":1}' --database=ShellDemo --container=Items
print sample-1 demo --database=ShellDemo --container=Items

文字列 demo は、項目の /tenantId パーティション キー値です。

フィールドを更新する

サンプル項目の状態のみを変更し、その後で結果を確認してください。

patch set sample-1 demo /status reviewed --database=ShellDemo --container=Items
print sample-1 demo --database=ShellDemo --container=Items

同時実行ワークフローの場合は、現在の項目を読み取り、実際の ETag に --etag を指定して、未表示のバージョンを変更しないようにします。

インポートをエクスポートして検証する

サンプル項目のみを新しいローカル ファイルにエクスポートします:

export sample-items.json --database=ShellDemo --container=Items --query="SELECT * FROM c WHERE c.tenantId = 'demo' AND c.id = 'sample-1'" --max=1
import sample-items.json --database=ShellDemo --container=Items --dry-run

エクスポートされたファイルは、インポートが直接読み取ることができる JSON 配列です。 jq 変換は必要ありません。 .csv変換先として CSV を選択する場合、CSV インポートでは値が文字列に変換されるため、型付き JSON のラウンドトリップにはなりません。

インポート ドライ ランはオフラインです。ターゲットに接続せずに構文と項目 ID を検証します。 検証済みのレコードを報告し、項目は 0 件インポートされます。 ターゲットのアクセス許可、パーティション キーの互換性、または ID が既に存在するかどうかは確認しません。

ファイルを別の互換性のあるコンテナーにコピーするには、そのコピー先を指定し、確認した後でのみ --dry-run を削除します。 既存の ID では、既定の挿入モードが失敗します。 --mode=upsert は上書きできます。 この動作が意図されている場合を除き、この例を元のコンテナーにインポートし直さないでください。

トランザクション バッチと独立したクロスパーティション書き込みについては、「トランザクションと一括操作」を参照してください。

サンプル リソースをクリーンアップする

Warning

サンプル データベースを削除すると、その中のすべてのコンテナーと項目が削除されます。 それをこのガイド用に自分で作成し、その内容が不要な場合にのみ続行します。

アカウント ルートに戻り、 accountId と uri が目的のアカウントを識別していることを確認し、データベースの削除をプレビューします。

cd
info --format=json
rmdb ShellDemo --dry-run

アカウントとデータベースをもう一度確認します。 プレビューでこのガイド用に作成されたデータベースのみが識別される場合は、rmdb ShellDemo を実行し、対話型の確認を承認します。 削除を確認するには、後でアカウント ルートで ls を使用します。 これらの例をクリーンアップするために、既存のデータベースを削除しないでください。

代わりにサンプル項目のみを削除する場合は、実際のプレビュー ETag を含む 項目の正確な削除手順に従います。

ローカル コピーが不要になったら、オペレーティング システムのファイル ツールで sample-items.json を削除します。 次のコマンドでシェルを終了します:

exit

AI ツール

これらのアクションを使用して、最初の Shell セッションについてアシスタントと確認します。

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

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

AI エージェントを接続する
認証されたデータベース操作用にシェル MCP を構成します。

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

ChatGPT に質問する
最初のセッションを計画し、各コマンドを理解します。

Claudeに質問する
最初のセッションを計画し、各コマンドを理解します。

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