Azure Cosmos DB 통합 캐시를 구성하는 방법

아티클
11/01/2024

적용 대상: NoSQL

이 문서에서는 전용 게이트웨이를 프로비저닝하고, 통합 캐시를 구성하고, 애플리케이션을 연결하는 방법을 설명합니다.

필수 조건

Azure 구독이 아직 없는 경우 시작하기 전에 체험 계정을 만듭니다.
Azure Cosmos DB를 사용하는 기존 애플리케이션입니다. 계정이 없는 경우 여기에 몇 가지 예가 있습니다.
기존 Azure Cosmos DB API for NoSQL 계정.

전용 게이트웨이 프로비전

Azure Portal에서 Azure Cosmos DB 계정으로 이동하고 전용 게이트웨이 탭을 선택합니다.
다음 세부 정보로 전용 게이트웨이 양식을 작성합니다.
- 전용 게이트웨이 - 프로비저닝됨으로 토글을 켭니다.
- SKU - 필요한 컴퓨팅 및 메모리 크기가 있는 SKU를 선택합니다. 통합 캐시는 메모리의 약 50%를 사용하며 나머지 메모리는 메타데이터 및 백 엔드 파티션으로의 라우팅 요청에 사용됩니다.
- 인스턴스 수 - 노드 수입니다. 개발 목적을 위해 D4 크기의 노드 하나에서 시작하는 것이 좋습니다. 캐시하고 고가용성을 달성하기 위해 필요한 데이터 양에 따라 초기 테스트 후 노드 크기를 늘릴 수 있습니다.
저장을 선택하고 전용 게이트웨이 프로비저닝이 완료될 때까지 약 5~10분 정도 기다립니다. 프로비저닝이 완료되면 다음 알림이 표시됩니다.

통합 캐시를 사용하도록 애플리케이션 구성

전용 게이트웨이를 프로비전하면 통합 캐시가 자동으로 만들어집니다. 통합 캐시를 사용할 필요가 없는 경우 Azure Cosmos DB를 사용하는 모든 애플리케이션을 전용 게이트웨이에 연결할 필요가 없습니다. 전용 게이트웨이를 추가해도 Azure Cosmos DB에 연결하는 기존 방법에는 영향을 주지 않습니다. 예를 들어, 하나의 CosmosClient는 게이트웨이 모드와 전용 게이트웨이 엔드포인트를 사용하여 연결하고 다른 CosmosClient는 직접 모드를 사용할 수 있습니다.

역할 기반 액세스 제어를 사용하여 인증

전용 게이트웨이는 Azure Cosmos DB와 동일한 권한, 역할 정의 및 역할 할당을 사용합니다. Azure Cosmos DB 계정의 데이터 평면 작업에 대해 RBAC(역할 기반 액세스 제어)가 이미 구성된 경우 전용 게이트웨이에 인증하는 데 사용할 수도 있습니다. Azure Cosmos DB 데이터 평면 작업에 대한 RBAC에 대해 알아봅니다.

CosmosClient 전용 게이트웨이 엔드포인트, 자격 증명을 설정하고 게이트웨이 연결 모드를 구성하여 구성합니다. 모든 전용 게이트웨이 엔드포인트는 동일한 패턴을 따릅니다. 원래 엔드포인트sqlx.cosmos.azure.com에서 제거하고 documents.azure.com . 전용 게이트웨이는 제거한 후 다시 프로비전하더라도 항상 동일한 엔드포인트를 갖습니다.

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

Important

직접 연결 모드는 .NET SDK의 기본값입니다. 전용 게이트웨이를 사용하도록 게이트웨이 모드를 명시적으로 구성해야 합니다.

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

Important

직접 연결 모드는 Java SDK의 기본값입니다. 전용 게이트웨이를 사용하도록 게이트웨이 모드를 명시적으로 구성해야 합니다.

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

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

endpoint = "<dedicated-gateway-endpoint>"

credential = DefaultAzureCredential()

