【免费下载链接】context-hub项目地址https://gitcode.com/gh_mirrors/co/context-hub点击查看免费下载本指南以 Context Hub 仓库中 content/azure/docs/data-tables/python/DOC.md 为权威主体系统讲解 Python 生态中azure-data-tables12.7.0的安装、认证、CRUD、OData 查询、事务批处理与异步编程。文章同时结合 Context Hub 的文档分发机制说明如何让 AI Agent 通过chubCLI 按需获取这份文档并给出分区键设计、乐观并发、端点与audience等高频踩坑点的可验证结论。读完你将能够为 Azure Table Storage 或 Azure Cosmos DB for Table 场景选对客户端与凭据模式、正确完成实体级增删改查与同分区事务以及排查绝大多数正确性问题。文档定位这份 DOC.md 在 Context Hub 中如何获取与使用Context Hub 是一个面向编码 Agent 的“精选版本化文档”仓库所有内容以纯 Markdown 开放维护Agent 通过chubCLI 搜索、抓取并按语言/版本取用而不是依赖训练数据中可能过时的 API 记忆。仓库结构上内容按「作者vendor/org→ 类型docs/skills→ 条目名 → 语言/版本」组织详见 docs/content-guide.md。本文对应的条目位于azure/data-tables其 Python 变体即 content/azure/docs/data-tables/python/DOC.mdfrontmatter 给出了可被搜索与版本追踪的元信息--- name:>chub search azure data tables --json # 检索条目取 id如 azure/data-tables chub get azure/data-tables --lang py # 抓取 Python 变体 DOC.mdAgent 使用chub的完整引导流程chub --help→chub search→chub get→chub annotate/chub feedback记录在 cli/skills/get-api-docs/SKILL.md全部命令与标志说明见 docs/cli-reference.md。Golden Rule先选对客户端再谈正确性文档的开篇给出了整个使用模型的核心规则在 Azure Table Storage 与 Azure Cosmos DB for Table 两种后端上统一使用azure-data-tables。需要账号级操作或建表时从TableServiceClient出发再获取TableClient进行实体读写。每个实体必须包含PartitionKey和RowKey而绝大多数正确性问题都源自分区设计、乐观并发或对目标端点使用了错误的认证配置。拆解这条规则落地时有三件事是决定性两级客户端分工TableServiceClient负责账号级操作创建/列出表、获取表客户端TableClient负责实体级操作插入、查询、更新、删除。绝大多数业务代码最终都落在TableClient上。双键模型是硬约束PartitionKey分区键与RowKey行键共同构成实体的唯一标识缺一不可且二者组成的键对必须唯一。表设计几乎完全由这两个键驱动——Azure Table 没有关系型数据库那样的通用二级索引。认证必须匹配目标端点Storage 端与 Cosmos DB for Table 端的端点、audience、角色要求各不相同混用是“看着代码对、跑起来报 401/403”的最常见原因。安装与版本锁定官方文档建议将包版本钉死到项目期望的版本避免 Agent 或依赖解析器拿到不兼容的版本python -m pip install azure-data-tables12.7.0如果使用 Microsoft Entra ID原 Azure AD认证还需一并安装azure-identitypython -m pip install azure-data-tables12.7.0 azure-identity其他主流包管理器等价写法uv add azure-data-tables12.7.0 poetry add azure-data-tables12.7.0版本层面的注意事项详见后文「版本敏感与迁移」PyPI 当前稳定版为12.7.0发布于 2025 年 5 月 6 日12.x客户端家族是官方包总览与 API 参考共同记载的现行家族并且是已弃用的azure-cosmosdb-tables的替代品。认证与客户端创建四种凭据模式SDK 支持四种凭据形态选择取决于运行环境与安全要求凭据模式适用场景Connection string连接字符串快速本地联调、原型验证Shared keyAzureNamedKeyCredential需要显式账号名 密钥的程序化场景SASAzureSasCredential已签发 SAS 令牌、希望把权限范围收窄TokenCredential如DefaultAzureCredential部署在 Azure 环境中的生产推荐总原则连接字符串适合快速本地搭建部署环境优先DefaultAzureCredential。服务客户端连接字符串需要创建/列出表并进一步获取各表客户端时用TableServiceClient.from_connection_stringfrom azure.data.tables import TableServiceClient conn_str DefaultEndpointsProtocolhttps;AccountName...;AccountKey...;EndpointSuffixcore.windows.net service TableServiceClient.from_connection_string(conn_strconn_str) table service.create_table_if_not_exists(table_nameproducts)服务客户端DefaultAzureCredential对 Azure Table Storage这是干净整洁的默认选择from azure.data.tables import TableServiceClient from azure.identity import DefaultAzureCredential credential DefaultAzureCredential() service TableServiceClient( endpointhttps://storage-account.table.core.windows.net, credentialcredential, )注意在存储端点上使用 Microsoft Entra ID 时调用方通常需要被授予Storage Table Data Contributor或Storage Table Data Reader角色前者可读写后者只读这与存储账号的访问密钥授权是两套体系。表客户端连接字符串直连表已存在、只需要实体操作时直接构造TableClient更省事from azure.data.tables import TableClient table TableClient.from_connection_string( conn_strDefaultEndpointsProtocolhttps;AccountName...;AccountKey...;EndpointSuffixcore.windows.net, table_nameproducts, )Cosmos DB for Table 快速上手模式Cosmos DB for Table 的官方快速入门与 Storage 场景使用同一包、同一TableServiceClient配合DefaultAzureCredentialfrom azure.data.tables import TableServiceClient from azure.identity import DefaultAzureCredential credential DefaultAzureCredential() service TableServiceClient( endpointazure-cosmos-db-table-account-endpoint, credentialcredential, ) table service.get_table_client(products)Cosmos 端点不要靠猜主机名——以 Azure 门户、SDK 快速入门或连接字符串中给出的账号端点为准。核心使用表、实体与查询创建或获取表get_table_client()只构造客户端、不会创建表需要幂等的建表语义时使用create_table_if_not_exists()from azure.data.tables import TableServiceClient service TableServiceClient.from_connection_string(conn_strconn_str) table service.create_table_if_not_exists(table_nameproducts) same_table service.get_table_client(products)插入或 upsert 实体每个实体必须携带PartitionKey与RowKeyfrom azure.data.tables import TableClient table TableClient.from_connection_string(conn_strconn_str, table_nameproducts) entity { PartitionKey: inventory, RowKey: sku-1001, name: Widget, price: 9.99, in_stock: True, } table.upsert_entity(entityentity)需要“创建或更新”语义时upsert_entity()是最安全默认行存在则更新不存在则插入无需先查后写。读取单个实体entity table.get_entity( partition_keyinventory, row_keysku-1001, ) print(entity[name], entity[price])用 OData 过滤器查询实体query_entities()使用OData 过滤器语法而非 SQL。优先使用带参数的参数化过滤器避免字符串拼接entities table.query_entities( query_filterPartitionKey eq pk and price gt minimum, parameters{pk: inventory, minimum: 5}, select[RowKey, name, price], ) for item in entities: print(item[RowKey], item[name], item[price])若必须手工拼接过滤器字符串值中的单引号要按 OData 规则转义防止过滤器被注入或解析失败。合并更新 vs 替换更新MERGE只更新提交中出现的属性其余属性保持不变REPLACE整体覆盖实体提交中未包含的属性会被丢弃。from azure.data.tables import UpdateMode entity table.get_entity(partition_keyinventory, row_keysku-1001) entity[price] 8.99 table.update_entity(entityentity, modeUpdateMode.MERGE)只有在你明确想让提交的实体成为存储中的完整形态时才使用UpdateMode.REPLACE——它是“整行覆盖”语义漏掉的字段会消失。删除实体table.delete_entity( partition_keyinventory, row_keysku-1001, )批处理一个事务内执行多个操作submit_transaction()是原子事务但只对同一分区内的实体有效operations [ (create, {PartitionKey: inventory, RowKey: sku-1002, name: Pen, price: 1.25}), (upsert, {PartitionKey: inventory, RowKey: sku-1003, name: Pencil, price: 0.75}), (update, {PartitionKey: inventory, RowKey: sku-1001, price: 7.99}, {mode: merge}), ] result table.submit_transaction(operations) print(result)Azure Table 存储本身的设计约束在这里依然成立事务内所有实体必须共享同一个分区键单个事务最多包含100 个实体整个事务的负载必须小于4 MiB。跨分区的一致性需求无法用批处理满足需要重新设计分区键或采用补偿式业务逻辑。异步客户端异步客户端位于azure.data.tables.aio通常配合async with使用以保证连接正确关闭import asyncio from azure.data.tables.aio import TableClient async def main() - None: async with TableClient.from_connection_string( conn_strconn_str, table_nameproducts, ) as table: entity await table.get_entity( partition_keyinventory, row_keysku-1001, ) print(entity[name]) asyncio.run(main())同步客户端的全部核心方法upsert_entity、get_entity、query_entities、update_entity、delete_entity、submit_transaction在aio命名空间下都有对应的async版本。配置要点端点EndpointAzure Storage 表端点形如https://account.table.core.windows.net主权云Sovereign Cloud存储端点使用不同域名例如table.core.usgovcloudapi.netAzure US GovernmentCosmos DB for Table 使用自己的账号端点优先从门户、SDK 快速入门或连接字符串获取而非猜测主机名。TokenCredential的audience使用TokenCredential时客户端默认面向公共云 audience。面向主权云或 Cosmos 专属 audience 时必须显式设置audience。Microsoft Learn 示例中涉及的取值包括https://storage.azure.comAzure 公共云存储https://storage.azure.usAzure 美国政府存储https://storage.azure.cnAzure 中国存储https://cosmos.azure.comAzure 公共云 Cosmoshttps://cosmos.azure.usAzure 美国政府 Cosmoshttps://cosmos.azure.cnAzure 中国 Cosmos主权云 Entra ID 场景下需要同时设置凭据上的 authority host 与表客户端上的audience二者必须配套。重试与传输选项包复用azure-core的管道pipeline选项常见的关键字参数包括retry_total、retry_connect、retry_read、retry_statusfrom azure.data.tables import TableServiceClient service TableServiceClient.from_connection_string( conn_strconn_str, retry_total5, retry_status5, )这些选项同样适用于TableClient可根据网络稳定性与后端限流行为调整。常见陷阱清单将文档中的易错点汇总如下每一条都对应一种可复现的失败模式get_table_client(name)只构造客户端不会创建表每个实体都必须同时包含PartitionKey与RowKey且这对键必须唯一query_entities()使用 OData 过滤器而非 SQL过滤器要么参数化要么正确转义字符串值update_entity(modeMERGE)不会删除提交中缺失的属性REPLACE才会乐观并发需要防止覆盖更新的版本时务必使用etag与match_condition例如MatchConditions.IfNotModified让服务端以 ETag 校验代替无条件覆盖事务批处理只在单个分区内有效且上限为 100 个实体、4 MiB 负载表设计由PartitionKey/RowKey驱动没有关系型数据库式的通用二级索引——查询设计要围绕分区键展开避免全表扫描式过滤DefaultAzureCredential的行为随环境变化本地失败常见原因是未登录 Azure CLI、缺少环境变量如AZURE_CLIENT_ID/AZURE_TENANT_ID/AZURE_CLIENT_SECRET或托管身份缺少角色分配主权云 Entra ID 场景凭据上的 authority host 与表客户端的audience必须同时配置并保持匹配。版本敏感与迁移建议PyPI 当前稳定版为12.7.0发布于 2025 年 5 月 6 日官方包总览与 API 参考均记载12.x客户端家族本仓库 content/azure/docs/data-tables/python/DOC.md 使用的12.7.0与截至 2026-03-12 的 PyPI 稳定元数据一致azure-data-tables是已弃用包azure-cosmosdb-tables的官方替代品不要在旧包上开启新工作除非你正处于迁移阶段需要维护遗留代码。如果你的 Agent 在按上述步骤实现时发现了文档未覆盖的坑例如某个端点特有的行为或版本怪癖可以按 cli/skills/get-api-docs/SKILL.md 中的流程用chub annotate azure/data-tables 笔记保存本地备注并用chub feedback把文档质量反馈给维护者帮助这份内容随真实使用持续变好。赞分享【免费下载链接】context-hub项目地址https://gitcode.com/gh_mirrors/co/context-hub点击查看免费下载相关推荐使用 azure/data-tables 13.3.2 操作 Azure Table Storage 与 Cosmos DB TableJavaScript 客户端完整实战指南使用 azure/data tables 13.3.2 操作 Azure Table Storage 与 Cosmos DB TableJavaScriptAzure Cosmos DB for NoSQL Python 客户端实战指南认证、分区键、CRUD、查询与异步用法Context Hub 精选文档Azure Cosmos DB for NoSQL Python 客户端实战指南认证、分区键、CRUD、查询与异步用法Context Hub 精选文档 本LlamaIndex AzureChatStore基于 Azure Table Storage 与 Cosmos DB 持久化聊天历史LlamaIndex AzureChatStore基于 Azure Table Storage 与 Cosmos DB 持久化聊天历史 本篇技术指南基于 Ll人工智能RAG大模型创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考