자습서: NoSQL용 API를 사용하여 Azure Cosmos DB 전역 배포 설정

  • 아티클

적용 대상: NoSQL

이 문서에서는 Azure Portal을 사용하여 Azure Cosmos DB 글로벌 배포를 설정한 다음, NoSQL용 API를 사용하여 연결하는 방법을 보여 줍니다.

이 문서에서 다루는 작업은 다음과 같습니다.

  • Azure Portal을 사용하여 전역 배포 구성
  • NoSQL용 API를 사용하여 전역 배포 구성

Azure Portal을 사용하여 글로벌 데이터베이스 지역 추가

Azure Cosmos DB는 전 세계의 모든 Azure 지역에서 사용할 수 있습니다. 데이터베이스 계정에서 기본 일관성 수준을 선택한 후에는 (선택한 기본 일관성 수준 및 글로벌 배포 수요에 따라) 하나 이상의 지역을 연결합니다.

  1. Azure Portal의 왼쪽 막대에서 Azure Cosmos DB를 클릭합니다.

  2. Azure Cosmos DB 페이지에서 수정할 데이터베이스 계정을 선택합니다.

  3. 계정 페이지의 메뉴에서 전역적으로 데이터 복제를 클릭합니다.

  4. 전역으로 데이터 복제 페이지에서 맵의 지역을 클릭하여 추가 또는 제거할 지역을 선택하고 저장을 클릭합니다. 지역을 추가하는 비용에 대한 자세한 내용은 가격 책정 페이지 또는 Azure Cosmos DB를 사용하여 전역적으로 데이터 배포 문서를 참조하세요.

    Click the regions in the map to add or remove them

두 번째 하위 지역을 추가하면 포털의 전역으로 데이터 복제 페이지에서 수동 장애 조치 옵션 사용이 설정됩니다. 장애 조치 프로세스를 테스트하거나 기본 쓰기 지역을 변경하려면 이 옵션을 사용할 수 있습니다. 세 번째 하위 지역을 추가하면 동일한 페이지에서 장애 조치 우선 순위 옵션 사용이 설정되므로 읽기의 장애 조치 순서를 변경할 수 있습니다.

글로벌 데이터베이스 지역 선택

둘 이상의 지역을 구성하기 위한 두 가지 일반적인 시나리오는 다음과 같습니다.

  1. 전세계 어느 위치에 있든 관계 없이 최종 사용자에게 낮은 대기 시간으로 데이터 액세스 제공
  2. BCDR(무중단 업무 방식 및 재해 복구)를 위한 지역 복원 기능 추가

최종 사용자에게 낮은 대기 시간을 제공하기 위해서는 애플리케이션 사용자가 있는 위치와 동일한 지역에 애플리케이션과 Azure Cosmos DB를 모두 배포하는 것이 좋습니다.

BCDR의 경우 Azure의 교차 지역 복제: 비즈니스 연속성 및 재해 복구 문서에 설명된 지역 쌍을 기반으로 지역을 추가하는 것이 좋습니다.

NoSQL용 API를 사용하여 기본 설정 지역에 연결

전역 배포를 활용하기 위해 클라이언트 애플리케이션은 문서 작업을 수행하는 데 사용할 정렬된 기본 지역 목록을 지정할 수 있습니다. SQL SDK에서 Azure Cosmos DB 계정 구성, 현재 지역 가용성 및 지정된 기본 설정 목록을 기반으로 하여 쓰기 및 읽기 작업을 수행하는 데 가장 적합한 엔드포인트를 선택합니다.

이 기본 설정 목록은 SQL SDK를 사용하여 연결을 초기화할 때 지정됩니다. SDK는 Azure 지역의 정렬된 목록인 선택적 매개 변수 PreferredLocations를 수락합니다.

SDK는 현재 쓰기 지역에 모든 쓰기를 자동 전송합니다. 모든 읽기는 기본 설정 위치 목록에서 사용 가능한 첫 번째 지역으로 전송됩니다. 요청이 실패하면 클라이언트는 목록을 다음 지역으로 옮겨갑니다.

SDK는 기본 설정 위치에 지정된 지역에서만 읽기를 시도합니다. 따라서 예를 들어 Azure Cosmos DB 계정이 4개 지역에서 사용될 수 있지만 클라이언트가 PreferredLocations 내에서 2개의 읽기(쓰기 아님) 지역만 지정한 경우, PreferredLocations에 지정되지 않은 읽기 지역에서 읽기를 제공하지 않습니다. PreferredLocations 목록에 지정된 읽기 영역을 사용할 수 없는 경우 읽기는 쓰기 영역 외부로 처리됩니다.

