Azure Tables客户端库（Python版）

Azure Tables是一种NoSQL数据存储服务，可以通过HTTP或HTTPS进行认证调用，从世界任何地方访问。表的大小会根据需要扩展，以支持插入的数据量，并允许存储具有非复杂访问的数据。Azure Tables客户端可用于访问Azure Storage或Cosmos账户。本文档涵盖azure-data-tables。

请注意，此包是azure-cosmosdb-tables的替代品，该包现在已弃用。有关详细信息，请参阅迁移指南。

源代码 | 包（PyPI） | 包（Conda） | API参考文档 | 示例

入门指南

Azure Tables SDK 可以访问Azure存储或CosmosDB账户。

先决条件

• 使用此包需要Python 3.8或更高版本。
• 您必须拥有一个Azure订阅，并拥有以下之一：
  • Azure存储账户或
  • Azure Cosmos账户。

创建账户

• 要创建新的存储账户，您可以使用Azure门户、Azure PowerShell或Azure CLI。
• 要创建新的Cosmos存储账户，您可以使用Azure CLI或Azure门户。

安装包

使用pip安装Azure Tables客户端库。

pip install azure-data-tables

创建客户端

Azure Tables库允许您与两种类型的资源进行交互

• 您账户中的表
• 这些表中的实体。与这些资源的交互从客户端实例开始。要创建客户端对象，您需要账户的表服务端点URL和允许您访问账户的凭据。可以在您的存储账户页面上的Azure门户"访问密钥"部分找到endpoint，或者通过运行以下Azure CLI命令找到

# Get the table service URL for the account
az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table"

一旦您有了账户URL，就可以用它来创建服务客户端

from azure.data.tables import TableServiceClient
service = TableServiceClient(endpoint="https://<my_account_name>.table.core.windows.net/", credential=credential)

有关表服务URL的更多信息以及如何为Azure存储配置自定义域名，请参阅官方文档

凭证类型

根据您希望使用的授权类型，credential参数可以以多种形式提供。Tables库支持以下授权方式

• 共享密钥
• 连接字符串
• 共享访问签名令牌
• TokenCredential(AAD)(支持存储)

从共享密钥创建客户端

要使用账户共享密钥（即账户密钥或访问密钥），请提供作为字符串的密钥。您可以在存储账户的Azure门户"访问密钥"部分找到此密钥，或者通过运行以下Azure CLI命令找到

az storage account keys list -g MyResourceGroup -n MyStorageAccount

将密钥用作凭据参数以验证客户端

from azure.data.tables import TableServiceClient
from azure.core.credentials import AzureNamedKeyCredential

credential = AzureNamedKeyCredential("my_account_name", "my_access_key")
with TableServiceClient(
    endpoint="https://<my_account_name>.table.core.windows.net", credential=credential
) as table_service_client:
    properties = table_service_client.get_service_properties()
    print(f"{properties}")

从连接字符串创建客户端

根据您的用例和授权方法，您可能更喜欢使用连接字符串而不是分别提供账户URL和凭据来初始化客户端实例。为此，请将连接字符串传递给客户端的from_connection_string类方法。如果连接字符串没有指定完全限定的端点URL（"TableEndpoint"）或URL后缀（"EndpointSuffix"），则假定端点为Azure存储账户，并自动格式化相应的URL。

对于表存储，连接字符串可以在您的存储账户中的Azure门户“访问密钥”部分找到，或者使用以下Azure CLI命令

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

对于表Cosmos，连接字符串可以在您的Cosmos账户中的Azure门户“连接字符串”部分找到，或者使用以下Azure CLI命令

az cosmosdb list-connection-strings -g MyResourceGroup -n MyCosmosAccount

从连接字符串创建客户端

from azure.data.tables import TableServiceClient

connection_string = "AccountName=<my_account_name>;AccountKey=<my_account_key>;EndpointSuffix=<endpoint_suffix>"
with TableServiceClient.from_connection_string(conn_str=connection_string) as table_service_client:
    properties = table_service_client.get_service_properties()
    print(f"{properties}")

从SAS令牌创建客户端

