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

適用対象: Table

• .NET
• Python
• Node.js
• Java

このクイック スタートでは、.NET アプリケーションから Azure Cosmos DB for Table を使用する方法について説明します。 Azure Cosmos DB for Table はスキーマレス データ ストアであり、これによりアプリケーションは構造化されたテーブル データをクラウドに格納できます。 Azure SDK for .NET を使用して、Azure Cosmos DB リソース内でテーブル、行を作成し、基本的なタスクを実行する方法を学習します

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

前提条件

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

プロジェクトを初期化する

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

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

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

   azd auth login
   

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

   azd init --template cosmos-db-table-dotnet-quickstart
   

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

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 アプリケーションに移動します。 実行中のアプリの出力を確認します。

   

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

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

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

   cd ./src/web
   

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

   dotnet add package Azure.Data.Tables
   

3. src/web/Microsoft.Samples.Cosmos.Table.Quickstart.Web.csproj ファイルを開いて確認し、Azure.Data.Tables エントリが存在することを確認します。

オブジェクト モデル

名前	説明
TableServiceClient	このクラスは主要なクライアント クラスであり、アカウント全体のメタデータやデータベースを管理するために使われます。
TableClient	このクラスは、アカウント内のテーブルのクライアントを表します。

コード例

• クライアントを認証する
• テーブルを取得する
• 項目の作成
• アイテムを取得する
• クエリ項目

テンプレート内のサンプル コードでは、cosmicworks-products という名前のテーブルを使用します。 cosmicworks-products テーブルには、各製品の名前、カテゴリ、数量、価格、一意識別子、販売フラグなどの詳細が含まれています。 コンテナーでは、行キーとして "一意識別子"* を使用し、パーティション キーとして "カテゴリ" を使用します。

クライアントを認証する

このサンプルでは、TableServiceClient クラスの新しいインスタンスを作成します。

TableServiceClient serviceClient = new(
    endpoint: new Uri("<azure-cosmos-db-table-account-endpoint>"),
    credential
);

テーブルを取得

このサンプルでは、TableServiceClient クラスの GetTableClient メソッドを使用して TableClient クラスのインスタンスを作成します。

TableClient client = serviceClient.GetTableClient(
    tableName: "<azure-cosmos-db-table-name>"
);

項目を作成する

テーブルに新しい項目を作成する最も簡単な方法は、ITableEntity インターフェイスを実装するクラスを作成することです。 その後、クラスに独自のプロパティを追加して、そのテーブル行のデータ列を設定できます。

public record Product : ITableEntity
{
    public string RowKey { get; set; } = $"{Guid.NewGuid()}";

    public string PartitionKey { get; set; } = String.Empty;

    public string Name { get; set; } = String.Empty;

    public int Quantity { get; set; } = 0;

    public decimal Price { get; set; } = 0.0m;

    public bool Clearance { get; set; } = false;

    public ETag ETag { get; set; } = ETag.All;

    public DateTimeOffset? Timestamp { get; set; }
};

TableClient.AddEntityAsync<T> を呼び出し、Product クラスを使用してコレクション内に項目を作成します。

Product entity = new()
{
    RowKey = "68719518391",
    PartitionKey = "gear-surf-surfboards",
    Name = "Surfboard",
    Quantity = 10,
    Price = 300.00m,
    Clearance = true
};

Response response = await client.UpsertEntityAsync<Product>(
    entity: entity,
    mode: TableUpdateMode.Replace
);

アイテムを取得する

TableClient.GetEntityAsync<T> メソッドを使用して、テーブルから特定の項目を取得できます。 partitionKey と rowKey をパラメーターに指定し、正しい行を特定してその項目のクイック ポイント リードを実行できます。

Response<Product> response = await client.GetEntityAsync<Product>(
    rowKey: "68719518391",
    partitionKey: "gear-surf-surfboards"
);

クエリ項目

項目を挿入した後、TableClient.Query<T> メソッドを使用して、特定のフィルターに一致するすべての項目を取得するクエリを実行することもできます。 この例では、Linq 構文を使って商品をカテゴリー別にフィルタリングしていますが、これは Product クラスのように型指定された ITableEntity モデルを使用する利点となります。

Note

OData 構文を使用して項目のクエリを実行することもできます。 この方法の例については、「クエリ データ」チュートリアルをご覧ください。

string category = "gear-surf-surfboards";

AsyncPageable<Product> results = client.QueryAsync<Product>(
    product => product.PartitionKey == category
);

非同期ループを使用して結果の各ページをループすることにより、クエリのページ分割された結果を解析します。

List<Product> entities = new();
await foreach (Product product in results)
{
    entities.Add(product);
}

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

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

azd down

関連するコンテンツ

• Node.js クイック スタート
• Python クイックスタート
• Java クイックスタート