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

아티클
02/25/2024

적용 대상: NoSQL

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

필수 조건

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

전용 게이트웨이 프로비전

Azure Portal에서 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년으로 설정할 수 있습니다. 실제로 이 값은 최대 부실이며 발생할 수 있는 노드 다시 시작으로 인해 캐시가 더 빠르게 다시 설정될 수 있습니다.

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.35.0-preview
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를 수정하면 모든 요청이 전용 게이트웨이를 통해 라우팅됩니다.

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

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

참고 항목

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

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

필수 조건

전용 게이트웨이 프로비전

통합 캐시 구성

요청 일관성 조정

MaxIntegratedCacheStaleness 조정

통합 캐시 무시(미리 보기)

캐시 적중 확인

다음 단계

추가 리소스