애플리케이션은 SDK 버전 1.8 이상에서 사용 가능한 두 가지 속성(WriteEndpoint 및 ReadEndpoint)을 확인하여 SDK가 선택한 현재의 쓰기 엔드포인트와 읽기 엔드포인트를 확인할 수 있습니다. PreferredLocations 속성이 설정되지 않으면 모든 요청이 현재 쓰기 지역에서 제공됩니다.

기본 설정 위치를 지정하지 않고 setCurrentLocation 메서드를 사용하는 경우 SDK는 클라이언트가 실행 중인 현재 지역에 따라 기본 설정 위치를 자동으로 채웁니다. SDK는 현재 지역에 대한 지역의 근접성에 따라 지역을 정렬합니다.

.NET SDK

SDK는 코드 변경 없이 사용할 수 있습니다. 이 경우 SDK는 읽기와 쓰기를 현재 쓰기 하위 지역에 자동으로 가져옵니다.

.NET SDK의 1.8 버전 이상에서 DocumentClient 생성자의 ConnectionPolicy 매개 변수는 Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations라는 속성이 있습니다. 이 속성은 컬렉션 <string> 형식이며 지역 이름 목록을 포함합니다. 문자열 값은 Azure 지역 페이지의 지역 이름 열에 따라 서식이 지정되고 첫 글자와 마지막 글자 앞/뒤에 공백이 없습니다.

현재 읽기 및 쓰기 엔드포인트는 각각 DocumentClient.WriteEndpoint와 DocumentClient.ReadEndpoint에서 이용할 수 있습니다.

참고 항목

엔드포인트의 URL은 수명이 긴 상수로 간주하지 말아야 합니다. 서비스는 언제든지 이 URL을 업데이트할 수 있습니다. SDK가 이런 변경 내용을 자동으로 처리합니다.

.NET V2 SDK를 사용하는 경우 PreferredLocations 속성을 사용하여 기본 설정 지역을 설정합니다.

// Getting endpoints from application settings or other configuration location
Uri accountEndPoint = new Uri(Properties.Settings.Default.GlobalDatabaseUri);
string accountKey = Properties.Settings.Default.GlobalDatabaseKey;
  
ConnectionPolicy connectionPolicy = new ConnectionPolicy();

//Setting read region selection preference
connectionPolicy.PreferredLocations.Add(LocationNames.WestUS); // first preference
connectionPolicy.PreferredLocations.Add(LocationNames.EastUS); // second preference
connectionPolicy.PreferredLocations.Add(LocationNames.NorthEurope); // third preference

// initialize connection
DocumentClient docClient = new DocumentClient(
    accountEndPoint,
    accountKey,
    connectionPolicy);

// connect to DocDB
await docClient.OpenAsync().ConfigureAwait(false);

또는 SetCurrentLocation 속성을 사용하고 SDK에서 근접성에 따라 기본 설정 위치를 선택하도록 할 수 있습니다.

// Getting endpoints from application settings or other configuration location
Uri accountEndPoint = new Uri(Properties.Settings.Default.GlobalDatabaseUri);
string accountKey = Properties.Settings.Default.GlobalDatabaseKey;
  
ConnectionPolicy connectionPolicy = new ConnectionPolicy();

connectionPolicy.SetCurrentLocation("West US 2"); /

// initialize connection
DocumentClient docClient = new DocumentClient(
    accountEndPoint,
    accountKey,
    connectionPolicy);

// connect to DocDB
await docClient.OpenAsync().ConfigureAwait(false);

Node.js/JavaScript

참고 항목

엔드포인트의 URL은 수명이 긴 상수로 간주하지 말아야 합니다. 서비스는 언제든지 이 URL을 업데이트할 수 있습니다. SDK가 이런 변경 내용을 자동으로 처리합니다.

다음은 Node.js/JavaScript 코드 예제입니다.

// Setting read region selection preference, in the following order -
// 1 - West US
// 2 - East US
// 3 - North Europe
const preferredLocations = ['West US', 'East US', 'North Europe'];

// initialize the connection
const client = new CosmosClient{ endpoint, key, connectionPolicy: { preferredLocations } });

Python SDK

다음 코드는 Python SDK를 사용하여 기본 위치를 설정하는 방법을 보여줍니다.

connectionPolicy = documents.ConnectionPolicy()
connectionPolicy.PreferredLocations = ['West US', 'East US', 'North Europe']
client = cosmos_client.CosmosClient(ENDPOINT, {'masterKey': MASTER_KEY}, connectionPolicy)

