快速入门：使用 Python SDK 和 Azure Cosmos DB 生成 API for Table 应用

适用对象： 表

本快速入门介绍如何从 Python 应用程序访问 Azure Cosmos DB API for Table。 Azure Cosmos DB for Table 是一种无架构数据存储，允许应用程序在云中存储结构化 NoSQL 数据。 由于数据存储在无架构设计中，因此将具有新特性的对象添加到表中时，系统会自动向表中添加新属性（列）。 Python 应用程序可以使用适用于 Python 的 Azure 数据表 SDK包访问 Azure Cosmos DB for Table。

先决条件

示例应用程序是用 Python 3.7 或更高版本编写的，不过这些原则适用于所有 Python 3.7+ 应用程序。 可以使用 Visual Studio Code 作为 IDE。

如果没有 Azure 试用版订阅，请在开始前创建一个试用版订阅。

示例应用程序

可以从存储库 https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask 克隆或下载本教程的示例应用程序。

git clone https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask.git

示例存储库中包含 1-starter-app 和 2-completed-app 示例文件夹。 1-starter-app 具有一些功能，可让你完成标记了“#TODO”的行。 本文中显示的代码片段是完成 1-starter-app 的建议附加代码。

已完成的示例应用程序使用天气数据作为示例来演示 API for Table 的功能。 表示天气观察值的对象使用 API for Table 进行存储和检索，其中就包括存储具有额外属性的对象以演示 API for Table 的无架构功能。 下图显示了在浏览器中运行的本地应用程序，其中显示了存储在 Azure Cosmos DB for Table 中的天气数据。

1 - 创建 Azure Cosmos DB 帐户

首先需要创建一个 Azure Cosmos DB Tables API 帐户，该帐户将包含应用程序中使用的表。 使用 Azure 门户、Azure CLI 或 Azure PowerShell 创建帐户。

2 - 创建表

接下来，需要在 Azure Cosmos DB 帐户中创建表，以供应用程序使用。 与传统数据库不同，只需指定表的名称，无需指定表中的属性（列）。 将数据加载到表中时，属性（列）会根据需要自动创建。

3 - 获取 Azure Cosmos DB 连接字符串

若要访问 Azure Cosmos DB 中的表，你的应用需要 CosmosDB 存储帐户的表连接字符串。 可以使用 Azure 门户、Azure CLI 或 Azure PowerShell 检索该连接字符串。

4 - 安装适用于 Python 的 Azure 数据表 SDK

创建 Azure Cosmos DB 帐户后，下一步是安装适用于 Python 的 Azure 数据表 SDK。 有关安装该 SDK 的详细信息，请参阅 GitHub 上适用于 Python 的数据表 SDK 存储库中的 README.md 文件。

使用 pip 安装适用于 Python 的 Azure 表客户端库：

pip install azure-data-tables

不要忘记在 1-starter-app 或 2-completed-app 文件夹中安装 requirements.txt。

---

5 - 在 .env 文件中配置 Table 客户端

从 Azure 门户复制你的 Azure Cosmos DB 帐户连接字符串，并使用复制的连接字符串创建 TableServiceClient 对象。 切换到 1-starter-app 或 2-completed-app 文件夹。 无论从哪个应用开始，都需要在 .env 文件中定义环境变量。

# Configuration Parameters
conn_str = "A connection string to an Azure Cosmos DB account."
table_name = "WeatherData"
project_root_path = "Project abs path"

Azure SDK 使用客户端对象与 Azure 通信，以对 Azure 执行不同的操作。 TableServiceClient 对象用于与 Azure Cosmos DB for Table 通信。 应用程序通常只有一个 TableServiceClient，并且每个表都有一个 TableClient。

例如，以下代码使用环境变量中的连接字符串创建 TableServiceClient 对象。

self.conn_str = os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)

---

6 - 实现 Azure Cosmos DB 表操作

示例应用的所有 Azure Cosmos DB 表操作都在 TableServiceHelper 类中实现，该类位于 webapp 目录下的 helper 文件中。 需要在此文件的顶部导入 TableServiceClient 类才能使用 azure.data.tables Python 客户端库中的对象。

