.NET を使用して Azure Cosmos DB for NoSQL の使用を開始する

[アーティクル]
10/07/2024

適用対象: NoSQL

この記事では、.NET SDK を使用して Azure Cosmos DB for NoSQL に接続する方法を示します。接続すると、データベース、コンテナー、および項目に対する操作を実行できます。

パッケージ (NuGet) | サンプル | API リファレンス | ライブラリソースコード | フィードバックを送る

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
Azure Cosmos DB for NoSQL アカウント。 NoSQL 用 API アカウントを作成します。
.NET 6.0 以降
Azure コマンドラインインターフェイス (CLI) または Azure PowerShell

プロジェクトの設定

dotnet new コマンドとコンソール テンプレートを使用して、新しい .NET アプリケーションを作成します。

dotnet new console

dotnet add package コマンドを使用して、Microsoft.Azure.Cosmos 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 またはサービスプリンシパル
Azure	マネージド ID
Azure の外部にあるサーバーまたはクライアント	サービスプリンシパル

Azure.Identity のインポート

Azure.Identity NuGet パッケージには、すべての Azure SDK ライブラリ間で共有されるコア認証機能が含まれています。

dotnet add package コマンドを使用して、Azure.Identity 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 環境変数と TokenCredential オブジェクトをパラメーターとして使用して、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 階層の図。

各種類のリソースは、1 つまたは複数の関連付けられた .NET クラスによって表されます。以下に最も一般的なクラスの一覧を示します。

クラス	説明
`CosmosClient`	このクラスは、Azure Cosmos DB サービスのクライアント側の論理表現を提供します。このクライアントオブジェクトは、サービスに対する要求の構成と実行に使用されます。
`Database`	このクラスは、サービスにまだ存在する場合と存在しない場合があるデータベースへの参照です。データベースへのアクセスまたはデータベースに対する操作の実行を試みると、データベースはサーバー側で検証されます。
`Container`	このクラスは、まだサービスに存在しない可能性があるコンテナーへの参照です。コンテナーを操作しようとすると、コンテナーはサーバー側で検証されます。

次のガイドでは、これらの各クラスを使ってアプリケーションをビルドする方法を示します。

ガイド	説明
データベースの作成	データベースを作成する
コンテナーの作成	コンテナーを作成する
項目を読み取る	特定の項目のポイント読み取り
クエリ項目	複数の項目のクエリの実行

次のステップ

.NET を使用して Azure Cosmos DB for NoSQL にデータベースを作成する

次の方法で共有