Java V4 SDK

다음 코드는 Java SDK를 사용하여 기본 위치를 설정하는 방법을 보여줍니다.

Java SDK V4(Maven com.azure::azure-cosmos) Async API


ArrayList<String> preferredRegions = new ArrayList<String>();
preferredRegions.add("East US");
preferredRegions.add( "West US");
preferredRegions.add("Canada Central");

CosmosAsyncClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .key(MASTER_KEY)
                .preferredRegions(preferredRegions)
                .contentResponseOnWriteEnabled(true)
                .buildAsyncClient();

스파크 3 커넥터

spark.cosmos.preferredRegionsList구성을 사용하여 기본 설정하는 지역 목록을 정의할 수 있습니다. 예를 들면 다음과 같습니다.

val sparkConnectorConfig = Map(
  "spark.cosmos.accountEndpoint" -> cosmosEndpoint,
  "spark.cosmos.accountKey" -> cosmosMasterKey,
  "spark.cosmos.preferredRegionsList" -> "[West US, East US, North Europe]"
  // other settings
)

REST

데이터베이스 계정을 여러 지역에서 사용할 수 있게 되면 클라이언트는 이 URI https://{databaseaccount}.documents.azure.com/에서 GET 요청을 수행하여 가용성을 쿼리할 수 있습니다.

서비스에서 복제본에 대한 지역 목록과 해당 Azure Cosmos DB 엔드포인트 URI를 반환합니다. 현재 쓰기 지역이 응답에 표시됩니다. 클라이언트는 다음과 같이 모든 추가 REST API 요청에 알맞은 엔드포인트를 선택할 수 있습니다.

예제 응답

{
    "_dbs": "//dbs/",
    "media": "//media/",
    "writableLocations": [
        {
            "Name": "West US",
            "DatabaseAccountEndpoint": "https://globaldbexample-westus.documents.azure.com:443/"
        }
    ],
    "readableLocations": [
        {
            "Name": "East US",
            "DatabaseAccountEndpoint": "https://globaldbexample-eastus.documents.azure.com:443/"
        }
    ],
    "MaxMediaStorageUsageInMB": 2048,
    "MediaStorageUsageInMB": 0,
    "ConsistencyPolicy": {
        "defaultConsistencyLevel": "Session",
        "maxStalenessPrefix": 100,
        "maxIntervalInSeconds": 5
    },
    "addresses": "//addresses/",
    "id": "globaldbexample",
    "_rid": "globaldbexample.documents.azure.com",
    "_self": "",
    "_ts": 0,
    "_etag": null
}
  • 모든 PUT, POST 및 DELETE 요청은 표시된 쓰기 URI로 이동해야 합니다.
  • 모든 GET 및 다른 읽기 전용 요청(예: 쿼리)은 클라이언트가 선택한 엔드포인트로 이동할 수 있습니다.

읽기 전용 지역에 대한 쓰기 요청은 HTTP 오류 코드 403(“사용 권한 없음”)과 함께 실패합니다.

클라이언트의 최초 검색 단계 이후에 쓰기 지역이 변경되면 나중에 이전 쓰기 지역에 쓰려고 하면 HTTP 오류 코드 403("사용 권한 없음")과 함께 실패합니다. 클라이언트는 업데이트된 쓰기 지역을 가져오려면 지역 목록을 다시 가져와야 합니다.

이것으로 끝이며, 이 자습서를 완료했습니다! Azure Cosmos DB의 일관성 수준을 참조하여 전역적으로 복제한 계정의 일관성을 관리하는 방법에 대해 알아볼 수 있습니다. 그리고 Azure Cosmos DB에서 전역 데이터베이스 복제가 작동하는 방법에 대한 자세한 내용은 Azure Cosmos DB를 사용하여 전역적으로 데이터 배포를 참조하세요.

다음 단계

이 자습서에서는 다음을 수행했습니다.

  • Azure Portal을 사용하여 전역 배포 구성
  • NoSQL용 API를 사용하여 전역 배포 구성

이제 다음 자습서로 진행하여 Azure Cosmos DB 로컬 에뮬레이터를 사용하여 로컬로 개발하는 방법에 대해 자세히 알아볼 수 있습니다.

에뮬레이터를 사용하여 로컬로 개발

Azure Cosmos DB로 마이그레이션하기 위한 용량 계획을 수행하려고 하시나요? 용량 계획을 위해 기존 데이터베이스 클러스터에 대한 정보를 사용할 수 있습니다.