.NET 用 Azure Tables クライアント ライブラリ - バージョン 12.8.1

Azure Table Storage は、大量の構造化 NoSQL データをクラウドに格納し、キー/属性ストアにスキーマなしの設計を提供するサービスです。

Azure Cosmos DB には、次のような Premium 機能を必要とする Azure Table Storage 用に記述されたアプリケーション用の Table API が用意されています。

• ターンキー グローバル配信。
• 世界規模での専用スループット。
• 99 パーセンタイルで 10 ミリ秒未満の待ち時間。
• 高可用性の保証。
• 自動セカンダリ インデックス作成。

Azure Tables クライアント ライブラリは、コードを変更しない Azure Table Storage または Azure Cosmos DB table service エンドポイントをシームレスにターゲットにできます。

ソースコード | パッケージ (NuGet) | API リファレンス ドキュメント | サンプル | 変更ログ

作業の開始

パッケージをインストールする

NuGet を使用して .NET 用 Azure Tables クライアント ライブラリをインストールします。

dotnet add package Azure.Data.Tables

前提条件

• Azure サブスクリプション。
• Azure Table API が指定された既存の Azure ストレージ アカウントまたは Azure Cosmos DB データベース。

これらのいずれかを作成する必要がある場合は、 Azure CLI を使用できます。

ストレージ アカウントの作成

米国西部リージョンのサブスクリプションMySubscriptionのリソース グループMyResourceGroupにストレージ アカウントmystorageaccountを作成します。

az storage account create -n mystorageaccount -g MyResourceGroup -l westus --subscription MySubscription

Cosmos DB の作成

サブスクリプションMySubscriptionのリソース グループMyResourceGroupに Cosmos DB アカウントMyCosmosDBDatabaseAccountを作成し、そのアカウントに という名前MyTableNameのテーブルを作成します。

az cosmosdb create --name MyCosmosDBDatabaseAccount --capabilities EnableTable --resource-group MyResourceGroup --subscription MySubscription

az cosmosdb table create --name MyTableName --resource-group MyResourceGroup --account-name MyCosmosDBDatabaseAccount

クライアントの認証

認証のオプション (接続文字列、共有キー、共有キー署名、TokenCredentials など) の詳細については、サンプルを参照してください。

主要な概念

• TableServiceClient - テーブルの作成、一覧表示、削除など、Table Service レベルで対話するメソッドを提供するクライアント
• TableClient - テーブル内のエンティティの作成、クエリ、削除など、テーブル エンティティ レベルで対話するメソッドを提供するクライアント。
• Table - テーブルには、エンティティのコレクションとしてデータが格納されます。
• Entity - エンティティは行に似ています。 エンティティには、プライマリ キーと一連のプロパティがあります。 プロパティは、列に似た名前の値のペアです。

Table service の一般的な使用法を次に示します。

• Web スケール アプリケーションにサービスを提供できる数テラバイトの構造化データを格納する
• 複雑な結合、外部キー、またはストアド プロシージャを必要とせず、高速アクセスのために正規化解除できるデータセットの格納
• クラスター化インデックスを使用して高速なデータのクエリを実行する
• OData プロトコルと LINQ フィルター式を使用したデータへのアクセス

スレッド セーフ

すべてのクライアント インスタンス メソッドがスレッド セーフであり、相互に独立していることを保証します (ガイドライン)。 これにより、クライアント インスタンスの再利用に関する推奨事項は、スレッド間でも常に安全になります。

その他の概念

クライアント オプション | 応答 | へのアクセス実行時間の長い操作 | エラーの | 処理診断 | あざける | クライアントの有効期間

例

• Table Service クライアントを作成する
  • Azure テーブルを作成する
  • Azure テーブルを取得する
  • Azure テーブルを削除する
• Table クライアントを作成する
  • テーブル エンティティの追加
  • テーブル エンティティのクエリ
  • テーブル エンティティを削除する

Table service クライアントを作成する

まず、 を構築する必要があります TableServiceClient。

// Construct a new "TableServiceClient using a TableSharedKeyCredential.

var serviceClient = new TableServiceClient(
    new Uri(storageUri),
    new TableSharedKeyCredential(accountName, storageAccountKey));

Azure テーブルを作成する

次に、新しいテーブルを作成できます。

// Create a new table. The TableItem class stores properties of the created table.
TableItem table = serviceClient.CreateTableIfNotExists(tableName);
Console.WriteLine($"The created table's name is {table.Name}.");

Azure テーブルを取得する

既存の Azure テーブルのセットは、OData フィルターを使用したクエリにすることができます。

