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

適用対象: NoSQL

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

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

前提条件

設定

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

GitHub codespaces で開く

開発コンテナーで開く

重要

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

  1. プロジェクトのルート ディレクトリでターミナルを開きます。

  2. azd auth login を使って Azure Developer CLI に対して認証します。 ツールによって指示された手順に従って、任意の Azure 資格情報を使って CLI に対して認証します。

    azd auth login
    
  3. azd init を使ってプロジェクトを初期化します。

    azd init
    
  4. 初期化中に、一意の環境名を構成します。

    ヒント

    この環境名は、ターゲット リソース グループ名としても使用されます。 このクイックスタートでは、msdocs-cosmos-db- の使用を検討してください。

  5. azd up を使って、Azure Cosmos DB アカウントをデプロイします。 Bicep テンプレートは、サンプル Web アプリケーションもデプロイします。

    azd up
    
  6. プロビジョニング プロセス中に、サブスクリプションと目的の場所を選択します。 プロビジョニング プロセスが完了するまで待ちます。 このプロセスには 5 分ほどかかる可能性があります。

  7. 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.
    
  8. コンソールで URL を使って、ブラウザーで Web アプリケーションに移動します。 実行中のアプリの出力を確認します。

    実行中の Web アプリケーションのスクリーンショット。

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

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

  1. ターミナルを開き、/src/web フォルダーに移動します。

    cd ./src/web
    
  2. Microsoft.Azure.Cosmos パッケージがまだインストールされていない場合は、dotnet add package を使ってインストールします。

    dotnet add package Microsoft.Azure.Cosmos
    
  3. また、Azure.Identity パッケージがまだインストールされていない場合はインストールします。

    dotnet add package Azure.Identity
    
  4. src/web/Cosmos.Samples.NoSQL.Quickstart.Web.csproj ファイルを開いて確認し、Microsoft.Azure.CosmosAzure.Identity の両エントリが存在することを確認します。

オブジェクト モデル

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

コード例

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

クライアントを認証する

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

重要

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

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

CosmosClient client = new(
    accountEndpoint: builder.Configuration["AZURE_COSMOS_DB_NOSQL_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: "68719518391",
    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: "68719518391",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

クエリ項目

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

SELECT * FROM products p WHERE p.category = @category
var query = new QueryDefinition(
    query: "SELECT * FROM products p WHERE p.category = @category"
)
    .WithParameter("@category", "gear-surf-surfboards");

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

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

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

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

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

azd down

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

次のステップ