通过 Python 开始使用 Azure 表存储和 Azure Cosmos DB 表 APIGet started with Azure Table storage and the Azure Cosmos DB Table API using Python


本文中的内容适用于 Azure 表存储和 Azure Cosmos DB 表 API。The content in this article applies to Azure Table storage and the Azure Cosmos DB Table API. Azure Cosmos DB 表 API 是表存储的高级产品,可提供吞吐量优化表、全局分发和自动辅助索引。The Azure Cosmos DB Table API is a premium offering for table storage that offers throughput-optimized tables, global distribution, and automatic secondary indexes.

Azure 表存储和 Azure Cosmos DB 是用于在云中存储结构化 NoSQL 数据的服务,通过无架构设计提供键/属性存储。The Azure Table storage and the Azure Cosmos DB are services that store structured NoSQL data in the cloud, providing a key/attribute store with a schemaless design. 由于表存储和 Azure Cosmos DB 是无架构的,因此随着应用程序需求的发展,可以轻松调整数据。Because Table storage and Azure Cosmos DB are schemaless, it's easy to adapt your data as the needs of your application evolve. 对于许多类型的应用程序来说,访问表存储和表 API 数据速度快且经济高效,在数据量相似的情况下,其成本通常比传统 SQL 要低。Access to the table storage and table API data is fast and cost-effective for many types of applications, and is typically lower in cost than traditional SQL for similar volumes of data.

可以使用表存储或 Azure Cosmos DB 来存储灵活的数据集,例如 Web 应用程序的用户数据、通讯簿、设备信息,或者服务需要的其他类型的元数据。You can use the Table storage or the Azure Cosmos DB to store flexible datasets like user data for web applications, address books, device information, or other types of metadata your service requires. 可以在表中存储任意数量的实体,并且一个存储帐户可以包含任意数量的表,直至达到存储帐户的容量极限。You can store any number of entities in a table, and a storage account may contain any number of tables, up to the capacity limit of the storage account.

关于此示例About this sample

此示例介绍如何在常见的 Azure 表存储方案中使用用于 Python 的 Azure Cosmos DB 表 SDKThis sample shows you how to use the Azure Cosmos DB Table SDK for Python in common Azure Table storage scenarios. 该 SDK 的名称表示它适合与 Azure Cosmos DB 配合使用,但其实该 SDK 既适合与 Azure Cosmos DB 配合使用,也适合与 Azure 表存储配合使用,只不过每个服务具有唯一的终结点。The name of the SDK indicates it is for use with Azure Cosmos DB, but it works with both Azure Cosmos DB and Azure Tables storage, each service just has a unique endpoint. 本文使用 Python 示例探索这些方案,以演示如何:These scenarios are explored using Python examples that illustrate how to:

  • 创建和删除表Create and delete tables
  • 插入和查询实体Insert and query entities
  • 修改实体Modify entities

浏览此示例中的方案时,可能需要参考用于 Python API 的 Azure Cosmos DB SDK 参考While working through the scenarios in this sample, you may want to refer to the Azure Cosmos DB SDK for Python API reference.


若要成功完成此示例,需要以下项:You need the following to complete this sample successfully:

创建 Azure 服务帐户Create an Azure service account

可以通过 Azure 表存储或 Azure Cosmos DB 使用表。You can work with tables using the Azure Table storage or the Azure Cosmos DB. 若要详细了解这两个服务中的表产品/服务之间的差异,请参阅表产品/服务一文。To learn more about the differences between table offerings in these two services, see the Table offerings article. 需要为所要使用的服务创建一个帐户。You'll need to create an account for the service you're going to use. 以下部分说明了如何创建 Azure 表存储和 Azure Cosmos DB 帐户,但你只需使用其中一个。The following sections show how to create both Azure Table storage and the Azure Cosmos DB account, however you can just use one of them.

创建 Azure 存储帐户Create an Azure storage account

创建 Azure 存储帐户的最简单方法是使用 Azure 门户The easiest way to create an Azure storage account is by using the Azure portal. 若要了解更多信息,请参阅 创建存储帐户To learn more, see Create a storage account.

也可以使用 Azure PowerShellAzure CLI 创建 Azure 存储帐户。You can also create an Azure storage account by using Azure PowerShell or Azure CLI.

如果暂时不想创建存储帐户,也可以使用 Azure 存储模拟器在本地环境中运行和测试代码。If you prefer not to create a storage account at this time, you can also use the Azure storage emulator to run and test your code in a local environment. 有关详细信息,请参阅使用 Azure 存储模拟器进行开发和测试For more information, see Use the Azure storage emulator for development and testing.

创建 Azure Cosmos DB 表 API 帐户Create an Azure Cosmos DB Table API account

有关创建 Azure Cosmos DB 表 API 帐户的说明,请参阅创建数据库帐户For instructions on creating an Azure Cosmos DB Table API account, see Create a database account.