from azure.data.tables import TableServiceClient

在 TableServiceHelper 类的开头，创建一个构造函数并添加用于 TableClient 对象的成员变量，以允许将 TableClient 对象注入该类。

def __init__(self, table_name=None, conn_str=None):
    self.table_name = table_name if table_name else os.getenv("table_name")
    self.conn_str = conn_str if conn_str else os.getenv("conn_str")
    self.table_service = TableServiceClient.from_connection_string(self.conn_str)
    self.table_client = self.table_service.get_table_client(self.table_name)

筛选从表返回的行

若要筛选从表返回的行，可以将 OData 样式筛选器字符串传递到 query_entities 方法。 例如，如果你想要获取 2021 年 7 月 1 日午夜到 2021 年 7 月 2 日午夜（含）的所有上海天气读数，可以传入以下筛选字符串。

PartitionKey eq 'Shanghai' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'

你可以在编写筛选器部分的 azure-data-tables 网站中查看相关的 OData 筛选器运算符。

将 request.args 参数传递到 TableServiceHelper 类中的 query_entity 方法时，它会为每个非 null 属性值创建一个筛选器字符串。 它随后会使用“and”子句将所有值联接在一起，以创建合并筛选器字符串。 此合并筛选器字符串会传递到 TableClient 对象上的 query_entities 方法，仅返回与筛选器字符串匹配的行。 可以在代码中使用类似方法，根据应用程序的要求构造合适的筛选器字符串。

def query_entity(self, params):
    filters = []
    if params.get("partitionKey"):
        filters.append("PartitionKey eq '{}'".format(params.get("partitionKey")))
    if params.get("rowKeyDateStart") and params.get("rowKeyTimeStart"):
        filters.append("RowKey ge '{} {}'".format(params.get("rowKeyDateStart"), params.get("rowKeyTimeStart")))
    if params.get("rowKeyDateEnd") and params.get("rowKeyTimeEnd"):
        filters.append("RowKey le '{} {}'".format(params.get("rowKeyDateEnd"), params.get("rowKeyTimeEnd")))
    if params.get("minTemperature"):
        filters.append("Temperature ge {}".format(params.get("minTemperature")))
    if params.get("maxTemperature"):
        filters.append("Temperature le {}".format(params.get("maxTemperature")))
    if params.get("minPrecipitation"):
        filters.append("Precipitation ge {}".format(params.get("minPrecipitation")))
    if params.get("maxPrecipitation"):
        filters.append("Precipitation le {}".format(params.get("maxPrecipitation")))
    return list(self.table_client.query_entities(" and ".join(filters)))

使用 TableEntity 对象插入数据

将数据添加到表的最简单方法是使用 TableEntity 对象。 在此示例中，数据会从输入模型对象映射到 TableEntity 对象。 输入对象中表示气象站名称和观察日期/时间的属性分别映射到 PartitionKey 和 RowKey 属性，这些属性共同构成表中行的唯一键。 输入模型对象上的额外属性随后会映射到 TableEntity 对象上的字典属性。 最后，TableClient 对象上的 create_entity 方法用于将数据插入表中。

修改示例应用程序中的 insert_entity 函数，以包含以下代码。

def insert_entity(self):
    entity = self.deserialize()
    return self.table_client.create_entity(entity)
    
@staticmethod
def deserialize():
    params = {key: request.form.get(key) for key in request.form.keys()}
    params["PartitionKey"] = params.pop("StationName")
    params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
    return params

使用 TableEntity 对象更新插入数据

如果尝试向表中插入的行具有该表中已存在的分区键/行键组合，则会收到错误。 因此，在向表添加行时，通常最好使用 upsert_entity 而不是 create_entity 方法。 如果表中已存在给定分区键/行键组合，则 upsert_entity 方法会更新现有行。 否则，行会添加到表中。

def upsert_entity(self):
    entity = self.deserialize()
    return self.table_client.upsert_entity(entity)
    
@staticmethod
def deserialize():
    params = {key: request.form.get(key) for key in request.form.keys()}
    params["PartitionKey"] = params.pop("StationName")
    params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
    return params

使用变量属性插入或更新插入数据

