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

如何配置 Azure Cosmos DB 集成缓存

项目
11/01/2024

适用范围： NoSQL

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

先决条件

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

预配专用网关

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

配置你的应用程序以便使用集成缓存

预配专用网关时，会自动创建集成缓存。如果所有使用 Azure Cosmos DB 的应用程序都不需要使用集成缓存，则无需将这些应用程序连接到专用网关。添加专用网关并不会影响 Azure Cosmos DB 的现有连接方式。例如，你可能有一个 CosmosClient 使用网关模式和专用网关终结点进行连接，而另一个 CosmosClient 使用直接模式。

使用基于角色的访问控制进行身份验证

专用网关使用与 Azure Cosmos DB 相同的权限、角色定义和角色分配。如果已在 Azure Cosmos DB 帐户中为数据平面操作配置了基于角色的访问控制 (RBAC)，则也可使用它来向专用网关进行身份验证。了解 Azure Cosmos DB 数据平面的 RBAC 操作。

通过设置专用网关终结点、凭据并配置网关连接模式来配置 CosmosClient。所有专用网关终结点都遵循相同的模式。从原始终结点中移除 documents.azure.com 并将其替换为 sqlx.cosmos.azure.com。专用网关始终具有相同的终结点，即使移除并重新预配它也是如此。

using Azure.Core;
using Azure.Identity;
using Microsoft.Azure.Cosmos;

string endpoint = "<dedicated-gateway-endpoint>";

TokenCredential credential = new DefaultAzureCredential();

CosmosClient client = new(endpoint, credential, new CosmosClientOptions { ConnectionMode = ConnectionMode.Gateway });

重要

直接连接模式是 .NET SDK 中的默认设置。必须将网关模式显式配置为使用专用网关。

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

public class NoSQL{
    public static void main(String[] args){
        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
            .build();
        
        CosmosClient client = new CosmosClientBuilder()
            .endpoint("<dedicated-gateway-endpoint>")
            .gatewayMode()
            .credential(credential);
            .buildClient();
    }
}

重要

直接连接模式是 Java SDK 中的默认设置。必须将网关模式显式配置为使用专用网关。

const { CosmosClient } = require('@azure/cosmos');
const { DefaultAzureCredential } = require('@azure/identity');

const endpoint = '<dedicated-gateway-endpoint>';

const credential = new DefaultAzureCredential();

const client = new CosmosClient({ endpoint, aadCredentials:credential})

from azure.cosmos import CosmosClient
from azure.identity import DefaultAzureCredential

endpoint = "<dedicated-gateway-endpoint>"

credential = DefaultAzureCredential()

client = CosmosClient(endpoint, credential=credential)

使用连接字符串进行身份验证

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

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

所有专用网关连接字符串都遵循相同的模式。从原始连接字符串中删除 documents.azure.com 并将其替换为 sqlx.cosmos.azure.com。专用网关始终具有相同的连接字符串，即使删除并重新预配它也是如此。
如果使用 .NET 或 Java SDK，请将连接模式设置为网关模式。对于 Python 和 Node.js SDK，不强制要求执行此步骤，因为除了网关模式之外，它们没有其他连接选项。

重要

如果使用最新的 .NET 或 Java 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.39.0
Java SDK v4	>= 4.49.0
Node.js SDK	>= 4.1.0
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);

    const queryRequestOptions = {
      bypassIntegratedCache: true };
    const querySpec = {
      query: "SELECT * from c"
    };
    const { resources: items, requestCharge: queryCharge } = await container.items
      .query(querySpec, queryRequestOptions)
      .fetchAll();

验证缓存命中数

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

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

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

备注

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

通过