安装用于 Python 的 Azure Cosmos DB 表 SDKInstall the Azure Cosmos DB Table SDK for Python

创建存储帐户后,下一步是安装用于 Python 的 Azure Cosmos DB 表 SDKAfter you've created a Storage account, your next step is to install the Azure Cosmos DB Table SDK for Python. 有关安装该 SDK 的详细信息,请参阅 GitHub 上用于 Python 的 Cosmos DB 表 SDK 存储库中的 README.rst 文件。For details on installing the SDK, refer to the README.rst file in the Cosmos DB Table SDK for Python repository on GitHub.

导入 TableService 和 Entity 类Import the TableService and Entity classes

若要通过 Python 使用 Azure 表服务中的实体,请使用 TableServiceEntity 类。To work with entities in the Azure Table service in Python, you use the TableService and Entity classes. 将此代码添加到 Python 文件顶部附近,以便同时导入:Add this code near the top your Python file to import both:

from azure.cosmosdb.table.tableservice import TableService
from azure.cosmosdb.table.models import Entity

连接到 Azure 表服务Connect to Azure Table service

若要连接到 Azure 存储表服务,请创建 TableService 对象,并传入存储帐户名称和帐户密钥。To connect to Azure Storage Table service, create a TableService object, and pass in your Storage account name and account key. myaccountmykey 替换为自己的帐户名和密钥。Replace myaccount and mykey with your account name and key.

table_service = TableService(account_name='myaccount', account_key='mykey', endpoint_suffix='core.chinacloudapi.cn')

连接到 Azure Cosmos DBConnect to Azure Cosmos DB

若要连接到 Azure Cosmos DB,请从 Azure 门户中复制主连接字符串,并使用复制的连接字符串创建 TableService 对象:To connect to Azure Cosmos DB, copy your primary connection string from the Azure portal, and create a TableService object using your copied connection string:

table_service = TableService(connection_string='DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;TableEndpoint=myendpoint;')

创建表Create a table

调用 create_table 创建表。Call create_table to create the table.


将实体添加到表Add an entity to a table

若要添加实体,请先创建一个表示实体的对象,然后将该对象传递给 TableService.insert_entity 方法To add an entity, you first create an object that represents your entity, then pass the object to the TableService.insert_entity method. 实体对象可以是一个实体类型的字典或对象,且可定义实体的属性名称和值。The entity object can be a dictionary or an object of type Entity, and defines your entity's property names and values. 除了为实体定义的任何其他属性外,每个实体还必须包含 PartitionKey 和 RowKey 属性。Every entity must include the required PartitionKey and RowKey properties, in addition to any other properties you define for the entity.

此示例创建表示实体的字典对象,然后将其传递给 insert_entity 方法,以将其添加到表中:This example creates a dictionary object representing an entity, then passes it to the insert_entity method to add it to the table:

task = {'PartitionKey': 'tasksSeattle', 'RowKey': '001',
        'description': 'Take out the trash', 'priority': 200}
table_service.insert_entity('tasktable', task)

此示例创建一个 Entity 对象,然后将该对象传递给 insert_entity 方法,以将其添加到表中:This example creates an Entity object, then passes it to the insert_entity method to add it to the table:

task = Entity()
task.PartitionKey = 'tasksSeattle'
task.RowKey = '002'
task.description = 'Wash the car'
task.priority = 100
table_service.insert_entity('tasktable', task)

PartitionKey 和 RowKeyPartitionKey and RowKey

必须为每个实体同时指定 PartitionKey 和 RowKey 属性。You must specify both a PartitionKey and a RowKey property for every entity. 这些是实体的唯一标识符,它们一起构成了实体的主键。These are the unique identifiers of your entities, as together they form the primary key of an entity. 由于只对这些属性编制了索引,因此可使用这些值进行查询,速度比查询任何其他实体属性都要快。You can query using these values much faster than you can query any other entity properties because only these properties are indexed.

表服务使用 PartitionKey 在存储节点中智能分发。The Table service uses PartitionKey to intelligently distribute table entities across storage nodes. 具有相同的 PartitionKey 的实体存储在同一个节点上。Entities that have the same PartitionKey are stored on the same node. RowKey 是实体在其所属分区内的唯一 ID。RowKey is the unique ID of the entity within the partition it belongs to.

更新条目Update an entity

若要更新一个实体的所有属性值,请调用 update_entity 方法。To update all of an entity's property values, call the update_entity method. 此示例演示如何使用更新版本替换现有实体:This example shows how to replace an existing entity with an updated version:

task = {'PartitionKey': 'tasksSeattle', 'RowKey': '001',
        'description': 'Take out the garbage', 'priority': 250}
table_service.update_entity('tasktable', task)

如果要更新的实体不存在,更新操作将失败。If the entity that is being updated doesn't already exist, then the update operation will fail. 如果要存储实体(无论其存在与否),请使用 insert_or_replace_entityIf you want to store an entity whether it exists or not, use insert_or_replace_entity. 在下面的示例中,第一次调用会替换现有实体。In the following example, the first call will replace the existing entity. 第二个调用将插入新实体,因为表中不存在具有指定 PartitionKey 和 RowKey 的实体。The second call will insert a new entity, since no entity with the specified PartitionKey and RowKey exists in the table.

# Replace the entity created earlier
task = {'PartitionKey': 'tasksSeattle', 'RowKey': '001',
        'description': 'Take out the garbage again', 'priority': 250}
table_service.insert_or_replace_entity('tasktable', task)

# Insert a new entity
task = {'PartitionKey': 'tasksSeattle', 'RowKey': '003',
        'description': 'Buy detergent', 'priority': 300}
table_service.insert_or_replace_entity('tasktable', task)


update_entity 方法将替换现有实体的所有属性和值,还可使用它从现有实体删除属性。The update_entity method replaces all properties and values of an existing entity, which you can also use to remove properties from an existing entity. 可使用 merge_entity 方法更新具有新的或修改过的属性值的现有实体,而无需完全替换该实体。You can use the merge_entity method to update an existing entity with new or modified property values without completely replacing the entity.

修改多个实体Modify multiple entities

若要确保通过表服务进行原子处理,可以批量同时提交多个操作。To ensure the atomic processing of a request by the Table service, you can submit multiple operations together in a batch. 首先,使用 TableBatch 类,将多个操作添加到单个批次。First, use the TableBatch class to add multiple operations to a single batch. 然后,调用 TableService.commit_batch,以在一个原子操作中提交这些操作。Next, call TableService.commit_batch to submit the operations in an atomic operation. 批处理中要修改的实体必须位于同一分区。All entities to be modified in batch must be in the same partition.

该示例将两个实体一起添加到批处理中:This example adds two entities together in a batch:

from azure.cosmosdb.table.tablebatch import TableBatch
batch = TableBatch()
task004 = {'PartitionKey': 'tasksSeattle', 'RowKey': '004',
           'description': 'Go grocery shopping', 'priority': 400}
task005 = {'PartitionKey': 'tasksSeattle', 'RowKey': '005',
           'description': 'Clean the bathroom', 'priority': 100}
table_service.commit_batch('tasktable', batch)

还可以通过上下文管理器语法来使用批处理:Batches can also be used with the context manager syntax:

task006 = {'PartitionKey': 'tasksSeattle', 'RowKey': '006',
           'description': 'Go grocery shopping', 'priority': 400}
task007 = {'PartitionKey': 'tasksSeattle', 'RowKey': '007',
           'description': 'Clean the bathroom', 'priority': 100}

with table_service.batch('tasktable') as batch:

查询条目Query for an entity

要查询表中的实体,请将其 PartitionKey 和 RowKey 传递给 TableService.get_entity 方法。To query for an entity in a table, pass its PartitionKey and RowKey to the TableService.get_entity method.

task = table_service.get_entity('tasktable', 'tasksSeattle', '001')

查询一组条目Query a set of entities

在筛选器字符串中提供 filter 参数,可以查询一组实体。You can query for a set of entities by supplying a filter string with the filter parameter. 此示例通过对 PartitionKey 应用筛选器来查找 Seattle 中的所有任务:This example finds all tasks in Seattle by applying a filter on PartitionKey:

tasks = table_service.query_entities(
    'tasktable', filter="PartitionKey eq 'tasksSeattle'")
for task in tasks:

查询一部分实体属性Query a subset of entity properties

还可以限制查询中每个实体所返回的属性。You can also restrict which properties are returned for each entity in a query. 此方法称为“投影”,可减少带宽并提高查询性能,尤其适用于大型实体或结果集。This technique, called projection, reduces bandwidth and can improve query performance, especially for large entities or result sets. 使用 select 参数并传递希望返回给客户端的属性的名称。Use the select parameter and pass the names of the properties you want returned to the client.

以下代码中的查询只返回表中实体的说明。The query in the following code returns only the descriptions of entities in the table.


下面的代码段仅对 Azure 存储有效。The following snippet works only against the Azure Storage. 但不受存储模拟器支持。It is not supported by the Storage Emulator.

tasks = table_service.query_entities(
    'tasktable', filter="PartitionKey eq 'tasksSeattle'", select='description')
for task in tasks:

删除条目Delete an entity

将实体的 PartitionKeyRowKey 传递给 delete_entity 方法,以删除该实体。Delete an entity by passing its PartitionKey and RowKey to the delete_entity method.

table_service.delete_entity('tasktable', 'tasksSeattle', '001')

删除表Delete a table

如果不再需要表或表中的所有实体,请调用 delete_table 方法,从 Azure 存储永久删除该表。If you no longer need a table or any of the entities within it, call the delete_table method to permanently delete the table from Azure Storage.


后续步骤Next steps