Java 用 Azure Tables クライアントライブラリ - バージョン 12.3.16

[アーティクル]
10/25/2023

Azure Tables は、構造化された NoSQL データをクラウドに格納し、キー/属性ストアにスキーマレス設計を提供するサービスです。 Azure Tables を使用すると、開発者は Azure クラウドのすべての最適な部分で柔軟性とスケーラビリティを実現できます。

ソースコード | パッケージ (Maven) | API リファレンスドキュメント | 製品ドキュメント | サンプル

作業の開始

パッケージを組み込む

BOM ファイルを含める

ライブラリの一般提供 (GA) バージョンに依存するには、azure-sdk-bom をプロジェクトに含めてください。次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 BOM の詳細については、 AZURE SDK BOM README に関するページを参照してください。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

次に、次に示すように、バージョンタグを使用せずに、依存関係セクションに直接依存関係を含めます。

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-data-tables</artifactId>
    </dependency>
</dependencies>

直接依存関係を含める

BOM に存在しない特定のバージョンのライブラリに依存する場合は、次のように直接依存関係をプロジェクトに追加します。

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-data-tables</artifactId>
  <version>12.3.16</version>
</dependency>

前提条件

バージョン 8 以降の Java Development Kit (JDK)
Azure サブスクリプション
既存の Azure ストレージアカウントまたは Azure Cosmos DB Table API アカウント

ストレージアカウントを作成する

ストレージアカウントを作成するには、 Azure Portal または Azure CLI を使用できます。

az storage account create \
    --resource-group <resource-group-name> \
    --name <storage-account-name> \
    --location <location>

後でとして <your-table-account-url>識別されるストレージアカウントの URL は、次 http(s)://<storage-account-name>.table.core.windows.netのように書式設定されます。

Cosmos DB Table API アカウントを作成する

Cosmos DB Table API アカウントを作成するには、 Azure Portal または Azure CLI を使用できます。

az cosmosdb create \
    --resource-group <resource-group-name> \
    --name <cosmosdb-account-name> \
    --capabilities EnableTable

Table API アカウントの URL は、後でとして <your-table-account-url>識別され、次のように http(s)://<cosmosdb-account-name>.table.cosmosdb.azure.com書式設定されます。

クライアントを認証する

Tables サービスに対して行われるすべての要求は、接続文字列、名前付きキー資格情報、Shared Access Signature、またはトークン資格情報を使用して承認する必要があります。以下のサンプルは、これらのメソッドの使用方法を示しています。

注: 現在、トークン資格情報を使用した AAD 承認をサポートしているのは、Azure Storage API エンドポイントのみです。

接続文字列

接続文字列には、アプリケーションが共有キー承認を使用して実行時に Azure テーブル内のデータにアクセスするために必要な認証情報が含まれています。で接続文字列TableServiceClientを使用する方法の例については、「接続文字列を使用して認証する」を参照してください。

azure portal から接続文字列を取得するか ([ポータルストレージアカウント] ブレードの [設定] の [アクセスキー] をクリックするか、[ポータル Cosmos DB アカウント] ブレードの [設定] の [接続文字列] をクリックします)、または Azure CLI を使用します。

# Storage account
az storage account show-connection-string \
    --resource-group <resource-group-name> \
    --name <storage-account-name>

# Cosmos DB Table API account
az cosmosdb list-connection-strings \
    --resource-group <resource-group-name> \
    --name <cosmosdb-account-name>

共有キーの資格情報

共有キー認証では、アカウントのアクセスキーと他のパラメーターを使用して、要求の Authorization ヘッダーで渡される暗号化された署名文字列が生成されます。で名前付きキー承認を使用する方法の例については、「共有キー資格情報を TableServiceClient使用して認証する」を参照してください。

名前付きキーの承認を使用するには、アカウント名と URL、およびアカウントアクセスキーが必要です。プライマリアクセスキーは、Azure Portal から取得するか ([ポータルストレージアカウント] ブレードの [設定] の [アクセスキー] をクリックするか、[ポータル Cosmos DB アカウント] ブレードの [設定] の [接続文字列] をクリックします)、または Azure CLI を使用して取得できます。