client = CosmosClient(endpoint, credential=credential)

연결 문자열 인증

새 전용 게이트웨이 엔드포인트를 사용하도록 애플리케이션의 연결 문자열을 수정합니다.

업데이트된 전용 게이트웨이 연결 문자열은 키 블레이드에 있습니다.

모든 전용 게이트웨이 연결 문자열은 동일한 패턴을 따릅니다. 원래 연결 문자열에서 documents.azure.com을 제거하고 sqlx.cosmos.azure.com으로 바꿉니다. 전용 게이트웨이는 제거했다가 다시 프로비저닝하더라도 항상 동일한 연결 문자열을 갖습니다.
.NET 또는 Java SDK를 사용하는 경우 연결 모드를 게이트웨이 모드로 설정합니다. Python 및 Node.js SDK에는 게이트웨이 모드 외에 추가 연결 옵션이 없기 때문에 이 단계가 필요하지 않습니다.

Important

최신 .NET 또는 Java SDK 버전을 사용하는 경우 기본 연결 모드는 직접 모드입니다. 통합 캐시를 사용하려면 이 기본값을 재정의해야 합니다.

요청 일관성 조정

요청 일관성이 세션인지 또는 최종인지 확인해야 합니다. 그러지 않으면 요청은 항상 통합 캐시를 바이패스합니다. 모든 읽기 작업에 대해 특정 일관성을 구성하는 가장 쉬운 방법은 계정 수준에서 설정하는 것입니다. 또한 요청 수준에서 일관성을 구성할 수도 있습니다. 이는 읽기의 하위 집합만 통합 캐시를 활용하려는 경우에 권장됩니다.

MaxIntegratedCacheStaleness 조정

부실 캐시 데이터를 허용할 최대 시간인 MaxIntegratedCacheStaleness를 구성합니다. 반복되는 지점 읽기 및 쿼리가 캐시 적중이 될 가능성이 높아지므로 MaxIntegratedCacheStaleness를 최대한 높게 설정하는 것이 좋습니다. MaxIntegratedCacheStaleness를 0으로 설정하면 일관성 수준에 관계없이 읽기 요청이 통합 캐시를 전혀 사용하지 않습니다. 구성되지 않은 경우 MaxIntegratedCacheStaleness 기본값은 5분입니다.

참고 항목

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

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

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

캐시 적중 확인

마지막으로 애플리케이션을 다시 시작하고 요청 요금이 0인지 확인하여 반복된 포인트 읽기 또는 쿼리에 대한 통합 캐시 적중을 확인할 수 있습니다. 전용 게이트웨이 엔드포인트를 사용하도록 CosmosClient를 수정하면 모든 요청이 전용 게이트웨이를 통해 라우팅됩니다.

읽기 요청(포인트 읽기 또는 쿼리)에서 통합 캐시를 활용하려면 다음 기준이 모두 충족되어야 합니다.

클라이언트가 전용 게이트웨이 엔드포인트에 연결됩니다.
클라이언트가 게이트웨이 모드를 사용합니다(Python 및 Node.js SDK는 항상 게이트웨이 모드를 사용함).
요청에 대한 일관성은 세션 또는 최종으로 설정되어야 합니다.

참고 항목

통합 캐시에 관한 피드백이 있나요? 많은 의견 부탁드립니다. 언제든지 자유롭게 Azure Cosmos DB 엔지니어링 팀(cosmoscachefeedback@microsoft.com)과 피드백을 직접 공유해 주세요.

다음을 통해 공유

Azure Cosmos DB 통합 캐시를 구성하는 방법

필수 조건

전용 게이트웨이 프로비전

통합 캐시를 사용하도록 애플리케이션 구성

역할 기반 액세스 제어를 사용하여 인증

연결 문자열 인증

요청 일관성 조정

MaxIntegratedCacheStaleness 조정

통합 캐시 무시

캐시 적중 확인

다음 단계

피드백

추가 리소스