使用 Azure Cosmos DB for Table 的一个好处是，如果要加载到表的对象包含任何新属性，那这些属性会自动添加到表中并且值存储在 Azure Cosmos DB 中。 无需如同传统数据库中一样，运行 ALTER TABLE 等 DDL 语句来添加列。

在处理可能会随着时间推移添加或修改需要捕获的数据的数据源时，或者在不同的输入向应用程序提供不同的数据时，此模型可使应用程序具有灵活性。 在示例应用程序中，我们可以模拟一个不仅发送基本天气数据，而且还发送一些额外值的气象站。 首次将具有这些新属性的对象存储在表中时，对应属性（列）会自动添加到表中。

若要使用 API for Table 插入或更新插入此类对象，请将可扩充对象的属性映射到 TableEntity 对象，并根据需要对 TableClient 对象使用 upsert_entity 或 create_entity 方法。

在示例应用程序中，upsert_entity 函数还可实现使用变量属性插入或更新插入数据的功能

def insert_entity(self):
    entity = self.deserialize()
    return self.table_client.create_entity(entity)

def upsert_entity(self):
    entity = self.deserialize()
    return self.table_client.upsert_entity(entity)

@staticmethod
def deserialize():
    params = {key: request.form.get(key) for key in request.form.keys()}
    params["PartitionKey"] = params.pop("StationName")
    params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
    return params

更新条目

可以通过对 TableClient 对象调用 update_entity 方法来更新实体。

在示例应用中，此对象会传递到 TableClient 类中的 upsert_entity 方法。 它更新该实体对象，并使用 upsert_entity 方法将更新保存到数据库。

def update_entity(self):
    entity = self.update_deserialize()
    return self.table_client.update_entity(entity)
    
@staticmethod
def update_deserialize():
    params = {key: request.form.get(key) for key in request.form.keys()}
    params["PartitionKey"] = params.pop("StationName")
    params["RowKey"] = params.pop("ObservationDate")
    return params

删除实体

若要从表中删除实体，请使用对象的分区键和行键对 TableClient 对象调用 delete_entity 方法。

def delete_entity(self):
    partition_key = request.form.get("StationName")
    row_key = request.form.get("ObservationDate")
    return self.table_client.delete_entity(partition_key, row_key)

7 - 运行代码

运行示例应用程序以与 Azure Cosmos DB for Table 交互。 例如，从 2-completed-app 文件夹开始，安装了要求项后，可以使用：

python3 run.py webapp

有关运行示例应用程序的详细信息，请参阅示例存储库根路径中的 README.md 文件。

首次运行应用程序时没有数据，因为表为空。 使用应用程序顶部的任何按钮将数据添加到表。

选择“使用表实体插入”按钮会打开一个对话框，使你可以使用 TableEntity 对象插入或更新插入新行。

选择“使用可扩展数据插入”按钮后，将会打开一个对话框，在其中可以插入具有自定义属性的对象，并演示 Azure Cosmos DB for Table 如何根据需要自动将属性（列）添加到表中。 使用“添加自定义字段”按钮添加一个或多个新属性并演示此功能。

使用“插入示例数据”按钮将一些示例数据加载到 Azure Cosmos DB 表中。

• 对于 1-starter-app 示例文件夹，至少需要完成 submit_transaction 函数的代码，才能使示例数据插入正常工作。

• 示例数据从 sample_data.json 文件加载。 .env 变量 project_root_path 告知应用在何处查找此文件。 例如，如果从 1-starter-app 或 2-completed-app 文件夹运行应用程序，请将 project_root_path 设置为“”（空白）。

选择顶部菜单中的“筛选结果”项以进入“筛选结果”页面。 在此页面上，填写筛选条件以演示如何生成筛选子句并传递到 Azure Cosmos DB for Table。

清理资源

完成示例应用程序后，应从 Azure 帐户中删除与本文相关的所有 Azure 资源。 可以通过删除资源组来删除所有资源。

后续步骤

在本快速入门教程中，已了解如何创建 Azure Cosmos DB 帐户、使用数据资源管理器创建表和运行应用。 现在可以使用 API for Table 进行数据查询了。