# Storage account
az storage account keys list \
    --resource-group <resource-group-name> \
    --account-name <storage-account-name>

# Cosmos DB Table API account
az cosmosdb list-keys \
    --resource-group <resource-group-name> \
    --name <cosmosdb-account-name>

Shared Access Signature (SAS)

Shared Access Signature を使用すると、管理者はアクセスキーを直接共有することなく、詳細なアクセス権を Azure テーブルに委任できます。クライアントがアクセスできるリソース、それらのリソースに対するアクセス許可、SAS が有効な期間などを制御できます。クエリ文字列内の要求で渡される暗号化された署名文字列を生成するには、アカウントアクセスキーとその他のパラメーターに依存します。で共有アクセス署名を使用する方法の例については、「Shared Access Signature (SAS) を使用して認証するTableServiceClient」を参照してください。

SAS トークン承認を使用するには、アカウント名と URL と SAS が必要です。 SAS は、Azure Portal から取得するか ([ポータルストレージアカウント] ブレードの [設定] で [共有アクセス署名] をクリックします)、または Azure CLI を使用して取得できます。

# Account-level SAS
az storage account generate-sas \
    --account-name <storage-or-cosmosdb-account-name> \
    --services t \
    --resource-types <resource-types> \
    --permissions <permissions> \
    --expiry <expiry-date>

# Table-level SAS
az storage table generate-sas \
    --name <table-name>

TokenCredential

Azure Tables は、ストレージエンドポイントをターゲットとする場合に Table サービスへの要求を ID ベースで認証するために、Azure Active Directory (AAD) との統合を提供します。 AAD を使用すると、ロールベースのアクセス制御 (RBAC) を使用して、Azure Table リソースへのアクセスをユーザー、グループ、またはアプリケーションに付与できます。

を使用して TokenCredentialテーブルリソースにアクセスするには、認証された ID に "ストレージテーブルデータ共同作成者" または "ストレージテーブルデータ閲覧者" ロールが必要です。

パッケージを azure-identity 使用すると、開発環境と運用環境の両方で要求をシームレスに承認できます。 Azure Storage での Azure AD 統合の詳細については、 Azure Identity README に関するページを参照してください。

主要な概念

TableServiceClient - テーブル TableServiceClient を作成、一覧表示、および削除するために Table Service と対話できるクライアントオブジェクトです。
TableClient - A TableClient は、特定のテーブルを操作して、その中のエンティティを作成、アップサート、更新、取得、一覧表示、削除できるようにするクライアントオブジェクトです。
テーブル - テーブルはエンティティのコレクションです。テーブルではエンティティにスキーマを設定しないため、1 つのテーブルに異なるプロパティのセットを持つエンティティが含まれている場合があります。
エンティティ - エンティティは、データベース行に似たプロパティのセットです。 Azure Storage 内のエンティティには、最大 1 MB のサイズを指定できます。 Azure Cosmos DB 内のエンティティには、最大 2 MB のサイズを指定できます。エンティティには、テーブル内のエンティティを一意に識別するパーティションキーと行キーがあります。
プロパティ - プロパティは名前と値のペアです。それぞれのエンティティは、データを格納するために最大で 252 個のプロパティを含むことができます。さらに、それぞれのエンティティは、パーティションキー、行キー、およびタイムスタンプを指定する、3 つのシステムプロパティを持ちます。
パーティションキー - エンティティのパーティションキーは、エンティティが属するテーブル内のパーティションを識別します。同じパーティションキーを持つエンティティは、アトミック操作でより迅速な照会と挿入/更新が可能です。
行キー - エンティティの行キーは、パーティション内の一意の識別子です。

Tables サービスの一般的な用途は次のとおりです。

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

クライアントを認証する

接続文字列で認証する

接続文字列を使用してクライアントを承認するには、接続文字列でビルダーの connectionString メソッドを呼び出します。

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

