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

發行項
03/28/2024

適用於：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.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
            }
        }
);

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 修改為使用專用閘道端點，所有要求都會經由專用閘道路由。

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

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

注意

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

共用方式為