Important
Azure Cosmos DB中的分布式事务目前以公共预览版提供。 此预览版在没有服务级别协议(SLA)的情况下提供。 在正式发布之前,行为、限制和支持的方案可能会更改。
本文介绍如何在Azure Cosmos DB上为NoSQL帐户启用分布式事务,并通过 .NET SDK 使用这些事务提交跨同一帐户和区域中多个逻辑分区、容器和数据库的原子读写操作。
本文中的示例使用单个方案 --一个包含两个 banking 容器的数据库( accounts 按帐户 ID 分区)和 ledger (通过发布月份进行分区)-因此,读取和写入示例中会显示相同的项。
先决条件
在开始之前,请确保具备:
- 活动的 Azure 订阅。 如果没有 试用版,请创建一个试用版。
-
用于 NoSQL 的 Azure Cosmos DB 帐户。 该帐户必须:
- 使用 NoSQL (Core SQL) API。 预览版不支持 MongoDB、Cassandra、表和 Gremlin API。
- 必须是预配吞吐量帐户(手动或自动缩放)。 预览版不支持无服务器帐户。
- 在公共Azure云区域中运行。
- 为单写入区域账户。 预览版不支持多区域写入帐户。
- 未配置以下任何功能:
- 客户管理的密钥 (CMK)
- 按分区自动故障转移(PPAF)
- 连续备份
- 长期保留
- 分区合并
- 分层分区键 (HPK)
- Fabric 原生数据库
- NuGet 中Azure Cosmos DB .NET v3 SDK (
Microsoft.Azure.Cosmos) 的最低要求版本为 v3.64.0-preview.0。
为您的账户申请登记
分布式事务是公开预览功能。 通过 Azure 门户、Azure CLI或 PowerShell 的自助服务注册当前不可用。
若要请求注册,请提交 分布式事务加入表单。 请求通常在一到两个工作日内完成。 帐户准备就绪后会收到确认。
安装所需的.NET SDK
将Azure Cosmos DB .NET SDK 的最新预览版本(v3.64.0-preview.0)添加到项目中。
dotnet add package Microsoft.Azure.Cosmos --version 3.64.0-preview.0
初始化客户端
将这些导入添加到 C# 文件的顶部。
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Threading;
using Microsoft.Azure.Cosmos;
使用事务重试选项创建客户端。 显示的值为默认值。
CosmosClientOptions options = new CosmosClientOptions
{
MaxRetryAttemptsOnAbortedTransactions = 10,
MaxRetryWaitTimeOnAbortedTransactions = TimeSpan.FromSeconds(30)
};
SDK 会自动重试服务报告为可重试的请求,并遵循服务器提供的 Retry-After 提示。 默认情况下,它会重试最多 10 次或直到 30 秒的累积重试延迟(以先发生者为准);这不是执行超时。 将 MaxRetryAttemptsOnAbortedTransactions 设置为 0 以禁用这些重试。 受限制的请求使用单独的 MaxRetryAttemptsOnRateLimitedRequests 和 MaxRetryWaitTimeOnRateLimitedRequests 设置。
使用 Microsoft Entra ID 或账户密钥,针对你已注册的账户初始化 CosmosClient。
将 Microsoft Entra ID 用于生产环境。 若要使用所需的角色分配和凭据来设置帐户,请参阅使用基于角色的访问控制连接到 Azure Cosmos DB for NoSQL。
using Microsoft.Azure.Cosmos;
using Azure.Identity;
string endpoint = "https://<your-account>.documents.azure.cn:443/";
using CosmosClient client = new CosmosClient(
endpoint, new Azure.Identity.DefaultAzureCredential(), options);
所使用的标识必须在参与事务的每个容器上具有数据平面写入权限(例如 Cosmos DB 内置数据参与者 角色)。 在事务批处理中,会针对每项单独操作进行角色检查。
可以使用GetContainer实例上的CosmosClient方法获取容器引用。 例如:
Container accounts = client.GetContainer("banking", "accounts");
Container ledger = client.GetContainer("banking", "ledger");
提交多分区写入事务
.NET v3 SDK 将 CreateDistributedWriteTransaction() API 添加到 CosmosClient。 为每个项串联一个操作,然后调用 ExecuteTransactionAsync,将整个批处理作为单个原子单元提交。
以下示例以原子方式将 100 个单位从 account-A 转移到 account-B,并在 ledger 容器中记录相应的条目。 这两个帐户位于容器的不同逻辑分区 accounts 中,账本条目位于单独的容器中。
这些示例假定两个容器都使用分区键路径 /pk ,并且帐户项已存在。 每个写入示例都是独立的;仅运行一个,因为每个示例都会创建该账本条目 txn-1001。
这些固定余额假定这两个帐户从 1000 开始。 对于并发传输,请使用条件 PATCH 请求。
var updatedAccountA = new { id = "account-A", pk = "account-A", balance = 900.00 };
var updatedAccountB = new { id = "account-B", pk = "account-B", balance = 1100.00 };
var ledgerEntry = new
{
id = "txn-1001", pk = "2026-09",
from = "account-A", to = "account-B", amount = 100.00
};
using DistributedTransactionResponse writeResponse = await client
.CreateDistributedWriteTransaction()
.ReplaceItem(accounts, new PartitionKey("account-A"), "account-A", updatedAccountA)
.ReplaceItem(accounts, new PartitionKey("account-B"), "account-B", updatedAccountB)
.CreateItem(ledger, new PartitionKey("2026-09"), ledgerEntry.id, ledgerEntry)
.ExecuteTransactionAsync(CancellationToken.None);
if (!writeResponse.IsSuccessStatusCode ||
writeResponse.Any(operation => !operation.IsSuccessStatusCode))
{
throw new InvalidOperationException(
$"Transaction failed: {writeResponse.StatusCode}; {writeResponse.ErrorMessage}; " +
$"ActivityId={writeResponse.ActivityId}; Diagnostics={writeResponse.Diagnostics}");
}
Console.WriteLine(writeResponse.ResponseMode == DistributedTransactionResponseMode.Standard
? "Transaction committed."
: "FastResponse received; do not infer a terminal commit outcome from this response.");
要么将这三个项目一起提交,要么一个都不要提交。 不存在部分状态。
Important
写入仍然是全有或全无的。 在 FastResponse 模式下,调用可以在最终提交或中止之前返回。 ResponseMode 表示服务使用的模式(若未报告,则为 Standard);它不是客户端设置。
读取和写入事务实例是一次性的,即使在失败或取消之后也是如此;创建新的实例以再次运行。 取消的调用不能证明事务已回滚,因此不要盲目重播它。
在单个事务中混合操作类型
可以在同一事务中混合使用 CreateItem、UpsertItem、ReplaceItem、PatchItem 和 DeleteItem。
using DistributedTransactionResponse patchResponse = await client
.CreateDistributedWriteTransaction()
.PatchItem(accounts, new PartitionKey("account-A"), "account-A",
new[] { PatchOperation.Increment("/balance", -100L) },
new DistributedTransactionPatchItemRequestOptions
{
FilterPredicate = "from c where c.balance >= 100"
})
.PatchItem(accounts, new PartitionKey("account-B"), "account-B",
new[] { PatchOperation.Increment("/balance", 100L) })
.CreateItem(ledger, new PartitionKey("2026-09"), ledgerEntry.id, ledgerEntry)
.ExecuteTransactionAsync(CancellationToken.None);
Console.WriteLine(
$"Status={patchResponse.StatusCode}; Mode={patchResponse.ResponseMode}; " +
$"Error={patchResponse.ErrorMessage}; Diagnostics={patchResponse.Diagnostics}");
提交多分区读取事务
当您需要获取位于不同逻辑分区、容器或数据库中的项的CreateDistributedReadTransaction()时,请使用 。 与发起多个彼此独立的 ReadItemAsync 调用不同,分布式读事务会返回所有项在某一单个已提交时刻的状态,因此读取方绝不会看到仅部分生效的写事务。
为每个项链接一个 ReadItem 调用,然后调用 CommitTransactionAsync 以提取快照:
using DistributedTransactionResponse readResponse = await client
.CreateDistributedReadTransaction()
.ReadItem(accounts, new PartitionKey("account-A"), "account-A")
.ReadItem(accounts, new PartitionKey("account-B"), "account-B")
.ExecuteTransactionAsync(CancellationToken.None);
if (!readResponse.IsSuccessStatusCode &&
readResponse.StatusCode != HttpStatusCode.NotModified)
{
throw new InvalidOperationException(
$"Read failed: {readResponse.StatusCode}; {readResponse.ErrorMessage}; " +
$"Diagnostics={readResponse.Diagnostics}");
}
for (int i = 0; i < readResponse.Count; i++)
{
if (readResponse[i].StatusCode == HttpStatusCode.NotModified)
{
Console.WriteLine($"Operation {i}: unchanged.");
continue;
}
if (!readResponse[i].IsSuccessStatusCode)
{
throw new InvalidOperationException(
$"Read operation {i} failed: {readResponse[i].StatusCode}; " +
$"Diagnostics={readResponse.Diagnostics}");
}
Dictionary<string, object> account =
readResponse.GetOperationResultAtIndex<Dictionary<string, object>>(i).Resource;
Console.WriteLine($"{account["id"]}: {account["balance"]}");
}
结果遵循请求顺序。 使用 IfNoneMatchEtag 时,未更改的项目返回 304;如果所有内容均未更改,则事务返回 304 并保留结果。 IsSuccessStatusCode 对于 304 为 false,因此请检查每个操作。 使用完后释放响应对象。
何时使用分布式读取事务
当正确性取决于跨分区分布的项 的相互一致性 时,分布式读取事务最有用。 常见方案包括:
- 跨帐户余额对帐。 读取多腿资金转账所涉及的每个账户余额,以确认借方和贷方之和为零,并避免出现这种风险:在某笔并发转账提交之前读取其中一腿,而在其提交之后读取另一腿。
- 库存和订单验证。 在决定是否接受新订单之前,先一起读取库存项和相应的待定订单记录,因此可用数量和预留数量始终反映相同的即时。
- 审计与合规快照。 获取相关记录的统一视图(例如订单、订单行项目和分别位于不同容器中的客户资料),用于报表、导出或监管举证。
- 缓存或读取模型重新生成。 从多个源容器填充反规范化视图或物化投影,而不会读到正在进行中的分布式写入事务导致的不完整写入。
对于单项读取,或者对于不需要相互一致性的不相关项,请继续使用 ReadItemAsync - 延迟较低,并且消耗的请求单位更少。
多区域注意事项
在多区域账户中,分布式事务仅在写入区域内具有原子性。 预览版不支持多区域写入帐户 - 该帐户必须具有单个写入区域。
- SDK 将所有事务读取和写入路由到帐户的 写入区域。
- 提交的数据 以异步方式和按分区复制到次要区域。 次要区域中的读取器可能会暂时观察部分更新,直到复制赶上。
对于需要对事务性数据进行全局写后读的应用程序,可采用以下任一方式:
- 将读取路由到写入区域,或
- 在帐户级别使用 强一致性,或者
- 使用提交响应返回的会话令牌。
会话令牌针对每个操作分别设置。 同一客户端会自动将它们应用于以后的非事务会话读取,但不适用于事务操作;将每个令牌原样传递给同一分区上的后续事务操作。 令牌提供分区级读己之写,而不是全局原子快照。
string accountAToken = writeResponse[0].SessionToken;
string accountBToken = writeResponse[1].SessionToken;
if (string.IsNullOrEmpty(accountAToken) || string.IsNullOrEmpty(accountBToken))
{
throw new InvalidOperationException(
"The response did not provide both tokens required for explicit session propagation.");
}
using DistributedTransactionResponse sessionReadResponse = await client
.CreateDistributedReadTransaction()
.ReadItem(accounts, new PartitionKey("account-A"), "account-A",
new DistributedTransactionRequestOptions { SessionToken = accountAToken })
.ReadItem(accounts, new PartitionKey("account-B"), "account-B",
new DistributedTransactionRequestOptions { SessionToken = accountBToken })
.ExecuteTransactionAsync(CancellationToken.None);
Console.WriteLine(
$"Status={sessionReadResponse.StatusCode}; Error={sessionReadResponse.ErrorMessage}; " +
$"Diagnostics={sessionReadResponse.Diagnostics}");
公共预览版中的限制
| Limit | 价值 |
|---|---|
| 每个事务的最大操作数 | 100 |
| 每个事务的最大有效负载大小 | 2 MB |
在正式发布之前,这些限制可能会更改。
支持的 API 和 SDK
目前,只有 NoSQL (Core SQL) API 支持分布式事务。
.NET v3 SDK 支持分布式事务。 即将推出对其他 SDK 的支持。