統合キャッシュを有効にする

完了

統合キャッシュの有効化

統合キャッシュの有効化は、次の 2 つの主要ステップで行います。

• Azure Cosmos DB for NoSQL アカウントで専用ゲートウェイを作成する
• 要求にゲートウェイを使用するように SDK コードを更新する

専用ゲートウェイを作成する

まず、アカウント内に専用ゲートウェイをプロビジョニングする必要があります。 このアクションは、ポータルと [Dedicated Gateway](専用ゲートウェイ) ペインを使用して実行できます。

プロビジョニング プロセスの一環として、ゲートウェイ インスタンスの数と SKU を構成することが求められます。 これらの設定により、ノードの数と、各ゲートウェイ ノードのコンピューティングとメモリのサイズが決まります。 後で、キャッシュする必要があるデータ量が増えたら、ノードと SKU の数を変更できます。

新しいゲートウェイのプロビジョニングが完了すると、そのゲートウェイのエンドポイントを取得できるようになります。

Note

このゲートウェイ エンドポイントは、Azure Cosmos DB for NoSQL クライアントで使用される一般的なエンドポイントとは異なります。

.NET SDK コードを更新する

.NET SDK クライアントで統合キャッシュを使用するには、次の 3 つに該当することを確認する必要があります。

• クライアントは、一般的なエンドポイントの代わりに専用ゲートウェイ エンドポイントを使用します
• クライアントは、既定の直接接続モードではなくゲートウェイ モードを使用するように構成されている
• クライアントの一貫性レベルは、[セッション] または [最終的] に設定されている必要がある

まず、エンドポイントが専用ゲートウェイのエンドポイントに設定されていることを確認します。 通常、Azure Cosmos DB for NoSQL エンドポイントの形式は <cosmos-account-name>.documents.azure.com となります。 専用ゲートウェイの場合、エンドポイントの構造は <cosmos-account-name>.sqlx.cosmos.azure.com となります。

アカウント キーを使用する代わりに、認証にマネージド ID を使用するように SDK を構成します。 更新されたコードは次のとおりです。

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

string endpoint = "https://<cosmos-account-name>.sqlx.cosmos.azure.com/";

CosmosClientOptions options = new()
{
    ConnectionMode = ConnectionMode.Gateway,
    ConsistencyLevel = ConsistencyLevel.Session // or ConsistencyLevel.Eventual
};

// Use DefaultAzureCredential to authenticate with managed identity.
CosmosClient client = new(endpoint, new DefaultAzureCredential(), options);

Note

アプリケーションでマネージド ID が有効になっており、そのマネージド ID に Azure Cosmos DB アカウントの Cosmos DB 組み込みデータ共同作成者ロールが付与されていることを確認します。

ポイント読み取り操作を構成する

統合キャッシュを使用するようにポイント読み取り操作を構成するには、ItemRequestOptions 型のオブジェクトを作成する必要があります。 このオブジェクトでは、ConsistencyLevel プロパティを ConsistencyLevel.Session または ConsistencyLevel.Eventual に手動で設定できます。 その後、ReadItemAsync メソッド呼び出しでオプション変数を使用できます。

string id = "9DB28F2B-ADC8-40A2-A677-B0AAFC32CAC8";
PartitionKey partitionKey = new("56400CF3-446D-4C3F-B9B2-68286DA3BB99");

ItemRequestOptions requestOptions = new()
{
    ConsistencyLevel = ConsistencyLevel.Session
};

ItemResponse<Product> response = await container.ReadItemAsync<Product>(id, partitionKey, requestOptions: requestOptions);

RU の使用状況を確認するには、応答変数の RequestCharge プロパティを使用します。 この読み取り操作の最初の呼び出しでは、予想される要求ユニット数が使用されます。 この例では、それはポイント読み取り操作に対して 1 RU となります。 後続の要求では、データはキャッシュの有効期限が切れるまでキャッシュからプルされるため、要求ユニットは一切使用されません。

Console.WriteLine($"Request charge:\t{response.RequestCharge:0.00} RU/s");

クエリを構成する

統合キャッシュを使用するようにクエリを構成するには、QueryRequestOptions 型のオブジェクトを作成します。 このオブジェクトでは、整合性レベルも手動で変更する必要があります。 次に、オプション変数を GetItemQueryIterator メソッド呼び出しに渡します。

string sql = "SELECT * FROM products";
QueryDefinition query = new(sql);

QueryRequestOptions queryOptions = new()
{
    ConsistencyLevel = ConsistencyLevel.Eventual
};

FeedIterator<Product> iterator = container.GetItemQueryIterator<Product>(query, requestOptions: queryOptions);

また、結果の各ページに関連付けられている各 FeedResponse オブジェクトの RequestCharge プロパティを取得することで、RU の使用状況を確認することもできます。 要求料金を集計すると、クエリ全体の合計要求料金を取得することになります。 ポイント読み取りと同様に、最初のクエリでは一般的な要求ユニット数が使用されます。 追加のクエリでは、キャッシュ内のデータの有効期限が切れるまで、要求ユニットは使用されません。

double totalRequestCharge = 0;
while(iterator.HasMoreResults)
{
    FeedResponse<Product> response = await iterator.ReadNextAsync();
    totalRequestCharge += response.RequestCharge;
    Console.WriteLine($"Request charge:\t\t{response.RequestCharge:0.00} RU/s");
}

Console.WriteLine($"Total request charge:\t{totalRequestCharge:0.00} RU/s");