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

在 Azure Cosmos DB 中管理一致性级别

适用于: SQL API

本文介绍了如何在 Azure Cosmos DB 中管理一致性级别。 你将了解如何配置默认一致性级别、替代默认一致性、手动管理会话令牌以及了解概率有限过期 (PBS) 指标。

注意

本文使用 Azure Az PowerShell 模块,这是与 Azure 交互时推荐使用的 PowerShell 模块。 若要开始使用 Az PowerShell 模块,请参阅安装 Azure PowerShell。 若要了解如何迁移到 Az PowerShell 模块,请参阅 将 Azure PowerShell 从 AzureRM 迁移到 Az

配置默认一致性级别

默认一致性级别是客户端默认情况下使用的一致性级别。

若要查看或修改默认一致性级别,请登录到 Azure 门户。 找到你的 Azure Cosmos 帐户,打开“默认一致性”窗格。 选择你希望用作新的默认值的一致性级别,然后选择“保存”。 Azure 门户还使用音符提供了不同一致性级别的可视化效果。

Consistency menu in the Azure portal

替代默认一致性级别

客户端可以重写由服务设置的默认一致性级别。 可以在每个请求上设置一致性级别,这将替代在帐户级别设置的默认一致性级别。

提示

只能在 SDK 实例或请求级别放宽一致性要求。 若要从较弱的一致性移动到更强的一致性,请更新 Cosmos 帐户的默认一致性。

提示

替代默认一致性级别的操作仅适用于 SDK 客户端中的读取。 默认情况下,配置为强一致性的帐户仍会将数据同步写入和复制到帐户中的所有区域。 SDK 客户端实例或请求使用会话或较弱一致性替代此级别时,将使用单个副本执行读取。 有关更多详细信息,请参阅一致性级别和吞吐量

.NET SDK

// Override consistency at the client level
documentClient = new DocumentClient(new Uri(endpoint), authKey, connectionPolicy, ConsistencyLevel.Eventual);

// Override consistency at the request level via request options
RequestOptions requestOptions = new RequestOptions { ConsistencyLevel = ConsistencyLevel.Eventual };

var response = await client.CreateDocumentAsync(collectionUri, document, requestOptions);

Java V4 SDK

Java SDK V4 (Maven com.azure::azure-cosmos) 异步 API


CosmosAsyncClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .key(MASTER_KEY)
                .consistencyLevel(ConsistencyLevel.EVENTUAL)
                .buildAsyncClient();

Java V2 SDK

Async Java V2 SDK (Maven com.microsoft.azure::azure-cosmosdb)

// Override consistency at the client level
ConnectionPolicy policy = new ConnectionPolicy();

AsyncDocumentClient client =
        new AsyncDocumentClient.Builder()
                .withMasterKey(this.accountKey)
                .withServiceEndpoint(this.accountEndpoint)
                .withConsistencyLevel(ConsistencyLevel.Eventual)
                .withConnectionPolicy(policy).build();

Node.js/JavaScript/TypeScript SDK

// Override consistency at the client level
const client = new CosmosClient({
  /* other config... */
  consistencyLevel: ConsistencyLevel.Eventual
});

// Override consistency at the request level via request options
const { body } = await item.read({ consistencyLevel: ConsistencyLevel.Eventual });

Python SDK

# Override consistency at the client level
connection_policy = documents.ConnectionPolicy()
client = cosmos_client.CosmosClient(self.account_endpoint, {
                                    'masterKey': self.account_key}, connection_policy, documents.ConsistencyLevel.Eventual)

利用会话令牌

Azure Cosmos DB 中的一致性级别之一是“会话”一致性。 这是默认情况下应用于 Cosmos 帐户的默认级别。 使用会话一致性时,将为向 Azure Cosmos DB 发出的每个新的写入请求分配一个新的 SessionToken。 CosmosClient 将在内部的每个读取/查询请求中使用此令牌,以确保维持设置的一致性级别。

