azure-data-tables-java

Azure Tables SDK for Java

Azure Tables SDK for Java を使用して、テーブルストレージアプリケーションを構築できます。Azure Table Storage と Cosmos DB Table API の両方に対応しています。

インストール

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-data-tables</artifactId>
  <version>12.6.0-beta.1</version>
</dependency>

クライアントの作成

接続文字列を使用する場合

import com.azure.data.tables.TableServiceClient;
import com.azure.data.tables.TableServiceClientBuilder;
import com.azure.data.tables.TableClient;

TableServiceClient serviceClient = new TableServiceClientBuilder()
    .connectionString("<your-connection-string>")
    .buildClient();

共有キーを使用する場合

import com.azure.core.credential.AzureNamedKeyCredential;

AzureNamedKeyCredential credential = new AzureNamedKeyCredential(
    "<account-name>",
    "<account-key>");

TableServiceClient serviceClient = new TableServiceClientBuilder()
    .endpoint("<your-table-account-url>")
    .credential(credential)
    .buildClient();

SAS トークンを使用する場合

TableServiceClient serviceClient = new TableServiceClientBuilder()
    .endpoint("<your-table-account-url>")
    .sasToken("<sas-token>")
    .buildClient();

DefaultAzureCredential を使用する場合（Storage のみ）

import com.azure.identity.DefaultAzureCredentialBuilder;

TableServiceClient serviceClient = new TableServiceClientBuilder()
    .endpoint("<your-table-account-url>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

主な概念

• TableServiceClient：テーブルの管理（作成、一覧表示、削除）
• TableClient：テーブル内のエンティティの管理（CRUD）
• Partition Key：効率的なクエリのためにエンティティをグループ化します
• Row Key：パーティション内での一意な識別子です
• Entity：最大252個のプロパティを持つ行（Storageでは1MB、Cosmosでは2MB）

基本的なパターン

例ではプレースホルダーの認証情報を使用しています。互換性のあるリリース済みの SDK バージョンを選択してください。上記のベータ版は過去のものです。接続文字列や SAS はシークレットストアに保管してください。書き込みを行う前に、アカウント、テーブル、および削除範囲を確認してください。マージ、置換、アップサートの例では ETag による同時実行チェックを示していません。同時に書き込むクライアントが存在する場合は、条件付き更新を使用してください。

テーブルの作成

// Create table (throws if exists)
TableClient tableClient = serviceClient.createTable("mytable");

// Create if not exists (no exception)
TableClient tableClient = serviceClient.createTableIfNotExists("mytable");

テーブルクライアントの取得

// From service client
TableClient tableClient = serviceClient.getTableClient("mytable");

// Direct construction
TableClient tableClient = new TableClientBuilder()
    .connectionString("<connection-string>")
    .tableName("mytable")
    .buildClient();

エンティティの作成

import com.azure.data.tables.models.TableEntity;

TableEntity entity = new TableEntity("partitionKey", "rowKey")
    .addProperty("Name", "Product A")
    .addProperty("Price", 29.99)
    .addProperty("Quantity", 100)
    .addProperty("IsAvailable", true);

tableClient.createEntity(entity);

エンティティの取得

TableEntity entity = tableClient.getEntity("partitionKey", "rowKey");

String name = (String) entity.getProperty("Name");
Double price = (Double) entity.getProperty("Price");
System.out.printf("Product: %s, Price: %.2f%n", name, price);

エンティティの更新

import com.azure.data.tables.models.TableEntityUpdateMode;

// Merge (update only specified properties)
TableEntity updateEntity = new TableEntity("partitionKey", "rowKey")
    .addProperty("Price", 24.99);
tableClient.updateEntity(updateEntity, TableEntityUpdateMode.MERGE);

// Replace (replace entire entity)
TableEntity replaceEntity = new TableEntity("partitionKey", "rowKey")
    .addProperty("Name", "Product A Updated")
    .addProperty("Price", 24.99)
    .addProperty("Quantity", 150);
tableClient.updateEntity(replaceEntity, TableEntityUpdateMode.REPLACE);

エンティティのアップサート

// Insert or update (merge mode)
tableClient.upsertEntity(entity, TableEntityUpdateMode.MERGE);

// Insert or replace
tableClient.upsertEntity(entity, TableEntityUpdateMode.REPLACE);

エンティティの削除

tableClient.deleteEntity("partitionKey", "rowKey");

エンティティの一覧表示

import com.azure.data.tables.models.ListEntitiesOptions;

// List all entities
for (TableEntity entity : tableClient.listEntities()) {
    System.out.printf("%s - %s%n",
        entity.getPartitionKey(),
        entity.getRowKey());
}

// With filtering and selection
ListEntitiesOptions options = new ListEntitiesOptions()
    .setFilter("PartitionKey eq 'sales'")
    .setSelect(java.util.Arrays.asList("Name", "Price"));

for (TableEntity entity : tableClient.listEntities(options, null, null)) {
    System.out.printf("%s: %.2f%n",
        entity.getProperty("Name"),
        entity.getProperty("Price"));
}

OData フィルターによるクエリ

// Filter by partition key
ListEntitiesOptions options = new ListEntitiesOptions()
    .setFilter("PartitionKey eq 'electronics'");

// Filter with multiple conditions
options.setFilter("PartitionKey eq 'electronics' and Price gt 100");

// Filter with comparison operators
options.setFilter("Quantity ge 10 and Quantity le 100");

// Request page size; stop iteration explicitly if only ten total results are wanted
options.setTop(10);

for (TableEntity entity : tableClient.listEntities(options, null, null)) {
    System.out.println(entity.getRowKey());
}

バッチ操作（トランザクション）

import com.azure.data.tables.models.TableTransactionAction;
import com.azure.data.tables.models.TableTransactionActionType;
import java.util.Arrays;

// All entities must have same partition key
List<TableTransactionAction> actions = Arrays.asList(
    new TableTransactionAction(
        TableTransactionActionType.CREATE,
        new TableEntity("batch", "row1").addProperty("Name", "Item 1")),
    new TableTransactionAction(
        TableTransactionActionType.CREATE,
        new TableEntity("batch", "row2").addProperty("Name", "Item 2")),
    new TableTransactionAction(
        TableTransactionActionType.UPSERT_MERGE,
        new TableEntity("batch", "row3").addProperty("Name", "Item 3"))
);

tableClient.submitTransaction(actions);

テーブルの一覧表示

import com.azure.data.tables.models.TableItem;
import com.azure.data.tables.models.ListTablesOptions;

// List all tables
for (TableItem table : serviceClient.listTables()) {
    System.out.println(table.getName());
}

// Filter tables
ListTablesOptions options = new ListTablesOptions()
    .setFilter("TableName eq 'mytable'");

for (TableItem table : serviceClient.listTables(options, null, null)) {
    System.out.println(table.getName());
}

テーブルの削除

serviceClient.deleteTable("mytable");

型付きエンティティ

TableEntity は具象 SDK クラスであり、POJO が実装するためのインターフェイスではありません。ドメイン値は明示的にマッピングしてください。

TableEntity product = new TableEntity("electronics", "laptop-001")
    .addProperty("Name", "Laptop")
    .addProperty("Price", 999.99);
tableClient.createEntity(product);

エラー処理

import com.azure.data.tables.models.TableServiceException;

try {
    tableClient.createEntity(entity);
} catch (TableServiceException e) {
    System.out.println("Status: " + e.getResponse().getStatusCode());
    System.out.println("Error: " + e.getMessage());
    // 409 = Conflict (entity exists)
    // 404 = Not Found
}

環境変数

# Storage Account
AZURE_TABLES_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
AZURE_TABLES_ENDPOINT=https://<account>.table.core.windows.net

# Cosmos DB Table API
COSMOS_TABLE_ENDPOINT=https://<account>.table.cosmosdb.azure.com

ベストプラクティス

1. Partition Key の設計：負荷が均等に分散されるキーを選択します
2. バッチ操作：複数エンティティをアトミックに更新するには、トランザクションを使用します
3. クエリの最適化：可能な場合は、常に PartitionKey でフィルターします
4. 選択するプロジェクション：パフォーマンス向上のため、必要なプロパティのみを選択します
5. エンティティサイズ：エンティティのサイズを1MB（Storage）または2MB（Cosmos）未満に保ちます

トリガーフレーズ

• 「Azure Tables Java」
• 「table storage SDK」
• 「Cosmos DB Table API」
• 「NoSQL キー値ストレージ」
• 「partition key row key」
• 「table entity CRUD」

使用する場面

このスキルは、概要で説明されているワークフローやアクションを実行する場合に適用できます。

制限事項

• このスキルは、タスクが上記のスコープに明確に合致する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中止して確認を求めてください。