要使用共享访问签名（SAS）令牌，将令牌作为字符串提供。如果您的账户URL包含SAS令牌，则省略凭证参数。您可以从Azure门户中的共享访问签名生成SAS令牌或使用generate_*_sas()函数之一为账户或表创建SAS令牌

from datetime import datetime, timedelta
from azure.data.tables import TableServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions
from azure.core.credentials import AzureNamedKeyCredential, AzureSasCredential

credential = AzureNamedKeyCredential("my_account_name", "my_access_key")
# Create a SAS token to use for authentication of a client
sas_token = generate_account_sas(
    credential,
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1),
)

with TableServiceClient(
    endpoint="https://<my_account_name>.table.core.windows.net", credential=AzureSasCredential(sas_token)
) as table_service_client:
    properties = table_service_client.get_service_properties()
    print(f"{properties}")

从TokenCredential创建客户端

Azure表提供了与Azure Active Directory（Azure AD）的集成，用于在针对存储端点时对表服务的请求进行基于身份的认证。使用Azure AD，您可以使用基于角色的访问控制（RBAC）来授予对您的Azure表资源的用户、组或应用程序的访问权限。

要使用TokenCredential访问表资源，认证的标识应具有“存储表数据贡献者”或“存储表数据读取器”角色。

使用azure-identity包，您可以在开发和生产环境中无缝授权请求。有关Azure存储中Azure AD集成的更多信息，请参阅azure-identity README

from azure.data.tables import TableServiceClient
from azure.identity import DefaultAzureCredential

with TableServiceClient(
    endpoint="https://<my_account_name>.table.core.windows.net", credential=DefaultAzureCredential()
) as table_service_client:
    properties = table_service_client.get_service_properties()
    print(f"{properties}")

关键概念

表服务的一些常见用途包括

• 存储TB级的结构化数据，能够服务于Web规模的应用程序
• 存储不需要复杂连接、外键或存储过程的集合数据，并且可以取消规范化以提高访问速度
• 使用聚集索引快速查询数据
• 使用OData协议和LINQ过滤器表达式访问数据

以下组件构成了Azure表服务

• 账户
• 账户内的一个表，其中包含一组实体
• 表内的一个实体，作为字典

Azure表Python客户端库允许您通过使用专用客户端对象与这些组件交互。

客户端

提供了两个不同的客户端来与表服务各组件交互

1. TableServiceClient -
   • 获取和设置账户设置
   • 查询、创建和删除账户内的表。
   • 使用get_table_client方法获取一个TableClient以使用特定的表。
2. TableClient -
   • 与特定的表（可能尚不存在）交互。
   • 在指定的表中创建、删除、查询和更新实体。
   • 创建或删除指定的表本身。

实体

实体类似于行。实体具有一个PartitionKey、一个RowKey和一组属性。属性是一个名称值对，类似于列。表中每个实体不需要具有相同的属性。实体可以像这样表示为字典示例

entity = {
    'PartitionKey': 'color',
    'RowKey': 'brand',
    'text': 'Marker',
    'color': 'Purple',
    'price': '5'
}

• create_entity - 向表中添加实体。
• delete_entity - 从表中删除实体。
• update_entity - 通过合并或替换现有实体来更新实体的信息。
  • UpdateMode.MERGE 将向现有实体添加新属性，而不会删除现有属性
  • UpdateMode.REPLACE 将用提供的实体替换现有实体，删除未包含在提交实体中的任何现有属性
• 查询实体 - 使用 OData 滤波器 在表中查询现有实体。
• 获取实体 - 通过分区和行键从表中获取特定实体。
• 插入或更新实体 - 在表中合并或替换实体，或者如果实体不存在，则插入实体。
  • UpdateMode.MERGE 将向现有实体添加新属性，而不会删除现有属性
  • UpdateMode.REPLACE 将用提供的实体替换现有实体，删除未包含在提交实体中的任何现有属性

示例

以下部分提供了几个代码片段，涵盖了最常见的表任务，包括

• 创建表
• 创建实体
• 查询实体

创建表