在某些情况下,你需要自行管理此会话。 假设某个 Web 应用程序有多个节点,则每个节点都会有其自己的 CosmosClient 实例。 如果希望这些节点参与同一会话(以便能够跨 Web 层一致地读取你自己的写入),必须使用 Cookie 或某些其他机制将 SessionToken 从写入操作的 FeedResponse<T> 发送到最终用户,使该令牌流回到 Web 层,并最终将 CosmosClient 用于后续读取。 如果你使用的轮循机制负载均衡器(如 Azure 负载均衡器)不在请求之间维护会话亲和性,读取可能会落在与写入请求不同的节点上(已在其中创建会话)。

如果没有如上所述传递 Azure Cosmos DB SessionToken,你可能会在一段时间内得到不一致的读取结果。

若要手动管理会话令牌,请从响应中获取会话令牌并针对每个请求设置它们。 如果不需手动管理会话令牌,则不需要使用这些示例。 SDK 会自动跟踪会话令牌。 如果未手动设置会话令牌,则默认情况下,SDK 使用最新的会话令牌。

.NET SDK

var response = await client.ReadDocumentAsync(
                UriFactory.CreateDocumentUri(databaseName, collectionName, "SalesOrder1"));
string sessionToken = response.SessionToken;

RequestOptions options = new RequestOptions();
options.SessionToken = sessionToken;
var response = await client.ReadDocumentAsync(
                UriFactory.CreateDocumentUri(databaseName, collectionName, "SalesOrder1"), options);

Java V4 SDK

Java SDK V4 (Maven com.azure::azure-cosmos) 异步 API


// Get session token from response
CosmosItemResponse<JsonNode> response = container.readItem(itemId, new PartitionKey(partitionKey), JsonNode.class).block();
String sessionToken = response.getSessionToken();

// Resume the session by setting the session token on the RequestOptions
CosmosItemRequestOptions options = new CosmosItemRequestOptions();
options.setSessionToken(sessionToken);
CosmosItemResponse<JsonNode> response2 = container.readItem(itemId, new PartitionKey(partitionKey), JsonNode.class).block();

Java V2 SDK

Async Java V2 SDK (Maven com.microsoft.azure::azure-cosmosdb)

// Get session token from response
RequestOptions options = new RequestOptions();
options.setPartitionKey(new PartitionKey(document.get("mypk")));
Observable<ResourceResponse<Document>> readObservable = client.readDocument(document.getSelfLink(), options);
readObservable.single()           // we know there will be one response
  .subscribe(
      documentResourceResponse -> {
          System.out.println(documentResourceResponse.getSessionToken());
      },
      error -> {
          System.err.println("an error happened: " + error.getMessage());
      });

// Resume the session by setting the session token on RequestOptions
RequestOptions options = new RequestOptions();
requestOptions.setSessionToken(sessionToken);
Observable<ResourceResponse<Document>> readObservable = client.readDocument(document.getSelfLink(), options);

Node.js/JavaScript/TypeScript SDK

// Get session token from response
const { headers, item } = await container.items.create({ id: "meaningful-id" });
const sessionToken = headers["x-ms-session-token"];

// Immediately or later, you can use that sessionToken from the header to resume that session.
const { body } = await item.read({ sessionToken });

Python SDK

// Get the session token from the last response headers
item = client.ReadItem(item_link)
session_token = client.last_response_headers["x-ms-session-token"]

// Resume the session by setting the session token on the options for the request
options = {
    "sessionToken": session_token
}
item = client.ReadItem(doc_link, options)

监视概率有限过期 (PBS) 指标

最终一致性的最终程度如何? 对于普通情况,我们是否可以提供版本历史和时间方面的过期限度。 概率有限过期 (PBS) 指标尝试量化过期的概率并将其显示为指标。 若要查看 PBS 指标,请在 Azure 门户中转到你的 Cosmos 帐户。 打开“指标”窗格,然后选择“一致性”选项卡。查看名为“基于工作负载的强一致性读取的概率(请参阅 PBS)”的图。

PBS graph in the Azure portal

后续步骤

详细了解如何管理数据冲突,或者继续了解 Azure Cosmos DB 中的下一个关键概念。 请参阅以下文章: