クイック スタート - .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)

前提条件

前提条件のチェック

  • ターミナルまたはコマンド ウィンドウで 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 つ作成します。

  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"

  2. az login コマンドを使用して Azure CLI にサインインします (まだ行っていない場合)。

  3. az group create コマンドを使用して、サブスクリプションに新しいリソース グループを作成します。

    az group create \
    --name $resourceGroupName \
    --location $location

  4. az cosmosdb create コマンドを使用して、既定の設定で新しい Azure Cosmos DB for Table アカウントを作成します。

    az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location
    --capabilities EnableTable

Table 用 API の接続文字列を取得する

  1. az cosmosdb list-connection-strings コマンドを使って、アカウントの接続文字列の一覧から Table 用 API の接続文字列を見つけます。

    az cosmosdb list-connection-strings \
    --resource-group $resourceGroupName \
    --name $accountName

  2. プライマリ テーブル接続文字列の値を記録します。 これらの資格情報は後で使用します。

新しい .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 モデルを使用する利点となります。

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 をより深く掘り下げることができます。

Azure Cosmos DB for Table と .NET を使ってみる