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

如何配置 Azure Cosmos DB 集成缓存

项目
12/29/2023

适用范围： NoSQL

本文介绍如何预配专用网关、配置集成缓存和连接应用程序。

先决条件

如果还没有 Azure 订阅，可以在开始前创建一个免费帐户。
一个使用 Azure Cosmos DB 的现有应用程序。如果没有，这里提供了一些示例。
现有 Azure Cosmos DB API for NoSQL 帐户。

预配专用网关

在 Azure 门户中，导航到 Azure Cosmos DB 帐户，然后选择“专用网关”选项卡。
使用以下详细信息填写“专用网关”表单：
- 专用网关 - 打开“预配”切换开关。
- SKU - 选择具有所需计算和内存大小的 SKU。集成缓存将使用大约 50% 的内存，其余内存用于元数据以及将请求路由到后端分区。
- 实例数 - 节点数。出于开发目的，我们建议先选择一个 D4 大小的节点。根据缓存和实现高可用性所需的数据量，可以在初始测试后增加节点大小。
选择“保存”，然后等待大约 5-10 分钟，以完成专用网关预配。预配完成后，将看到以下通知：

配置集成缓存

创建专用网关时，会自动预配集成缓存。

修改应用程序的连接字符串，以使用新的专用网关终结点。

更新后的专用网关连接字符串位于“密钥”边栏选项卡中：

所有专用网关连接字符串都遵循相同的模式。从原始连接字符串中删除 documents.azure.com 并将其替换为 sqlx.cosmos.azure.com。专用网关始终具有相同的连接字符串，即使删除并重新预配它也是如此。

你无需使用同一 Azure Cosmos DB 帐户修改所有应用程序中的连接字符串。例如，你可能有一个 CosmosClient 使用网关模式和专用网关终结点进行连接，而另一个 CosmosClient 使用直接模式。换句话说，添加专用网关并不会影响 Azure Cosmos DB 的现有连接方式。
如果使用 .NET 或 Java SDK，请将连接模式设置为网关模式。对于 Python 和 Node.js SDK，不强制要求执行此步骤，因为除了网关模式之外，它们没有其他连接选项。

注意

如果使用最新的 .NET 或 Java SDK 版本，则默认连接模式为直接模式。若要使用集成缓存，必须重写此默认值。

调整请求一致性

请务必确保请求一致性为“会话”或“最终”。否则，请求将始终绕过集成缓存。要为所有读取操作配置特定一致性，最简单的方法是在帐户级别设置。你还可在请求级别配置一致性，如果只希望部分读取使用集成缓存，则建议在请求级别配置。

注意

如果使用的是 Python SDK，则必须显式设置每个请求的一致性级别。默认不会自动应用帐户级别的设置。

调整 MaxIntegratedCacheStaleness

配置 MaxIntegratedCacheStaleness，这是你愿意容忍过时缓存数据的最长时间。建议将 MaxIntegratedCacheStaleness 设置得尽可能高，因为这会增加可缓存命中重复点读取和查询的可能性。如果将 MaxIntegratedCacheStaleness 设置为 0，则无论一致性级别如何，读取请求都决不会使用集成缓存。未配置时，默认 MaxIntegratedCacheStaleness 为 5 分钟。

注意

MaxIntegratedCacheStaleness 可以设置为长达 10 年的时间。实际上，此值是最大过期时间。由于可能发生节点重启，缓存重置的时间可能会提前。

每个 SDK 的以下版本支持调整 MaxIntegratedCacheStaleness 设置：

SDK	支持的版本
.NET SDK v3	>= 3.30.0
Java SDK v4	>= 4.34.0
Node.js SDK	>=3.17.0
Python SDK	>=4.3.1

FeedIterator<MyClass> myQuery = container.GetItemQueryIterator<MyClass>(new QueryDefinition("SELECT * FROM c"), requestOptions: new QueryRequestOptions
        {
            DedicatedGatewayRequestOptions = new DedicatedGatewayRequestOptions 
            { 
                MaxIntegratedCacheStaleness = TimeSpan.FromMinutes(30) 
            }
        }
);

DedicatedGatewayRequestOptions dgOptions = new DedicatedGatewayRequestOptions()
   .setMaxIntegratedCacheStaleness(Duration.ofMinutes(30));
CosmosQueryRequestOptions queryOptions = new CosmosQueryRequestOptions()
   .setDedicatedGatewayRequestOptions(dgOptions);

CosmosPagedFlux<MyClass> pagedFluxResponse = container.queryItems(
        "SELECT * FROM c", queryOptions, MyClass.class);

 const queryRequestOptions = {
   maxIntegratedCacheStalenessInMs: 1800000 };
 const querySpec = {
   query: "SELECT * from c"
 };
 const { resources: items } = await container.items
   .query(querySpec, queryRequestOptions)
   .fetchAll();

query = "SELECT * FROM c"
container.query_items(
    query=query,
    max_integrated_cache_staleness_in_ms=1800000
)

绕过集成缓存（预览版）

使用 BypassIntegratedCache 请求选项来控制哪些请求使用集成缓存。绕过集成缓存的写入、点读取和查询不会使用缓存存储，从而为其他项节省出空间。绕过缓存的请求仍通过专用网关来路由。这些请求将从后端提供服务，并耗费 RU。

每个 SDK 的以下版本都支持绕过缓存：

SDK	支持的版本
.NET SDK v3	>= 3.35.0-preview
Java SDK v4	>= 4.49.0
Node.js SDK	不支持
Python SDK	不支持

FeedIterator<MyClass> myQuery = container.GetItemQueryIterator<MyClass>(new QueryDefinition("SELECT * FROM c"), requestOptions: new QueryRequestOptions
        {
            DedicatedGatewayRequestOptions = new DedicatedGatewayRequestOptions 
            { 
                BypassIntegratedCache = true
            }
        }
);

DedicatedGatewayRequestOptions dgOptions = new DedicatedGatewayRequestOptions()
   .setIntegratedCacheBypassed(true);
CosmosQueryRequestOptions queryOptions = new CosmosQueryRequestOptions()
   .setDedicatedGatewayRequestOptions(dgOptions);

CosmosPagedFlux<MyClass> pagedFluxResponse = container.queryItems(
        "SELECT * FROM c", queryOptions, MyClass.class);

验证缓存命中数

最后，可重启应用程序并通过查看请求费用是否为 0 来验证重复点读取或查询的集成缓存命中数。将 CosmosClient 修改为使用专用网关终结点后，所有请求都将通过专用网关进行路由。

为了让读取请求（点读取或查询）利用集成缓存，必须满足以下所有条件：

客户端连接到专用网关终结点
客户端使用网关模式（Python 和 Node.js SDK 始终使用网关模式）
请求的一致性必须设置为“会话”或“最终”

备注

你对集成缓存有何反馈？我们想听一听！欢迎直接与 Azure Cosmos DB 工程团队分享反馈：cosmoscachefeedback@microsoft.com