// Use the <see cref="TableServiceClient"> to query the service. Passing in OData filter strings is optional.

Pageable<TableItem> queryTableResults = serviceClient.Query(filter: $"TableName eq '{tableName}'");

Console.WriteLine("The following are the names of the tables in the query results:");

// Iterate the <see cref="Pageable"> in order to access queried tables.

foreach (TableItem table in queryTableResults)
{
    Console.WriteLine(table.Name);
}

Azure テーブルを削除する

サービスから個々のテーブルを削除できます。

// Deletes the table made previously.
serviceClient.DeleteTable(tableName);

Table クライアントを作成する

テーブル エンティティを操作するには、最初に を構築する TableClient必要があります。

// Construct a new <see cref="TableClient" /> using a <see cref="TableSharedKeyCredential" />.
var tableClient = new TableClient(
    new Uri(storageUri),
    tableName,
    new TableSharedKeyCredential(accountName, storageAccountKey));

// Create the table in the service.
tableClient.Create();

テーブル エンティティの追加

テーブルに追加できるように、新しい TableEntity を定義しましょう。

// Make a dictionary entity by defining a <see cref="TableEntity">.
var tableEntity = new TableEntity(partitionKey, rowKey)
{
    { "Product", "Marker Set" },
    { "Price", 5.00 },
    { "Quantity", 21 }
};

Console.WriteLine($"{tableEntity.RowKey}: {tableEntity["Product"]} costs ${tableEntity.GetDouble("Price")}.");

を TableClient 使用して、新しいエンティティをテーブルに追加できるようになりました。

// Add the newly created entity.
tableClient.AddEntity(tableEntity);

テーブル エンティティをクエリします

既存のテーブル エンティティのセットを調べるには、OData フィルターを使用してテーブルに対してクエリを実行します。

Pageable<TableEntity> queryResultsFilter = tableClient.Query<TableEntity>(filter: $"PartitionKey eq '{partitionKey}'");

// Iterate the <see cref="Pageable"> to access all queried entities.
foreach (TableEntity qEntity in queryResultsFilter)
{
    Console.WriteLine($"{qEntity.GetString("Product")}: {qEntity.GetDouble("Price")}");
}

Console.WriteLine($"The query returned {queryResultsFilter.Count()} entities.");

LINQ スタイルのクエリ式を使用する場合は、その構文を使用してテーブルにクエリを実行することもできます。 この構文を示すには、次のような厳密に型指定されたモデルが必要です。

// Define a strongly typed entity by implementing the ITableEntity interface.
public class OfficeSupplyEntity : ITableEntity
{
    public string Product { get; set; }
    public double Price { get; set; }
    public int Quantity { get; set; }
    public string PartitionKey { get; set; }
    public string RowKey { get; set; }
    public DateTimeOffset? Timestamp { get; set; }
    public ETag ETag { get; set; }
}

このモデル クラス定義を使用すると、クエリを記述する方法を次に示します。

double priceCutOff = 6.00;
Pageable<OfficeSupplyEntity> queryResultsLINQ = tableClient.Query<OfficeSupplyEntity>(ent => ent.Price >= priceCutOff);

テーブル エンティティを削除する

新しいテーブル エンティティが不要になった場合は、削除できます。

// Delete the entity given the partition and row key.
tableClient.DeleteEntity(partitionKey, rowKey);

トラブルシューティング

Azure テーブル ライブラリを使用する場合、サービスによって返されるエラーは、 REST API 要求に対して返されるのと同じ HTTP 状態コードを使用して報告されます。

たとえば、既に存在するテーブルを作成しようとすると、 409 "競合" を示すエラーが返されます。

// Construct a new TableClient using a connection string.

var client = new TableClient(
    connectionString,
    tableName);

// Create the table if it doesn't already exist.

client.CreateIfNotExists();

// Now attempt to create the same table unconditionally.

try
{
    client.Create();
}
catch (RequestFailedException ex) when (ex.Status == (int)HttpStatusCode.Conflict)
{
    Console.WriteLine(ex.ToString());
}

コンソール ログの設定

ログを表示する最も簡単な方法は、コンソール ログを有効にすることです。 コンソールにメッセージを出力する Azure SDK ログ リスナーを作成するには、AzureEventSourceListener.CreateConsoleLogger メソッドを使用します。

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

その他のログメカニズムの詳細については、 こちらを参照してください。

次のステップ

Table サンプルの使用を開始します。

の既知の問題

Cosmos DB テーブル エンドポイントに関連する現在既知の問題の一覧 については、こちらを参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、「 cla.microsoft.com」を参照してください。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。