在您的帐户中创建一个表，并获取一个 TableClient 来对新建的表执行操作

from azure.data.tables import TableServiceClient
table_service_client = TableServiceClient.from_connection_string(conn_str="<connection_string>")
table_name = "myTable"
table_client = table_service_client.create_table(table_name=table_name)

创建实体

在表中创建实体

from azure.data.tables import TableServiceClient
from datetime import datetime

PRODUCT_ID = u'001234'
PRODUCT_NAME = u'RedMarker'

my_entity = {
    u'PartitionKey': PRODUCT_NAME,
    u'RowKey': PRODUCT_ID,
    u'Stock': 15,
    u'Price': 9.99,
    u'Comments': u"great product",
    u'OnSale': True,
    u'ReducedPrice': 7.99,
    u'PurchaseDate': datetime(1973, 10, 4),
    u'BinaryRepresentation': b'product_name'
}

table_service_client = TableServiceClient.from_connection_string(conn_str="<connection_string>")
table_client = table_service_client.get_table_client(table_name="myTable")

entity = table_client.create_entity(entity=my_entity)

查询实体

查询表中的实体

from azure.data.tables import TableClient
my_filter = "PartitionKey eq 'RedMarker'"
table_client = TableClient.from_connection_string(conn_str="<connection_string>", table_name="myTable")
entities = table_client.query_entities(my_filter)
for entity in entities:
    for key in entity.keys():
        print(f"Key: {key}, Value: {entity[key]}")

可选配置

可以在客户端和每个操作级别传递可选关键字参数。azure-core 参考文档 描述了重试、日志记录、传输协议等可用的配置。

重试策略配置

在实例化客户端时使用以下关键字参数来配置重试策略

• retry_total (int): 允许的重试总数。优先于其他计数。如果您不希望在请求上进行重试，请传递 retry_total=0。默认为 10。
• retry_connect (int): 重试连接相关错误的次数。默认为 3。
• retry_read (int): 重试读取错误的次数。默认为 3。
• retry_status (int): 重试不良状态码的次数。默认为 3。
• retry_to_secondary (bool): 如果可能，请求是否应重试到辅助节点。只有在使用 RA-GRS 帐户且可以处理可能过时的数据时才应启用此功能。默认为 False。

其他客户端/每个操作配置

可以在客户端或每个操作上指定其他可选配置关键字参数。

客户端关键字参数

• connection_timeout (int): 可选地设置连接和读取超时时间，以秒为单位。
• transport (Any): 用户提供的传输层，用于发送 HTTP 请求。

每个操作关键字参数

• raw_response_hook (callable): 给定的回调使用服务返回的响应。
• raw_request_hook (callable): 给定的回调使用在发送到服务之前请求。
• client_request_id (str): 可选的用户指定请求标识。
• user_agent (str): 将自定义值追加到请求中要发送的用户代理头。
• logging_enable (bool): 启用 DEBUG 级别的日志记录。默认为 False。也可以在客户端级别传递以在所有请求上启用它。
• headers (dict): 以键、值对的形式传递自定义头。例如：headers={'CustomValue': value}

故障排除

常规

Azure 表客户端引发在 Azure Core 中定义的异常。当您使用 Python SDK 与 Azure 表库交互时，服务返回的错误响应与 REST API 请求相同的 HTTP 状态码。表服务操作在失败时将抛出 HttpResponseError，并提供有用的 错误代码。

例如，如果您尝试创建一个已存在的表，则会返回一个 409 错误，表示 "冲突"。

from azure.data.tables import TableServiceClient
from azure.core.exceptions import HttpResponseError
table_name = 'YourTableName'

service_client = TableServiceClient.from_connection_string(connection_string)

# Create the table if it does not already exist
tc = service_client.create_table_if_not_exists(table_name)

try:
    service_client.create_table(table_name)
except HttpResponseError:
    print(f"Table with name {table_name} already exists")

日志记录

该库使用标准的logging库进行日志记录。HTTP会话（URL、头部信息等）的基本信息以INFO级别记录。

可以通过在客户端使用logging_enable参数来启用详细的DEBUG级别日志记录，包括请求/响应体和未编辑的头部信息。

import sys
import logging
from azure.data.tables import TableServiceClient
# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = TableServiceClient.from_connection_string("your_connection_string", logging_enable=True)

同样，logging_enable可以为一个单独的操作启用详细的日志记录，即使它没有为客户端启用。

service_client.create_entity(entity=my_entity, logging_enable=True)

下一步

从我们的表样例开始。

在SDK的GitHub存储库中提供了几个Azure表Python SDK样例。这些样例提供了在处理表时可能遇到的常见场景的示例代码。

常见场景

以下代码示例展示了Azure表客户端库的常见操作。异步版本的示例（以_async结尾的python样例文件）展示了异步操作。

• 创建和删除表：sample_create_delete_table.py (异步版本)
• 列出和查询表：sample_query_tables.py (异步版本)
• 插入和删除实体：sample_insert_delete_entities.py (异步版本)
• 查询和列出实体：sample_query_table.py (异步版本)
• 更新、upsert和合并实体：sample_update_upsert_merge_entities.py (异步版本)
• 在单个事务中提交多个请求：sample_batching.py (异步版本)

其他文档

有关Azure表的更多详细文档，请参阅docs.microsoft.com上的Azure Tables文档。

已知问题

有关Cosmos DB表端点的当前已知问题列表，请在此处查看。

贡献

本项目欢迎贡献和建议。大多数贡献都需要您同意一份贡献者许可协议（CLA），声明您有权并且确实授予我们使用您的贡献的权利。有关详细信息，请访问https://cla.microsoft.com。

在您提交拉取请求时，CLA机器人将自动确定您是否需要提供CLA，并相应地装饰PR（例如，标签，注释）。只需遵循机器人提供的说明即可。您只需在整个使用我们的CLA的存储库中做一次。

本项目已采用Microsoft开源行为准则。有关更多信息，请参阅行为准则FAQ或通过opencode@microsoft.com联系以获取任何额外的疑问或评论。

发布历史

12.5.0 (2024-01-10)

已修复的bug

• 修复了序列化EntityProperty元组的问题，其中None值可以序列化为字符串"None"。

其他更改

• 重构批处理代码以使用最新的Core模型并改进类型。
• 添加了一个公开类型 EntityMetadata，它在 TableEntity 的元数据中使用。
• 添加了对Python 3.12的支持。
• Python 3.7不再受支持。请使用Python版本3.8或更高版本。

12.4.4 (2023-09-14)

新增功能

• 在账户SAS访问中可以指定资源类型 container。

已修复的bug

• 修复了在提交空操作列表的事务时的错误。（#31471）
• 修复了解码字符串类型响应体时的错误。感谢 @kldtz 的贡献！（《a href="https://github.com/Azure/azure-sdk-for-python/pull/31265" rel="nofollow">#31265）
• 修复了在空字符串中检索实体时分区键和/或行键消失的错误。（《a href="https://github.com/Azure/azure-sdk-for-python/issues/31920" rel="nofollow">#31920）

其他更改

• 将 azure-core 的最低依赖性提升到 >=1.29.4。（《a href="https://github.com/Azure/azure-sdk-for-python/issues/28918" rel="nofollow">#28918 《a href="https://github.com/Azure/azure-sdk-for-python/issues/31471" rel="nofollow">#31471）

12.4.3 (2023-06-13)

已修复的bug

• 修复了在操作失败时获取错误属性值时的错误。（《a href="https://github.com/Azure/azure-sdk-for-python/issues/27410" rel="nofollow">#27410）

其他更改

• 调整对 isodate 的依赖性为 <1.0.0,>=0.6.1。

12.4.2 (2023-02-07)

已修复的bug

• 修复了删除具有分区键或行键的实体时的错误。（《a href="https://github.com/Azure/azure-sdk-for-python/issues/24480" rel="nofollow">#24480）

其他更改

• 添加了对Python 3.11的支持。
• 删除了 msrest 的需求。
• 添加了依赖 isodate，版本范围为 >=0.6.0（isodate 是由 msrest 需要的）。
• 添加了依赖 typing-extensions，版本范围为 >=4.3.0。

