クイック スタート - .NET 用 Azure Cosmos DB for Table

適用対象: Table

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

注意

コード スニペットの例は、.NET プロジェクトとしてGitHub 上で使用できます。

Table リファレンス ドキュメント用 API | Azure.Data.Tables パッケージ (NuGet)

前提条件

設定

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

Open in GitHub Codespaces

Open in Dev Container

重要

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

    Screenshot of the running web application.

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

クライアント ライブラリは、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.Table.Quickstart.Web.csproj ファイルを開いて確認し、Microsoft.Azure.CosmosAzure.Identity の両エントリが存在することを確認します。

コード例

このアーティクルで説明されているサンプル コードでは、adventureworks という名前のテーブルを作成します。 各テーブル行には、名前、カテゴリ、数量、販売インジケーターなどの製品詳細が含まれています。 各製品には、一意の識別子も含まれています。

これらのリソースとやり取りするには、以下の Table 用 API クラスを使用します。

  • TableServiceClient - このクラスは、Azure Cosmos DB for Table でサービス レベルの操作を実行するメソッドを提供します。
  • TableClient - このクラスを使用すると、Azure Cosmos DB Table API でホストされているテーブルを操作できます。
  • TableEntity - このクラスは、プロパティや列のデータを管理できるテーブルの行への参照です。

クライアントを認証する

プロジェクト ディレクトリから、 Program.cs ファイルを開きます。 エディターで、Azure.Data.Tables の using ディレクティブを追加します。

using Azure.Data.Tables;

コンストラクターを使って TableServiceClient クラスの新しいインスタンスを定義し、Environment.GetEnvironmentVariable で前に設定した接続文字列を読み込みます。

// New instance of the TableClient class
TableServiceClient tableServiceClient = new TableServiceClient(Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING"));

テーブルを作成する

TableServiceClient クラスを使用して、TableClient のインスタンスを取得します。 TableClientTableClient.CreateIfNotExistsAsync メソッドを使用して、テーブルがまだ存在しない場合は、新しいテーブルを作成します。 このメソッドは、既存または新しく作成されたテーブルへの参照を返します。

// New instance of TableClient class referencing the server-side table
TableClient tableClient = tableServiceClient.GetTableClient(
    tableName: "adventureworks"
);

await tableClient.CreateIfNotExistsAsync();

項目を作成する

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

// C# record type for items in the table
public record Product : ITableEntity
{
    public string RowKey { get; set; } = default!;

    public string PartitionKey { get; set; } = default!;

    public string Name { get; init; } = default!;

    public int Quantity { get; init; }

    public bool Sale { get; init; }

    public ETag ETag { get; set; } = default!;

    public DateTimeOffset? Timestamp { get; set; } = default!;
}

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

// Create new item using composite key constructor
var prod1 = new Product()
{
    RowKey = "68719518388",
    PartitionKey = "gear-surf-surfboards",
    Name = "Ocean Surfboard",
    Quantity = 8,
    Sale = true
};

// Add new item to server-side table
await tableClient.AddEntityAsync<Product>(prod1);

アイテムを取得する

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

// Read a single item from container
var product = await tableClient.GetEntityAsync<Product>(
    rowKey: "68719518388",
    partitionKey: "gear-surf-surfboards"
);
Console.WriteLine("Single product:");
Console.WriteLine(product.Value.Name);

クエリ項目

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

Note

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

// Read multiple items from container
var prod2 = new Product()
{
    RowKey = "68719518390",
    PartitionKey = "gear-surf-surfboards",
    Name = "Sand Surfboard",
    Quantity = 5,
    Sale = false
};

await tableClient.AddEntityAsync<Product>(prod2);

var products = tableClient.Query<Product>(x => x.PartitionKey == "gear-surf-surfboards");

Console.WriteLine("Multiple products:");
foreach (var item in products)
{
    Console.WriteLine(item.Name);
}

コードの実行

これは、Azure Cosmos DB Table API テーブルを作成するアプリです。 次に、この例では項目を作成し、まったく同じ項目を読み取ります。 最後に、2 番目の項目を作成し、複数の項目を返すクエリを実行します。 この例では、各ステップで、実行したステップに関するメタデータをコンソールに出力します。

アプリを実行するには、ターミナルを使用してアプリケーション ディレクトリに移動し、アプリケーションを実行します。

dotnet run

アプリの出力は次の例のようになります。

Single product name: 
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard

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

Azure Cosmos DB for Table アカウントが不要になったら、対応するリソース グループを削除できます。

az group delete コマンドを使用して、リソース グループを削除します。

az group delete --name $resourceGroupName

次のステップ

このクイックスタートでは、Azure Cosmos DB for Table アカウントの作成、テーブルの作成、.NET SDK を使用したエントリの管理方法を説明しました。 Azure Cosmos DB for Table リソースでより高度なデータ クエリや管理タスクを実行する方法を学ぶために、SDK をより深く掘り下げることができます。