クイックスタート: .NET 用 Azure Cosmos DB for NoSQL ライブラリ

[アーティクル]
11/07/2024
適用対象:

✅ NoSQL

.NET 用 Azure Cosmos DB for NoSQL クライアントライブラリを使用して、コンテナー内のデータのクエリを実行し、個々の項目で一般的な操作を実行できます。次の手順に従って、Azure Developer CLI を使用して最小限のソリューションを環境にデプロイしてください。

API のリファレンスドキュメント | ライブラリのソースコード | パッケージ (NuGet) | Azure Developer CLI

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
GitHub アカウント

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
Azure Developer CLI
Docker Desktop

設定

このプロジェクトの開発コンテナーをお使いの環境にデプロイします。次に、Azure Developer CLI (azd) を使って、Azure Cosmos DB for NoSQL アカウントを作成し、コンテナー化されたサンプルアプリケーションをデプロイします。サンプルアプリケーションでは、クライアントライブラリを使って、サンプルデータの管理、作成、読み取り、クエリを実行します。

重要

GitHub アカウントには、ストレージとコア時間のエンタイトルメントが無料で含まれています。詳細については、GitHub アカウントに含まれるストレージとコア時間に関する記事を参照してください。

プロジェクトのルートディレクトリでターミナルを開きます。
azd auth login を使って Azure Developer CLI に対して認証します。ツールによって指示された手順に従って、任意の Azure 資格情報を使って CLI に対して認証します。
```
azd auth login
```
azd init を使ってプロジェクトを初期化します。
```
azd init --template cosmos-db-nosql-dotnet-quickstart
```
Note

このクイックスタートでは、azure-samples/cosmos-db-nosql-dotnet-quickstart テンプレート GitHub リポジトリを使用します。まだない場合は、Azure Developer CLI によってこのプロジェクトがマシンに自動的にクローンされます。
初期化中に、一意の環境名を構成します。

ヒント

この環境名は、ターゲットリソースグループ名としても使用されます。このクイックスタートでは、msdocs-cosmos-db の使用を検討してください。
azd up を使って、Azure Cosmos DB アカウントをデプロイします。 Bicep テンプレートは、サンプル Web アプリケーションもデプロイします。
```
azd up
```
プロビジョニングプロセス中に、サブスクリプションと目的の場所を選択します。プロビジョニングプロセスが完了するまで待ちます。このプロセスには 5 分ほどかかる可能性があります。

Azure リソースのプロビジョニングが完了すると、実行中の Web アプリケーションへの URL が出力に含まれます。

Deploying services (azd deploy)

  (✓) Done: Deploying service web
- Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>

SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.

コンソールで URL を使って、ブラウザーで Web アプリケーションに移動します。実行中のアプリの出力を確認します。

クライアントライブラリをインストールする

クライアントライブラリは、NuGet を介して Microsoft.Azure.Cosmos パッケージとして入手できます。

ターミナルを開き、/src/web フォルダーに移動します。
```
cd ./src/web
```
Microsoft.Azure.Cosmos パッケージがまだインストールされていない場合は、dotnet add package を使ってインストールします。
```
dotnet add package Microsoft.Azure.Cosmos --version 3.*
```
また、Azure.Identity パッケージがまだインストールされていない場合はインストールします。
```
dotnet add package Azure.Identity --version 1.12.*
```
src/web/Cosmos.Samples.NoSQL.Quickstart.Web.csproj ファイルを開いて確認し、Microsoft.Azure.Cosmos と Azure.Identity の両エントリが存在することを確認します。

オブジェクトモデル

名前	説明
CosmosClient	このクラスは主要なクライアントクラスであり、アカウント全体のメタデータやデータベースを管理するために使われます。
Database	このクラスはアカウント内のデータベースを表します。
Container	このクラスは主に、コンテナーまたはコンテナー内に格納されている項目の読み取り、更新、削除操作を実行するために使われます。
PartitionKey	このクラスは論理パーティションキーを表します。このクラスは、多くの一般的な操作とクエリに必要です。

テンプレートのサンプルコードでは、cosmicworks というデータベースと products というコンテナーを使います。 products コンテナーには、各製品の名前、カテゴリ、数量、一意識別子、販売フラグなどの詳細が含まれています。コンテナーでは、論理パーティションキーとして /category プロパティを使います。

クライアントを認証する

