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

快速入门:使用 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。

先决条件

示例应用程序是用 Python3.6 编写的,不过这些原则适用于所有 Python3.6+ 应用程序。 可以使用 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

示例应用程序使用天气数据作为示例来演示 API for Table 的功能。 表示天气观察值的对象使用 API for Table 进行存储和检索,其中就包括存储具有附加属性的对象以演示 API for Table 的无架构功能。

已完成应用程序的屏幕截图,其中显示了使用 API for Table 存储在 Cosmos DB 表中的数据。

1 - 创建 Azure Cosmos DB 帐户

首先需要创建一个 Azure Cosmos DB Tables API 帐户,该帐户将包含应用程序中使用的表。 可以使用 Azure 门户、Azure CLI 或 Azure PowerShell 执行此操作。

登录 Azure 门户,并按照以下步骤创建 Azure Cosmos DB 帐户。

说明 屏幕快照
在 Azure 门户中:
  1. 在 Azure 门户顶部的搜索栏中,输入“cosmos db”。
  2. 在搜索栏下方出现的菜单上的“服务”下,选择标有“Azure Cosmos DB”的项。
屏幕截图:如何使用顶部工具栏中的搜索框在 Azure 中查找 Azure Cosmos DB 帐户。
在“Azure Cosmos DB”页上,选择“+创建”。 屏幕截图:Azure 中 Azure Cosmos DB 帐户页面上的“创建”按钮位置。
在“选择 API 选项”页上,选择“Azure 表”选项。 将“Azure 表”选项显示为要选择的正确选项的屏幕截图。
在“创建 Azure Cosmos DB 帐户 - Azure 表”页上填写表单,如下所示。
  1. 通过选择“资源组”下的“新建”链接,为名为 rg-msdocs-tables-sdk-demo 的存储帐户创建一个新资源组。
  2. 为存储帐户指定名称 cosmos-msdocs-tables-sdk-demo-XYZ,其中的 XYZ 是三个任意的随机字符,用于创建独一无二的帐户名称。 Azure Cosmos DB 帐户名称必须为 3 到 44 个字符长,并且只能包含小写字母、数字或连字符 (-)。
  3. 选择存储帐户的区域。
  4. 选择“标准”性能。
  5. 在“容量模式”下,为此示例选择“预配吞吐量”。
  6. 对于此示例,请在“应用免费层折扣”下选择“应用”。
  7. 选择屏幕底部的“查看 + 创建”按钮,然后选择摘要屏幕上的“创建”以创建 Azure Cosmos DB 帐户。 此过程可能需要数分钟。
显示如何在 Azure Cosmos DB 帐户创建页面上填写字段的屏幕截图。

2 - 创建表

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

Azure 门户中完成以下步骤,以在 Azure Cosmos DB 帐户中创建表。

说明 屏幕快照
在Azure 门户,导航到 Azure Cosmos DB 帐户的概述页。 可以通过在顶部搜索栏中键入 Azure Cosmos DB 帐户的名称 (cosmos-msdocs-tables-sdk-demo-XYZ) 并在资源标题下进行查看,导航到 Azure Cosmos DB 帐户的概述页。选择 Azure Cosmos DB 帐户的名称以转到概述页。 如何使用顶部工具栏中的搜索框查找 Azure Cosmos DB 帐户的屏幕截图。
在概述页面上,选择“+添加表”。 “新建表”对话框将从页面右侧滑出。 显示“添加表”按钮位置的屏幕截图。
在“新建表”对话框中填充表单,如下所示。
  1. 输入名称“WeatherData”作为“表 ID”。 这是表的名称。
  2. 对于此示例,请在“表吞吐量(自动缩放)”下选择“手动”。
  3. 在估计的 RU/秒下,使用默认值 400。
  4. 选择“确定”按钮以创建表。
显示 Azure Cosmos DB 表的“新建表”对话框的屏幕截图。

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

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

说明 屏幕快照
在 Azure Cosmos DB 帐户页左侧的“设置”标题下找到名为“连接字符串”的菜单项,并将其选中。 此时会转到一个页面,你可以在其中检索 Azure Cosmos DB 帐户的连接字符串。 显示 Azure Cosmos DB 页面上的连接字符串链接位置的屏幕截图。
复制“主连接字符串”值以在应用程序中使用。 显示要在应用程序中选择和使用哪个连接字符串的屏幕截图。

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

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

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

pip install azure-data-tables

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

从 Azure 门户复制你的 Azure Cosmos DB 帐户连接字符串,并使用复制的连接字符串创建 TableServiceClient 对象。 切换到文件夹 1-strater-app2-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

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

6 - 实现 Azure Cosmos DB 表操作

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

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 'Chicago' 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 对象。 输入对象中表示气象站名称和观察日期/时间的属性分别映射到 PartitionKeyRowKey 属性,这些属性共同构成表中行的唯一键。 输入模型对象上的其他属性随后会映射到 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_entitycreate_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 交互。 首次运行应用程序时没有数据,因为表为空。 使用应用程序顶部的任何按钮将数据添加到表。

应用程序的屏幕截图,其中显示了用于通过表 API 将数据插入到 Azure Cosmos DB 中的按钮位置。

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

应用程序的屏幕截图,其中显示用于通过 TableEntity 对象插入数据的对话框。

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

应用程序的屏幕截图,其中显示用于通过带有自定义字段的对象插入数据的对话框。

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

应用程序的屏幕截图,其中显示示例数据插入按钮的位置。

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

应用程序的屏幕截图,其中显示筛选结果页面,并突出显示了用于导航到该页面的菜单项。

清理资源

完成示例应用程序后,应从你的 Azure 帐户中删除与本文相关的所有 Azure 资源。 可以通过删除资源组来进行这种清理。

可以在 Azure 门户中执行以下操作来删除资源组。

说明 屏幕快照
若要转到资源组,在搜索栏中键入资源组的名称。 然后在“资源组”选项卡上,选择资源组的名称。 显示如何搜索资源组的屏幕截图。
从“资源组”页顶部的工具栏中选择“删除资源组”。 显示“删除资源组”按钮位置的屏幕截图。
屏幕右侧将弹出一个对话框,要求确认删除资源组。
  1. 按说明在文本框中键入确认删除的资源组的完整名称。
  2. 选择页面底部的“删除”按钮。
显示用于删除资源组的确认对话框的屏幕截图。

后续步骤

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