你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
如何配置 Azure Cosmos DB 集成缓存
适用范围: 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)
}
}
);
绕过集成的缓存
使用 BypassIntegratedCache
请求选项来控制哪些请求使用集成缓存。 绕过集成缓存的写入、点读取和查询不会使用缓存存储,从而为其他项节省出空间。 绕过缓存的请求仍通过专用网关来路由。 这些请求将从后端提供服务,并耗费 RU。
每个 SDK 的以下版本都支持绕过缓存:
SDK | 支持的版本 |
---|---|
.NET SDK v3 | >= 3.39.0 |
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
}
}
);
验证缓存命中数
最后,可重启应用程序并通过查看请求费用是否为 0 来验证重复点读取或查询的集成缓存命中数。 将 CosmosClient
修改为使用专用网关终结点后,所有请求都将通过专用网关进行路由。
为了让读取请求(点读取或查询)利用集成缓存,必须满足以下所有条件:
- 客户端连接到专用网关终结点
- 客户端使用网关模式(Python 和 Node.js SDK 始终使用网关模式)
- 请求的一致性必须设置为“会话”或“最终”
备注
你对集成缓存有何反馈? 我们想听一听! 欢迎直接与 Azure Cosmos DB 工程团队分享反馈:cosmoscachefeedback@microsoft.com