クイック スタート - .NET 用 Azure Cosmos DB for Table
適用対象: Table
このクイック スタートでは、.NET アプリケーションから Azure Cosmos DB for Table を使用する方法について説明します。 Azure Cosmos DB for Table はスキーマレス データ ストアであり、これによりアプリケーションは構造化された NoSQL データをクラウドに格納できます。 Azure.Data.Tables パッケージ (NuGet) を使用して、Azure Cosmos DB リソース内でテーブル、行を作成し、基本的なタスクを実行する方法について説明します。
注意
コード スニペットの例は、.NET プロジェクトとしてGitHub 上で使用できます。
Table リファレンス ドキュメント用 API | Azure.Data.Tables パッケージ (NuGet)
前提条件
- アクティブなサブスクリプションが含まれる Azure アカウント。 無料でアカウントを作成できます。
- .NET 6.0
- Azure コマンド ライン インターフェイス (CLI) または Azure PowerShell
前提条件のチェック
- ターミナルまたはコマンド ウィンドウで
dotnet --list-sdks
を実行して、.NET 6.x が使用可能なバージョンのいずれかであることを確認します。 az --version
(Azure CLI) またはGet-Module -ListAvailable AzureRM
(Azure PowerShell) を実行して、適切な Azure コマンド ライン ツールがインストールされていることを確認します。
設定
このセクションでは、Azure Cosmos DB アカウントを作成し、Table NuGet パッケージ用 API を使用するプロジェクトを設定する方法について説明します。
Azure Cosmos DB アカウントを作成する
このクイック スタートでは、Table 用 API を使用して Azure Cosmos DB アカウントを 1 つ作成します。
accountName、resourceGroupName、および location のシェル変数を作成します。
# Variable for resource group name resourceGroupName="msdocs-cosmos-quickstart-rg" location="westus" # Variable for account name with a randomnly generated suffix let suffix=$RANDOM*$RANDOM accountName="msdocs-$suffix"
az login
コマンドを使用して Azure CLI にサインインします (まだ行っていない場合)。az group create
コマンドを使用して、サブスクリプションに新しいリソース グループを作成します。az group create \ --name $resourceGroupName \ --location $location
az cosmosdb create
コマンドを使用して、既定の設定で新しい Azure Cosmos DB for Table アカウントを作成します。az cosmosdb create \ --resource-group $resourceGroupName \ --name $accountName \ --locations regionName=$location --capabilities EnableTable
Table 用 API の接続文字列を取得する
az cosmosdb list-connection-strings
コマンドを使って、アカウントの接続文字列の一覧から Table 用 API の接続文字列を見つけます。az cosmosdb list-connection-strings \ --resource-group $resourceGroupName \ --name $accountName
プライマリ テーブル接続文字列の値を記録します。 これらの資格情報は後で使用します。
新しい .NET アプリを作成する
任意のターミナルを使用して、空のフォルダーに新しい .NET アプリケーションを作成します。 dotnet new console
を使用して新しいコンソール アプリを作成します。
dotnet new console --output <app-name>
NuGet パッケージのインストール
Azure.Data.Tables NuGet パッケージを新しい .NET プロジェクトに追加します。 NuGet パッケージの名前を指定する dotnet add package
コマンドを使用します。
dotnet add package Azure.Data.Tables
環境変数を構成する
コード内で接続文字列の値を使うには、アプリケーションを実行しているローカル コンピューターでこの値を設定します。 環境変数を設定するには、任意のターミナルを使用して次のコマンドを実行します。
$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"
コード例
このアーティクルで説明されているサンプル コードでは、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
のインスタンスを取得します。 TableClient
の TableClient.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>
メソッドを使用して、テーブルから特定の項目を取得できます。 partitionKey
と rowKey
をパラメーターに指定し、正しい行を特定してその項目のクイック ポイント リードを実行できます。
// 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
モデルを使用する利点となります。
// 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 をより深く掘り下げることができます。