Azure Cosmos DB 統合キャッシュを構成する方法

適用対象: NoSQL

この記事では、専用ゲートウェイをプロビジョニングし、統合キャッシュを構成し、アプリケーションを接続する方法について説明します。

前提条件

• Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。
• Azure Cosmos DB を使用する既存のアプリケーション。 これがない場合、こちらのいくつかサンプルがあります。
• 既存の Azure Cosmos DB API for NoSQL アカウント。

専用ゲートウェイをプロビジョニングする

1. Azure portal で Azure Cosmos DB アカウントに移動し、 [専用ゲートウェイ] タブを選択します。

   

2. [専用ゲートウェイ] フォームに、次の詳細を入力します。

   • [専用ゲートウェイ] - トグルを [プロビジョニング済み] に切り替えます。
   • [SKU] - 必要なコンピューティングおよびメモリ サイズを持つ SKU を選択します。 統合キャッシュはメモリの約 50% を使用し、残りのメモリはメタデータとバックエンド パーティションへの要求のルーティングに使用されます。
   • [インスタンスの数] - ノードの数。 開発目的の場合、D4 サイズの 1 つのノードから開始することをお勧めします。 最初のテスト後、キャッシュする必要があるデータの量に基づいて、高可用性を実現するために、ノード サイズを大きくすることができます。

   

3. [保存] を選択し、専用ゲートウェイのプロビジョニングが完了するまで約 5 から 10 分待機します。 プロビジョニングが完了すると、次の通知が表示されます。

   

統合キャッシュを使うようにアプリケーションを構成する

専用ゲートウェイをプロビジョニングすると、統合キャッシュが自動的に作成されます。 統合キャッシュを使用する必要がない場合は、Azure Cosmos DB を使用するすべてのアプリケーションを専用ゲートウェイに接続する必要はありません。 専用ゲートウェイを追加しても、Azure Cosmos DB に接続するための既存の方法には影響しません。 たとえば、一方の CosmosClient 接続で、ゲートウェイ モードと専用ゲートウェイ エンドポイントを使用し、他方の CosmosClient でダイレクト モードを使用できます。

ロールベースのアクセス制御による認証

専用ゲートウェイでは、Azure Cosmos DB と同じアクセス許可、ロール定義、ロール割り当てが使用されます。 Azure Cosmos DB アカウントにデータ プレーン操作用に構成されたロールベースのアクセス制御 (RBAC) が既にある場合は、専用ゲートウェイに対する認証にもそれを使用できます。 詳細については、RBAC for Azure Cosmos DB データ プレーンの操作に関する記事を参照してください。

専用ゲートウェイ エンドポイント、資格情報を設定し、ゲートウェイ接続モードを構成して、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 分です。

Note

MaxIntegratedCacheStaleness は最高 10 年まで設定できます。 実際には、この値は最大期限延長であり、発生する可能性のあるノードの再起動によって、キャッシュのリセットがそれより早く行われる可能性があります。

MaxIntegratedCacheStaleness の調整は、各 SDK の次のバージョンでサポートされています。

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 を変更すると、すべての要求が専用ゲートウェイ経由でルーティングされます。

読み取り要求 (ポイント読み取りまたはクエリ) で統合キャッシュを利用するには、次のすべての条件が満たされている必要があります。

• クライアントが専用ゲートウェイ エンドポイントに接続している
• クライアントがゲートウェイ モードを使用している (Python と Node.js の SDK では、常にゲートウェイ モードが使用されています)
• 要求の整合性を、session または eventual に設定する必要があります。

Note

統合キャッシュについてフィードバックはありますか? ご意見をお待ちしています。 フィードバックは、Azure Cosmos DB エンジニアリング チーム (cosmoscachefeedback@microsoft.com) と直接共有できます

次の手順

• 統合キャッシュのよくあるご質問
• 統合キャッシュの概要
• 専用ゲートウェイ