12.4.1 (2022-10-11)

已修复的bug

• 修复了在服务请求期间引发客户端异常的处理（例如《a href="https://github.com/Azure/azure-sdk-for-python/issues/21416" rel="nofollow">#21416）（《a href="https://github.com/Azure/azure-sdk-for-python/pull/24788" rel="nofollow">#24788）

其他更改

• Python 3.6不再受支持。请使用Python版本3.7或更高版本。
• 将 azure-core 的最低依赖性提升到 >=1.24.0。
• 将 msrest 的最低依赖性提升到 >=0.7.1。
• 添加了依赖 yarl，版本范围为 <2.0,>=1.0。

12.4.0 (2022-05-10)

新增功能

• 支持多租户身份验证（《a href="https://github.com/Azure/azure-sdk-for-python/pull/24278" rel="nofollow">#24278）

已修复的bug

• 修复了即使传递了完整的 EdmProperty 元组，odmtype 标签也没有包含在布尔型和 int32 类型中的错误。这是为了与CLI兼容。

12.3.0 (2022-03-10)

已修复的bug

• 从 TableClient 构造函数中删除了对表名验证。相反，各个API将验证表名，并且仅在服务拒绝请求（由于表名无效）时抛出 ValueError。（#23106）
• 修复了批处理请求中的硬编码URL方案（#21953）
• 改进了 query_entities API 中查询格式的文档（#23235）
• 删除了不安全的调试日志

其他更改

• Python 2.7不再受支持。请使用Python版本3.6或更高版本。
• 将 azure-core 的依赖性提升到 >=1.15.0

12.2.0 (2021-11-10)

警告 此版本包含一个可能更改某些用户行为的错误修复。现在将自动转义包含单个引号字符（`'`）的分区键和行键，以便在更新、更新和删除实体操作中使用。对于已经转义或包含重复单个引号字符（`''`）的分区键和行键，现在将视为未转义值。

已修复的bug

• 解决了无法用枚举值代替实体更新模式字符串的问题（#20247）。
• 解决了分区键和行键中的单引号字符没有正确转义的问题（#20301）。

新增功能

• 在 `aio.TableClient.submit_transaction` 中添加了对异步迭代器的支持（#21083，感谢 yashbhutoria）。

其他更改

• 将 msrest 的依赖性提升到 >=0.6.21

12.1.0 (2021-07-06)

新增功能

• 仅存储账户：现在TableClient和TableServiceClient可以使用azure-identity凭据进行身份验证。注意：使用TokenCredential认证的TableClient不能使用get_table_access_policy或set_table_access_policy方法。

12.0.0 (2021-06-08)

重大变更

• 实体中的EdmType.Binary数据现在在Python 3中将反序列化为bytes，在Python 2中将反序列化为str，而不是EdmProperty实例。同样，在序列化时，Python 3中的bytes和Python 2中的str将被解释为二进制（这针对Python 3没有变化，但对于Python 2，之前的str被序列化为EdmType.String，现在发生变更）。
• TableClient.create_table现在返回一个TableItem实例。
• 所有模型构造函数的可选参数现在都是关键字参数。
• 存储服务配置模型现在已使用前缀Table，包括TableAccessPolicy、TableMetrics、TableRetentionPolicy、TableCorsRule。
• TableServiceClient.set_service_properties的所有参数现在都是关键字参数。
• 所有客户端的credential参数现在都是关键字参数。
• 方法TableClient.get_access_policy现在将在之前返回一个“空”访问策略对象的地方返回None。
• TableAccessPolicy实例中的时间戳属性现在将反序列化为datetime实例。

修复

• 已修复通过URL/凭据或连接字符串支持Cosmos模拟器端点。
• 已修复在TableClient.from_table_url类方法中从URL解析表名。
• 如果使用，客户端上的account_name属性现在将从AzureNamedKeyCredential中获取。
• 任何额外的odata元数据都返回在实体的元数据中。
• 实体元数据中的时间戳现在将反序列化为时间戳。
• 如果在create_entity操作中添加了prefer头，则将返回回显。
• 在412 if-not-match错误上引发的错误现在将是一个特定的azure.core.exceptions.ResourceModifiedError。
• EdmType.DOUBLE值现在在请求有效负载中显式类型化。
• 已修复TableCorsRule上列表属性的序列化和反序列化。