ほとんどの Azure サービスに対するアプリケーション要求は、承認される必要があります。アプリケーションと Azure Cosmos DB for NoSQL の間でパスワードレスの接続を実装するため、推奨される方法として、DefaultAzureCredential 型を使います。 DefaultAzureCredential は複数の認証方法をサポートしており、実行時に使用する方法が決定されます。

重要

パスワード、接続文字列、その他の資格情報を使用して、Azure サービスへの要求を直接承認することもできます。ただし、この方法は慎重に使用する必要があります。開発者は、安全でない場所にこれらのシークレットを公開しないように注意する必要があります。パスワードまたは秘密鍵へのアクセス権を取得したユーザーは誰でも、データベースサービスに対して認証を行うことができます。 DefaultAzureCredential はアカウントキーよりも管理しやすく、セキュリティが優れており、キーを保存するリスクなくパスワードレス認証が可能になります。

このサンプルでは、CosmosClient クラスの新しいインスタンスを作成し、DefaultAzureCredential インスタンスを使って認証します。

DefaultAzureCredential credential = new();

CosmosClient client = new(
    accountEndpoint: "<azure-cosmos-db-nosql-account-endpoint>",
    tokenCredential: new DefaultAzureCredential()
);

データベースの取得

client.GetDatabase を使って、cosmicworks という既存のデータベースを取得します。

Database database = client.GetDatabase("cosmicworks");

コンテナーの取得

database.GetContainer を使って既存の products コンテナーを取得します。

Container container = database.GetContainer("products");

項目を作成する

JSON にシリアル化するすべてのメンバーを含む C# レコード型を構築します。この例では、型には一意識別子、カテゴリ、名前、数量、価格、販売のフィールドが含まれます。

public record Product(
    string id,
    string category,
    string name,
    int quantity,
    decimal price,
    bool clearance
);

container.UpsertItem を使ってコンテナー内に項目を作成します。このメソッドは "アップサート" を行い、項目が既に存在する場合は、それを効果的に置き換えます。

Product item = new(
    id: "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    category: "gear-surf-surfboards",
    name: "Yamba Surfboard",
    quantity: 12,
    price: 850.00m,
    clearance: false
);

ItemResponse<Product> response = await container.UpsertItemAsync<Product>(
    item: item,
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

項目を読み取る

一意識別子 (id) フィールドとパーティションキーフィールドの両方を使って、ポイント読み取り操作を実行できます。 container.ReadItem を使って、特定の項目を効率的に取得できます。

ItemResponse<Product> response = await container.ReadItemAsync<Product>(
    id: "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

クエリ項目

container.GetItemQueryIterator を使って、コンテナー内の複数の項目に対してクエリを実行します。次のパラメーター化クエリを使用して、指定されたカテゴリ内のすべての項目を検索します。

SELECT * FROM products p WHERE p.category = @category

string query = "SELECT * FROM products p WHERE p.category = @category"

var query = new QueryDefinition(query)
  .WithParameter("@category", "gear-surf-surfboards");

using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryDefinition: query
);

feed.ReadNextAsync を使用して結果の各ページをループすることにより、クエリのページ分割された結果を解析します。 feed.HasMoreResults を使用して、各ループの開始時に結果が残っているかどうかを判断します。

List<Product> items = new();
while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        items.Add(item);
    }
}

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

サンプルアプリケーションやリソースが不要になったら、対応するデプロイとすべてのリソースを削除します。

azd down

GitHub Codespaces で、実行中のコードスペースを削除して、ストレージとコアエンタイトルメントを最大化します。

次の方法で共有

クイックスタート: .NET 用 Azure Cosmos DB for NoSQL ライブラリ

前提条件

設定

クライアントライブラリをインストールする

オブジェクトモデル

コード例

クライアントを認証する

データベースの取得

コンテナーの取得

項目を作成する

項目を読み取る

クエリ項目

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

フィードバック

その他のリソース

次の方法で共有

クイックスタート: .NET 用 Azure Cosmos DB for NoSQL ライブラリ

前提条件

設定

クライアント ライブラリをインストールする

オブジェクト モデル

コード例

クライアントを認証する

データベースの取得

コンテナーの取得

項目を作成する

項目を読み取る

クエリ項目

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

関連するコンテンツ

フィードバック

その他のリソース

クライアントライブラリをインストールする

オブジェクトモデル