共有キーを使用した認証

共有キーを使用してクライアントを承認するには、アカウント名とアクセスキーを使用しての AzureNamedKeyCredential インスタンスを作成します。アカウント URL を使用してビルダーの endpoint メソッドを呼び出し、作成した credential オブジェクトでメソッドを AzureNamedKeyCredential 呼び出します。

AzureNamedKeyCredential credential = new AzureNamedKeyCredential("<your-account-name>", "<account-access-key>");
TableServiceClient tableServiceClient = new TableServiceClientBuilder()
    .endpoint("<your-table-account-url>")
    .credential(credential)
    .buildClient();

Shared Access Signature (SAS) を使用した認証

SAS を使用してクライアントを承認するには、アカウント URL を使用してビルダーの endpoint メソッドを呼び出し、SAS で sasToken メソッドを呼び出します。

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

トークン資格情報を使用した認証

AAD を使用してクライアントを承認するには、を実装する資格情報クラスのインスタンスを作成します TokenCredential。アカウント URL を使用してビルダーの endpoint メソッドを呼び出し、作成した credential オブジェクトでメソッドを TokenCredential 呼び出します。

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

Azure テーブルの作成、一覧表示、削除

`TableServiceClient` を構築します

の TableServiceClient インスタンス TableServiceClientBuilder を作成し、ビルダー buildClient または buildAsyncClient メソッドを呼び出してを構築します。

TableServiceClient tableServiceClient = new TableServiceClientBuilder()
    .connectionString("<your-connection-string>") // or use any of the other authentication methods
    .buildClient();

テーブルを作成する

のメソッドを呼び出してテーブルをTableServiceClientcreateTable作成します。 TableClientが返されます。このクライアントでは、テーブルに対する操作を実行できます。指定された名前のテーブルが存在する場合は、例外がスローされます。

TableClient tableClient = tableServiceClient.createTable(tableName);

または、メソッドを createTableIfNotExists 呼び出すことができます。このメソッドは、そのようなテーブルが存在せず、例外がスローされない場合にのみテーブルを作成します。 TableClientも返されます。

TableClient tableClient = tableServiceClient.createTableIfNotExists(tableName);

テーブルをリストする

のメソッドを呼び出して既存のテーブルのセットをTableServiceClientlistTables一覧表示またはクエリします。必要に応じて、インスタンスをListTablesOptions渡してクエリ結果をフィルター処理または制限します。サポートされているクエリオプションの詳細については、「サポートされているクエリオプション」を参照してください。

ListTablesOptions options = new ListTablesOptions()
    .setFilter(String.format("TableName eq '%s'", tableName));

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

テーブルを削除する

のメソッドを呼び出してテーブルをTableServiceClientdeleteTable削除します。

tableServiceClient.deleteTable(tableName);

テーブルエンティティの作成、一覧表示、および削除

`TableClient` を構築します

TableClientのインスタンスを作成し、テーブルのTableClientBuilder名前を使用してビルダーのtableNameメソッドを呼び出し、そのbuildClientメソッドまたは buildAsyncClient メソッドを呼び出してを構築します。

TableClient tableClient = new TableClientBuilder()
    .connectionString("<your-connection-string>") // or use any of the other authentication methods
    .tableName(tableName)
    .buildClient();

または、メソッドをTableClient呼び出getTableClientして既存TableServiceClientのからを取得することもできます。

TableClient tableClient = tableServiceClient.getTableClient(tableName);

エンティティの作成

新 TableEntity しいインスタンスを作成し、作成するエンティティのパーティションキーと行キーを指定し、必要に応じて作成されたオブジェクトにプロパティを追加します。次に、オブジェクトをの createEntity メソッドにTableClient渡します。指定されたパーティションキーと行キーを持つエンティティがテーブル内に存在する場合、例外がスローされます。

TableEntity entity = new TableEntity(partitionKey, rowKey)
    .addProperty("Product", "Marker Set")
    .addProperty("Price", 5.00)
    .addProperty("Quantity", 21);