12.0.0b7 (2021-05-11)

重大变更

• 客户端构造函数中的account_url参数已重命名为endpoint。
• TableEntity对象现在仅作为字典使用，不再支持通过属性访问键。
• 实体的元数据现在通过TableEntity.metadata属性访问，而不是方法。
• 已删除显式的LinearRetry和ExponentialRetry，改用关键字参数。
• 在查询API中将filter参数重命名为query_filter。
• 客户端上的location_mode属性现在是只读的。这已作为构造函数的关键字参数添加。
• TableItem.table_name已重命名为TableItem.name。
• 已删除TableClient.create_batch方法以及TableBatchOperations对象。事务性批处理现在通过简单的Python元组列表支持。
• TableClient.send_batch已重命名为TableClient.submit_transaction。
• 已删除BatchTransactionResult对象，改为返回一个包含返回元数据的批处理实体可迭代对象。
• 已删除批处理上下文管理器行为。
• EntityProperty现在是一个命名元组，可以用一个(entity, EdmType)元组表示。
• 将EntityProperty.type重命名为EntityProperty.edm_type。
• BatchErrorException已重命名为TableTransactionError。
• location_mode不再是客户端上的公共属性。
• 唯一支持的凭据是AzureNamedKeyCredential、AzureSasCredential或通过连接字符串进行身份验证。
• 从TableItem类中删除了date和api_version。

修复

• 已修复Cosmos合并操作的问题。
• 从管道中删除了旧的存储策略。
• 从客户端类中删除了未使用的旧客户端端加密属性。
• 已修复在服务/表客户端之间共享管道的问题。
• 添加了对Azurite存储模拟器的支持。
• 在事务请求返回413错误码时抛出RequestTooLargeError。
• 在查询过滤器中添加了对Int64和Binary类型的支持。
• 在TableClient.get_entity()中添加了对select关键字参数的支持。
• 在update_entity和delete_entity中，如果通过kwargs没有提供etag，则如果实体中有，将使用实体的etag。

12.0.0b6 (2021-04-06)

• 更新了实体中datetime字段的反序列化，以支持保留带额外小数位的服务格式。
• 现在将字符串参数传递到查询过滤器时，将进行转义以防止注入。
• 修复了异步重试策略中增加重试次数的bug。

12.0.0b5 (2021-03-09)

• 此版本及所有未来版本将需要Python 2.7或Python 3.6+，Python 3.5不再受支持。
• 添加了SAS凭据作为认证选项。
• 将azure-core的最低要求提升到1.10.0。
• 将msrest的最低要求从0.6.10提升到0.6.19。
• 添加了对带有毫秒的datetime实体的支持。
• 添加了对共享访问签名认证的支持。

12.0.0b4 (2021-01-12)

• 修复了一个问题，其中query_entities kwarg parameters不会与多个参数或非字符串参数一起工作。现在它支持多个参数和数字、字符串、布尔值、UUID和datetime对象。
• 修复了一个问题，其中delete_entity会在实体中包含'@'符号时返回ClientAuthenticationError。

12.0.0b3 (2020-11-12)

• 添加了对实体操作事务分批的支持。
• 修复了list_tables和query_tables中的反序列化bug，其中TableItem.table_name是对象而不是字符串。
• 修复了未识别的实体数据字段被静默忽略的问题。现在它们将引发TypeError。
• 修复了查询过滤器参数被忽略的问题（#15094）。

12.0.0b2 (2020-10-07)

• 通过在发送到服务之前将枚举转换为字符串，添加了对可枚举类型的支持。

12.0.0b1 (2020-09-08)

这是azure-data-tables客户端库的第一个beta版本。Azure Tables客户端库可以无缝地针对Azure Table存储或Azure Cosmos DB表服务端点，无需代码更改。