你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 Java 的 Azure 表客户端库 - 版本 12.3.16

Azure 表是一项服务，用于在云中存储结构化 NoSQL 数据，提供具有无架构设计的密钥/属性存储。 Azure 表为开发人员提供了 Azure 云所有最佳部件的灵活性和可伸缩性。

源代码 | 包 (Maven) | API 参考文档 | 产品文档 | 样品

入门

添加包

包括 BOM 文件

请将 azure-sdk-bom 包含在项目中，以依赖于库的正式发布 (GA) 版本。 在以下代码段中，将 {bom_version_to_target} 占位符替换为版本号。 若要详细了解 BOM，请参阅 AZURE SDK BOM 自述文件。

<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>

先决条件

• Java 开发工具包 (版本 8 或更高版本的 JDK)
• Azure 订阅
• 现有的 Azure 存储帐户或 Azure Cosmos DB 表 API 帐户

创建存储帐户

若要创建存储帐户，可以使用 Azure 门户 或 Azure CLI。

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

存储帐户 URL（随后标识为 ） <your-table-account-url>的格式如下 http(s)://<storage-account-name>.table.core.windows.net。

创建 Cosmos DB 表 API 帐户

若要创建 Cosmos DB 表 API 帐户，可以使用 Azure 门户 或 Azure CLI。

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

随后标识为 <your-table-account-url>的表 API 帐户 URL 的格式如下 http(s)://<cosmosdb-account-name>.table.cosmosdb.azure.com。

验证客户端

对表服务发出的每个请求都必须使用连接字符串、命名密钥凭据、共享访问签名或令牌凭据进行授权。 下面的示例演示了这些方法的用法。

注意：目前只有 Azure 存储 API 终结点支持通过令牌凭据进行 AAD 授权。

连接字符串

连接字符串包括应用程序在运行时使用共享密钥授权访问 Azure 表中的数据所需的身份验证信息。 有关如何将连接字符串与 TableServiceClient结合使用的示例，请参阅使用连接字符串进行身份验证。

可以从 Azure 门户获取连接字符串， (单击“门户存储帐户”边栏选项卡中的“设置”下的“访问密钥”，或者在“门户 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>

共享密钥凭据

共享密钥授权依赖于帐户访问密钥和其他参数来生成在授权标头中的请求上传递的加密签名字符串。 有关如何将命名密钥授权与 TableServiceClient结合使用的示例，请参阅使用共享密钥凭据进行身份验证。

若要使用命名密钥授权，需要帐户名称和 URL 以及帐户访问密钥。 可以从 Azure 门户获取主访问密钥， (单击“门户存储帐户”边栏选项卡中的“设置”下的“访问密钥”，或者单击“门户 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>

共享访问签名 (SAS)

共享访问签名允许管理员委托对 Azure 表的精细访问权限，而无需直接共享访问密钥。 可以控制客户端可以访问哪些资源、对这些资源拥有哪些权限，以及 SAS 的有效时间以及其他参数。 它依赖于帐户访问密钥和其他参数来生成加密签名字符串，该字符串在查询字符串中的请求上传递。 有关如何 将共享访问签名与 结合使用的示例，请参阅使用共享访问签名 TableServiceClient (SAS) 进行身份验证。

若要使用 SAS 令牌授权，需要帐户名称和 URL 以及 SAS。 可以从 Azure 门户获取 SAS， (单击“门户存储帐户”边栏选项卡中的“设置”下的“共享访问签名”) 或使用 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 表提供与 Azure Active Directory (AAD) 的集成，以便在面向存储终结点时对表服务的请求进行基于标识的身份验证。 借助 AAD，可以使用基于角色的访问控制 (RBAC) 向用户、组或应用程序授予对 Azure 表资源的访问权限。

若要使用 TokenCredential访问表资源，经过身份验证的标识应具有“存储表数据参与者”或“存储表数据读取者”角色。

借助该 azure-identity 包，可以在开发和生产环境中无缝授权请求。 若要详细了解 Azure 存储中的 Azure AD 集成，请参阅 Azure 标识自述文件。

关键概念

• TableServiceClient - A TableServiceClient 是一个客户端对象，可用于与表服务交互，以便创建、列出和删除表。
• TableClient - A TableClient 是一个客户端对象，可用于与特定表交互，以便创建、更新、更新、获取、列出和删除其中的实体。
• 表 - 表是实体的集合。 表不对实体强制实施架构，这意味着单个表可以包含具有不同属性集的实体。
• 实体 - 实体是一组属性，类似于数据库行。 Azure 存储中的实体大小最大可以为 1MB。 Azure Cosmos DB 中的实体大小最大可以为 2MB。 实体具有分区键和行键，它们共同唯一标识表中的实体。
• 属性 - 属性是名称/值对。 每个实体最多可包含 252 个用于存储数据的属性。 每个实体还具有三个系统属性，分别指定分区键、行键和时间戳。
• 分区键 - 实体的分区键标识实体所属表中的分区。 对具有相同分区键的实体的查询速度将更快，并且可以在原子操作中插入/更新这些实体。
• 行键 - 实体的行键是其在分区中的唯一标识符。

表服务的常见用途包括：

• 存储 TB 量级的结构化数据，能够为 Web 规模应用程序提供服务
• 存储不需要复杂联接、外键或存储过程且可进行规范化以便快速访问的数据集
• 使用聚集索引快速查询数据
• 使用 OData 协议访问数据

示例

• 对客户端进行身份验证
  • 使用连接字符串进行身份验证
  • 使用共享密钥进行身份验证
  • 使用共享访问签名 (SAS) 进行身份验证
• 创建、列出和删除 Azure 表
  • 构造 TableServiceClient
  • 创建表
  • 列出表
  • 删除表
• 创建、列出和删除表实体
  • 构造 TableClient
  • 创建实体
  • 列表实体
  • 删除条目

对客户端进行身份验证

使用连接字符串进行身份验证

若要使用连接字符串授权客户端，请使用连接字符串调用生成器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();

使用共享访问签名 (SAS) 进行身份验证

若要使用 SAS 授权客户端，请使用帐户 URL 调用生成器的 endpoint 方法， sasToken 使用 SAS 调用 方法。

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();

创建表

通过调用 TableServiceClient的 createTable 方法创建表。 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());
}

删除表

通过调用 TableServiceClient的 deleteTable 方法删除表。

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 实例，提供要创建的实体的分区键和行键，并选择性地将属性添加到创建的对象。 然后将 对象传递给 TableClient的 createEntity 方法。 如果表中存在具有提供的分区键和行键的实体，将引发异常。

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"));
}

删除条目

通过调用 TableClient的 deleteEntity 方法删除实体。

tableClient.deleteEntity(partitionKey, rowKey);

疑难解答

常规

使用适用于 Java 的 Azure 表库与表服务交互时，服务返回的错误对应于为 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 。

后续步骤

表 示例入门。

贡献

本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。

此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与 联系。