tableClient.createEntity(entity);

エンティティの一覧表示

のメソッドを呼び出TableClientlistEntitiesしてテーブル内のエンティティのセットを一覧表示またはクエリします。必要に応じて、インスタンスをListEntitiesOptions渡してクエリ結果をフィルター処理、選択、または制限します。サポートされているクエリオプションの詳細については、「サポートされているクエリオプション」を参照してください。

List<String> propertiesToSelect = new ArrayList<>();
propertiesToSelect.add("Product");
propertiesToSelect.add("Price");

ListEntitiesOptions options = new ListEntitiesOptions()
    .setFilter(String.format("PartitionKey eq '%s'", partitionKey))
    .setSelect(propertiesToSelect);

for (TableEntity entity : tableClient.listEntities(options, null, null)) {
    Map<String, Object> properties = entity.getProperties();
    System.out.printf("%s: %.2f%n", properties.get("Product"), properties.get("Price"));
}

エンティティを削除する

の deleteEntity メソッドを呼び出してエンティティをTableClient削除します。

tableClient.deleteEntity(partitionKey, rowKey);

トラブルシューティング

全般

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

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

// Create the table if it doesn't already exist.
tableServiceClient.createTableIfNotExists(tableName);

// Now attempt to create the same table unconditionally.
try {
    tableServiceClient.createTable(tableName);
} catch (TableServiceException e) {
    System.out.println(e.getResponse().getStatusCode()); // 409
}

ログの記録

ログの記録を有効にすると、エラーに関する有用な情報を明らかにするのに役立つ場合があります。 HTTP 要求と応答のログを表示するには、環境変数を AZURE_LOG_LEVEL 目的の詳細度に設定します。使用可能なログレベルの説明については、「 LogLevel 」を参照してください。

次の手順

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

共同作成

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

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

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

インプレッション数

次の方法で共有

Java 用 Azure Tables クライアントライブラリ - バージョン 12.3.16

作業の開始

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

前提条件

ストレージアカウントを作成する

Cosmos DB Table API アカウントを作成する

クライアントを認証する

接続文字列

共有キーの資格情報

Shared Access Signature (SAS)

TokenCredential

主要な概念

例

クライアントを認証する

接続文字列で認証する

共有キーを使用した認証

Shared Access Signature (SAS) を使用した認証

トークン資格情報を使用した認証

Azure テーブルの作成、一覧表示、削除

`TableServiceClient` を構築します

テーブルを作成する

テーブルをリストする

テーブルを削除する

テーブルエンティティの作成、一覧表示、および削除

`TableClient` を構築します

エンティティの作成

エンティティの一覧表示

エンティティを削除する

トラブルシューティング

全般

ログの記録

次の手順

共同作成

フィードバック

その他のリソース

次の方法で共有

Java 用 Azure Tables クライアント ライブラリ - バージョン 12.3.16

作業の開始

パッケージを組み込む

BOM ファイルを含める

直接依存関係を含める

前提条件

ストレージ アカウントを作成する

Cosmos DB Table API アカウントを作成する

クライアントを認証する

接続文字列

共有キーの資格情報

Shared Access Signature (SAS)

TokenCredential

主要な概念

例

クライアントを認証する

接続文字列で認証する

共有キーを使用した認証

Shared Access Signature (SAS) を使用した認証

トークン資格情報を使用した認証

Azure テーブルの作成、一覧表示、削除

TableServiceClient を構築します

テーブルを作成する

テーブルをリストする

テーブルを削除する

テーブル エンティティの作成、一覧表示、および削除

TableClient を構築します

エンティティの作成

エンティティの一覧表示

エンティティを削除する

トラブルシューティング

全般

ログの記録

次の手順

共同作成

フィードバック

その他のリソース

Java 用 Azure Tables クライアントライブラリ - バージョン 12.3.16

ストレージアカウントを作成する

`TableServiceClient` を構築します

テーブルエンティティの作成、一覧表示、および削除

`TableClient` を構築します