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

[アーティクル]
06/01/2023

適用対象: 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

プロジェクトの設定

.NET コンソールアプリケーションを作成する

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 クラスのインスタンスを作成します。このクラスは、データベースに対するすべての操作を実行するための開始点です。 CosmosClient クラスを使用して NoSQL 用 API アカウントに接続する主な方法は次の 3 つです。

NoSQL 用 API エンドポイントと読み取り/書き込みキーを使用して接続する
NoSQL 用 API 接続文字列を使用して接続する
Microsoft Entra ID を使用して接続する

エンドポイントとキーを使用して接続する

CosmosClient の最も一般的なコンストラクターには、次の 2 つのパラメーターがあります。

パラメーター	値の例	説明
`accountEndpoint`	`COSMOS_ENDPOINT` 環境変数	すべての要求に使用する NoSQL 用 API エンドポイント
`authKeyOrResourceToken`	`COSMOS_KEY` 環境変数	認証時に使用するアカウントキーまたはリソーストークン

アカウントエンドポイントとキーを取得する

resourceGroupName のシェル変数を作成します。

# Variable for resource group name
resourceGroupName="msdocs-cosmos-dotnet-howto-rg"

az cosmosdb list コマンドを使用して、リソースグループ内の最初の Azure Cosmos DB アカウントの名前を取得し、それを accountName シェル変数に格納します。
```
# Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)
```
az cosmosdb show コマンドを使用して、アカウントの NoSQL 用 API エンドポイント URI を取得します。
```
az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "documentEndpoint"
```

az-cosmosdb-keys-list コマンドを使用して、アカウントのキーの一覧から PRIMARY KEY を見つけます。

az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

URI と PRIMARY KEY の値を記録します。これらの資格情報は後で使用します。

RESOURCE_GROUP_NAME のシェル変数を作成します。

# Variable for resource group name
$RESOURCE_GROUP_NAME = "msdocs-cosmos-dotnet-howto-rg"

Get-AzCosmosDBAccount コマンドレットを使用して、リソースグループ内の最初の Azure Cosmos DB アカウントの名前を取得し、それを ACCOUNT_NAME シェル変数に格納します。

# Retrieve most recently created account name
$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
}
$ACCOUNT_NAME = (
    Get-AzCosmosDBAccount @parameters |
        Select-Object -Property Name -First 1
).Name

Get-AzCosmosDBAccount コマンドレットを使用して、アカウントの NoSQL 用 API エンドポイント URI を取得します。

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
}
Get-AzCosmosDBAccount @parameters |
    Select-Object -Property "DocumentEndpoint"

Get-AzCosmosDBAccountKey コマンドレットを使用して、アカウントのキーの一覧から PRIMARY KEY を見つけます。

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
    Type = "Keys"
}    
Get-AzCosmosDBAccountKey @parameters |
    Select-Object -Property "PrimaryMasterKey"

URI と PRIMARY KEY の値を記録します。これらの資格情報は後で使用します。

ヒント

このガイドでは、リソースグループ名 msdocs-cosmos-dotnet-howto-rg を使用することをお勧めします。

Azure portal にサインインします。
既存の Azure Cosmos DB for NoSQL アカウントページに移動します。
Azure Cosmos DB for NoSQL アカウントページで、[キー] ナビゲーションメニューオプションを選択します。
URI フィールドと PRIMARY KEY フィールドの値を記録します。これらの値は、後の手順で使用します。

.NET コード内で URI 値と PRIMARY KEY 値を使用するには、アプリケーションを実行しているローカルコンピューター上の新しい環境変数に保持します。

Windows
Linux/macOS

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

export COSMOS_ENDPOINT="<cosmos-account-URI>"
export COSMOS_KEY="<cosmos-account-PRIMARY-KEY>"

アカウントエンドポイントとキーを使用して CosmosClient を作成する

COSMOS_ENDPOINT および COSMOS_KEY 環境変数をパラメーターとして使用し、CosmosClient クラスの新しいインスタンスを作成します。

// New instance of CosmosClient class using an endpoint and key string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    authKeyOrResourceToken: Environment.GetEnvironmentVariable("COSMOS_KEY")!
);

接続文字列を使用して接続する

CosmosClient の別のコンストラクターには、1 つのパラメーターのみが含まれています。

パラメーター	値の例	説明
`accountEndpoint`	`COSMOS_ENDPOINT` 環境変数	すべての要求に使用する NoSQL 用 API エンドポイント
`connectionString`	`COSMOS_CONNECTION_STRING` 環境変数	NoSQL 用 API アカウントへの接続文字列

アカウント接続文字列を取得する

az cosmosdb list コマンドを使用して、リソースグループ内の最初の Azure Cosmos DB アカウントの名前を取得し、それを accountName シェル変数に格納します。
```
# Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)
```

