如何設定 Azure Cosmos DB 整合式快取

適用於：NoSQL

本文描述如何佈建專用閘道、設定整合式快取，以及連接應用程式。

必要條件

• 如果您沒有 Azure 訂用帳戶，請在開始前建立免費帳戶。
• 使用 Azure Cosmos DB 的現有應用程式。 如果沒有，這裡有一些範例。
• 現有的 Azure Cosmos DB API for NoSQL 帳戶。

佈建專用閘道

1. 瀏覽至 Azure 入口網站的 Azure Cosmos DB 帳戶，然後選取 [專用閘道] 索引標籤。

   

2. 在 [專用閘道] 表單中填寫下列詳細資料：

   • 專用閘道 - 開啟 [已佈建] 的切換開關。
   • SKU - 選取有所需計算和記憶體大小的 SKU。 整合式快取會使用大約 50% 的記憶體，而剩餘的記憶體則用於中繼資料以及將要求路由傳送至後端分割區。
   • 執行個體數目 - 節點數目。 若為開發之用，建議從一個節點 D4 大小開始。 您可在初始測試後，再根據需要快取的資料量增加節點大小，以實現高可用性。

   

3. 選取 [儲存] 並等候約 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。 即使您移除並重新佈建專用網關，專用閘道一律會有相同的端點。

.NET

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 中的預設值。 您必須明確設定閘道模式以使用專用閘道。

Java

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 中的預設值。 您必須明確設定閘道模式以使用專用閘道。

Node.js

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})

Python

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

endpoint = "<dedicated-gateway-endpoint>"

credential = DefaultAzureCredential()

client = CosmosClient(endpoint, credential=credential)

使用 連接字串 進行驗證

1. 修改應用程式的連接字串，以使用新的專用閘道端點。

   更新的專用閘道連接字串位於 [金鑰] 刀鋒視窗中：

   

   所有專用閘道連接字串都遵循相同的模式。 移除原始連接字串中的 documents.azure.com，並更換成 sqlx.cosmos.azure.com。 即使移除並重新佈建閘道，專用閘道也一律有相同的連接字串。

2. 如果使用 .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

.NET

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

Java

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);

Node.js

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

Python

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	不支援

.NET

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

Java

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

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

Node.js

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

Python

Python SDK 中無法使用 [略過整合式快取要求] 選項。

驗證快取命中

最後，您可以重新啟動應用程式，查看要求費用是否為 0，以驗證重複點讀取或查詢的整合式快取命中情況。 一旦將 CosmosClient 修改為使用專用閘道端點，所有要求都會經由專用閘道路由。

為使讀取要求 (點讀取或查詢) 能利用整合式快取，下列所有條件都必須為 true：

• 用戶端連線到專用閘道端點
• 您的用戶端會使用閘道模式 (Python 和 Node.js SDK 一律使用閘道模式)
• 要求的一致性必須設定為工作階段或最終

注意

您對整合式快取有任何意見嗎？ 我們想知道您的看法！ 歡迎您將意見直接告訴 Azure Cosmos DB 工程小組：cosmoscachefeedback@microsoft.com

下一步

• 整合式快取常見問題
• 整合式快取概觀
• 專用閘道