この記事では、.NET SDK を使用して Azure Cosmos DB for NoSQL に接続する方法について説明します。 接続したら、データベース、コンテナー、および項目に対して操作を実行できます。
パッケージ (NuGet) | API リファレンス | ライブラリのソース コード | フィードバックを送信する
[前提条件]
- アクティブなサブスクリプションを持つ Azure アカウント。 無料でアカウントを作成できます。
- NoSQL 用の Azure Cosmos DB アカウント。 NoSQL 用 API アカウントを作成します。
- .NET 6.0 以降
- Azure コマンド ライン インターフェイス (CLI) または Azure PowerShell
プロジェクトの設定
dotnet new コマンドとコンソール テンプレートを使用して、新しい .NET アプリケーションを作成します。
dotnet new console
コマンドを使用してdotnet add package NuGet パッケージをインポートします。
dotnet add package Microsoft.Azure.Cosmos
dotnet build コマンドを使ってプロジェクトをビルドします。
dotnet build
Azure Cosmos DB for NoSQL に接続する
Azure Cosmos DB の NoSQL 用 API に接続するには、 CosmosClient クラスのインスタンスを作成します。 このクラスは、データベースに対するすべての操作を実行するための開始点です。
Microsoft Entra を使用して NoSQL 用 API アカウントに接続するには、セキュリティ プリンシパルを使用します。 プリンシパルの正確な種類は、アプリケーション コードをホストする場所によって異なります。 次の表は、クイック リファレンス ガイドとして機能します。
| アプリケーションの実行場所 | セキュリティ プリンシパル |
|---|---|
| ローカル コンピューター (開発とテスト) | ユーザー ID またはサービス プリンシパル |
| 紺碧 | マネージド ID |
| Azure の外部にあるサーバーまたはクライアント | サービス プリンシパル |
Azure.Identity のインポート
Azure.Identity NuGet パッケージには、すべての Azure SDK ライブラリ間で共有されるコア認証機能が含まれています。
コマンドを使用して、dotnet add package NuGet パッケージをインポートします。
dotnet add package Azure.Identity
dotnet build コマンドを使用してプロジェクトを再構築します。
dotnet build
コード エディターで、Azure.Core および Azure.Identity 名前空間のディレクティブを使用して追加します。
using Azure.Core;
using Azure.Identity;
既定の資格情報の実装を使用して CosmosClient を作成する
ローカル コンピューター上でテストする場合、またはマネージド ID を直接サポートする Azure サービス上でアプリケーションを実行する場合は、DefaultAzureCredential インスタンスを作成して OAuth トークンを取得します。
この例では、インスタンスを TokenCredential 型の変数に保存しました。これは、SDK 全体で再利用できるより汎用的な型であるためです。
// Credential class for testing on a local machine or Azure services
TokenCredential credential = new DefaultAzureCredential();
環境変数と COSMOS_ENDPOINT オブジェクトをパラメーターとして使用して、CosmosClient クラスの新しいインスタンスを作成します。
// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
tokenCredential: credential
);
アプリケーションをビルドする
アプリケーションをビルドすると、コードは主に 4 種類のリソースと対話します。
NoSQL アカウント用の API は、Azure Cosmos DB データに対する一意かつ最上位の名前空間です。
アカウント内のコンテナーを整理するデータベース。
データベース内の個々の項目のセットを含むコンテナー。
コンテナー内の JSON ドキュメントを表す項目。
次の図は、これらのリソース間の関係を示しています。
上部に Azure Cosmos DB アカウントを示す階層図。 アカウントには 2 つの子データベース ノードがあります。 一方のデータベース ノードには、2 つの子コンテナー ノードが含まれています。 もう一方のデータベース ノードには、1 つの子コンテナー ノードが含まれています。 その 1 つのコンテナー ノードには、3 つの子項目ノードがあります。
各種類のリソースは、1 つ以上の関連付けられた .NET クラスによって表されます。 最も一般的なクラスの一覧を次に示します。
| クラス | Description |
|---|---|
CosmosClient |
このクラスは、Azure Cosmos DB サービスのクライアント側の論理表現を提供します。 このクライアント オブジェクトは、サービスに対する要求の構成と実行に使用されます。 |
Database |
このクラスは、サービスにまだ存在する場合と存在しない場合があるデータベースへの参照です。 データベースへのアクセスまたはデータベースに対する操作の実行を試みると、データベースはサーバー側で検証されます。 |
Container |
このクラスは、まだサービスに存在しないコンテナーへの参照です。 コンテナーを操作しようとすると、コンテナーはサーバー側で検証されます。 |
次のガイドでは、これらの各クラスを使ってアプリケーションをビルドする方法を示します。
| ガイド | Description |
|---|---|
| データベースの作成 | データベースの作成 |
| コンテナーの作成 | コンテナーを作成する |
| 項目を読み取る | 特定の項目を指して読む |
| クエリ項目 | 複数のアイテムに対してクエリを実行する |