az-cosmosdb-keys-list コマンドを使用して、アカウントの接続文字列の一覧から "プライマリ接続文字列" を見つけます。

az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "connection-strings" \
    --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"

# Retrieve most recently created account name
$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
}
$ACCOUNT_NAME = (
    Get-AzCosmosDBAccount @parameters |
        Select-Object -Property Name -First 1
).Name

Get-AzCosmosDBAccountKey コマンドレットを使用して、アカウントの接続文字列の一覧からプライマリ接続文字列を見つけます。

$parameters = @{
    ResourceGroupName = $RESOURCE_GROUP_NAME
    Name = $ACCOUNT_NAME
    Type = "ConnectionStrings"
}    
Get-AzCosmosDBAccountKey @parameters |
    Select-Object -Property "Primary SQL Connection String" -First 1

ヒント

このガイドでは、リソースグループ名 msdocs-cosmos-dotnet-howto-rg を使用することをお勧めします。

Azure portal にサインインします。
既存の Azure Cosmos DB for NoSQL アカウントページに移動します。
Azure Cosmos DB for NoSQL アカウントページで、[キー] ナビゲーションメニューオプションを選択します。
[プライマリ接続文字列] フィールドの値を記録します。

.NET コード内でプライマリ接続文字列値を使用するには、アプリケーションを実行しているローカルコンピューター上で新しい環境変数にそれを保持します。

Windows
Linux/macOS

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

export COSMOS_CONNECTION_STRING="<cosmos-account-PRIMARY-CONNECTION-STRING>"

接続文字列を使用して CosmosClient を作成する

COSMOS_CONNECTION_STRING 環境変数を唯一のパラメーターとして使用し、CosmosClient クラスの新しいインスタンスを作成します。

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    connectionString: Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING")!
);

Microsoft ID プラットフォームを使用して接続する

Microsoft ID プラットフォームと Microsoft Entra ID を使用して 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
);

カスタム資格情報の実装を使用して CosmosClient を作成する

Azure の外部のアプリケーションをデプロイする場合は、.Net 用 Azure Identity クライアントライブラリの他のクラスを使って、OAuth トークンを取得できます。これらの他のクラスは、TokenCredential クラスからも派生します。

この例では、クライアントとテナントの識別子、およびクライアントシークレットを使用して ClientSecretCredential インスタンスを作成します。

// Custom credential class for servers and clients outside of Azure
TokenCredential credential = new ClientSecretCredential(
    tenantId: Environment.GetEnvironmentVariable("AAD_TENANT_ID")!,
    clientId: Environment.GetEnvironmentVariable("AAD_CLIENT_ID")!,
    clientSecret: Environment.GetEnvironmentVariable("AAD_CLIENT_SECRET")!,
    options: new TokenCredentialOptions()
);

アプリケーションを Microsoft Entra ID に登録するときに、クライアント ID、テナント ID、クライアントシークレットを取得できます。 Microsoft Entra アプリケーションの登録の詳細については、「Microsoft ID プラットフォームにアプリケーションを登録する」を参照してください。

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 ドキュメントを表す項目。

次の図に、これらのリソースの関係を示します。

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, containers, and items.

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

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

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

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

次のステップ

これで NoSQL 用 API アカウントに接続したので、次のガイドを使用してデータベースを作成し、管理してください。

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

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

前提条件

プロジェクトの設定

.NET コンソールアプリケーションを作成する

Azure Cosmos DB for NoSQL に接続する

エンドポイントとキーを使用して接続する

アカウントエンドポイントとキーを取得する

アカウントエンドポイントとキーを使用して CosmosClient を作成する

接続文字列を使用して接続する

アカウント接続文字列を取得する

接続文字列を使用して CosmosClient を作成する

Microsoft ID プラットフォームを使用して接続する

Azure.Identity のインポート

既定の資格情報の実装を使用して CosmosClient を作成する

カスタム資格情報の実装を使用して CosmosClient を作成する

アプリケーションをビルドする

関連項目

次のステップ

その他のリソース

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

前提条件

プロジェクトの設定

.NET コンソール アプリケーションを作成する

Azure Cosmos DB for NoSQL に接続する

エンドポイントとキーを使用して接続する

アカウント エンドポイントとキーを取得する

アカウント エンドポイントとキーを使用して CosmosClient を作成する

接続文字列を使用して接続する

アカウント接続文字列を取得する

接続文字列を使用して CosmosClient を作成する

Microsoft ID プラットフォームを使用して接続する

Azure.Identity のインポート

既定の資格情報の実装を使用して CosmosClient を作成する

カスタム資格情報の実装を使用して CosmosClient を作成する

アプリケーションをビルドする

関連項目

次のステップ

その他のリソース

.NET コンソールアプリケーションを作成する

アカウントエンドポイントとキーを取得する

アカウントエンドポイントとキーを使用して CosmosClient を作成する