Руководство. Настройка глобального распределения Azure Cosmos DB с помощью API для NoSQL

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: NoSQL

В этой статье мы покажем, как с помощью портал Azure настроить глобальное распределение Azure Cosmos DB, а затем подключиться с помощью API для NoSQL.

В этой статье рассматриваются следующие задачи:

  • настроили глобальное распределение на портале Azure;
  • Настройка глобального распределения с помощью API для NoSQLs

Добавление регионов глобальной базы данных с помощью портала Azure

Служба Azure Cosmos DB доступна во всех регионах Azure по всему миру. После выбора уровня согласованности по умолчанию для учетной записи базы данных вы можете связать один или несколько регионов (в зависимости от выбранного уровня согласованности по умолчанию и потребностей глобального распространения).

  1. На левой панели на портале Azure щелкните Azure Cosmos DB.

  2. На странице Azure Cosmos DB выберите учетную запись базы данных, которую нужно изменить.

  3. На странице учетной записи в меню щелкните Глобальная репликация данных.

  4. На странице Глобальная репликация данных выберите регионы для добавления или удаления, щелкнув их на карте, и нажмите кнопку Сохранить. Добавление регионов оплачивается. Дополнительные сведения см. на странице цен или в руководстве по глобальному распространению данных с помощью Azure Cosmos DB.

    Можно щелкать регионы на карте, чтобы добавить или удалить их.

Когда вы добавите второй регион, на портале на странице Глобальная репликация данных активируется параметр Ручная отработка отказа. Этот параметр можно использовать для тестирования отработки отказа или изменения основного региона записи. После добавления третьего региона на той же странице активируется параметр Приоритеты при отработке отказа. Он позволяет изменить порядок отработки отказов для операций чтения.

Выбор регионов глобальной базы данных

Существуют два распространенных сценария настройки нескольких регионов:

  1. Обеспечение низкой задержки при обращении пользователей к данным по всему миру не зависимо от расположения.
  2. Добавление региональной устойчивости для непрерывности бизнес-процессов и аварийного восстановления (BCDR)

Чтобы обеспечить низкую задержку для пользователей, мы советуем развернуть приложение и Azure Cosmos DB в регионы, соответствующие расположению пользователей приложения.

Для BCDR мы рекомендуем добавлять регионы исходя из пар регионов, описанных в статье Репликация между регионами в Azure. Непрерывность бизнес-процессов и аварийное восстановление.

Подключение к предпочтительному региону с помощью API для NoSQL

Чтобы воспользоваться преимуществами глобального распределения, клиентские приложения могут указать упорядоченный список предпочитаемых регионов, который будет использоваться для операций с документами. Для операций записи и чтения с помощью пакета SDK для SQL выбирается наиболее оптимальная конечная точка на основании текущих данных о региональной доступности и списка предпочтений, указанного в конфигурации учетной записи Azure Cosmos DB.

Этот список предпочтений указывается при инициализации подключения с помощью пакетов SDK для SQL. Пакеты SDK принимают необязательный параметр PreferredLocations, представляющий собой упорядоченный список регионов Azure.

Пакет SDK будет автоматически отправлять все операции записи в текущий регион записи. Все операции чтения будут отправляться в первый доступный регион из списка предпочтительных расположений. Если запрос завершится неудачей, клиент перейдет к следующему региону дальше по списку.

Пакеты SDK будут пытаться выполнять чтение данных из регионов, указанных в списке предпочтительных расположений. Например, если учетная запись Azure Cosmos DB доступна в четырех регионах, но клиент указывает только два региона чтения (без записи) в PreferredLocations, то операции чтения не будут обслуживаться из области чтения, которая не указана в PreferredLocations. Если указанные в PreferredLocations регионы не доступны, операции чтения обслуживаются в регионе записи.

Приложение может проверить текущие конечную точку записи и конечную точку чтения, выбранные пакетом SDK, просмотрев два свойства, WriteEndpoint и ReadEndpoint, доступные в SDK 1.8 и более поздней версии. Если свойство PreferredLocations не задано, будут обслуживаться все запросы из текущего региона записи.

Если не указать предпочтительные расположения, используя метод setCurrentLocation, пакет SDK автоматически заполняет предпочтительные расположения в зависимости от текущего региона, в котором работает клиент. Пакет SDK упорядочивает регионы на основе близости региона к текущему региону.

Пакет SDK для .NET

Пакет SDK можно использовать без изменения кода. В этом случае пакет SDK автоматически направляет операции чтения и записи в текущий регион записи.

В пакете SDK для .NET 1.8 и более поздней версии параметр ConnectionPolicy конструктора DocumentClient имеет свойство Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations. Это свойство имеет тип коллекции <string> и должно содержать список имен регионов. Строковые значения форматируются по столбцу "Имя региона" на странице Регионы Azure без пробелов до или после первого и последнего знака соответственно.

Текущие конечные точки записи и чтения доступны в DocumentClient.WriteEndpoint и DocumentClient.ReadEndpoint, соответственно.

Примечание

Не следует считать URL-адреса конечных точек долговременными константами. Служба может обновить их в любой момент. Пакет SDK обрабатывает это изменение автоматически.

Если вы используете пакет SDK для .NET версии 2, примените свойство 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-адреса конечных точек долговременными константами. Служба может обновить их в любой момент. Пакет 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 } });

Пакет SDK для Python

В коде ниже показано, как задать требуемое расположение с помощью пакета SDK для Python.

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

Пакет SDK для Java версии 4

В коде ниже показано, как задать требуемое расположение с помощью пакета SDK для Java.

Асинхронный API пакета SDK для Java версии 4 (Maven com.azure::azure-cosmos)


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

Соединитель Spark 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

После того, как учетная запись базы данных станет доступной в нескольких регионах, клиенты смогут запрашивать ее доступность с помощью запроса GET к универсальному коду ресурса (URI) https://{databaseaccount}.documents.azure.com/.

Служба вернет список регионов и соответствующих универсальных кодов ресурса (URI) конечных точек Azure Cosmos DB для реплик. В ответе будет указан текущий регион записи. Затем клиент сможет выбрать подходящую конечную точку для всех последующих запросов 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 (Forbidden).

В случае изменения региона записи после того, как клиент выполнил этап начального обнаружения, все последующие операции записи в предыдущий регион записи завершатся ошибкой с кодом HTTP 403 (Forbidden). Клиенту следует еще раз получить список регионов (запрос GET), чтобы получить обновленный регион записи.

На этом руководство завершено. Сведения об управлении согласованностью глобально реплицируемой учетной записи Azure Cosmos DB см. в этой статье. Сведения о том, как функционирует репликация глобальной базы данных в Azure Cosmos DB, см. в статье о глобальном распределении данных в Azure Cosmos DB.

Дальнейшие действия

В этом руководстве вы выполнили следующее:

  • настроили глобальное распределение на портале Azure;
  • Настройка глобального распределения с помощью API для NoSQLs

Перейдите к следующему руководству, чтобы узнать о разработке в локальной среде с помощью локального эмулятора Azure Cosmos DB.

Разработка в локальной среде с помощью эмулятора

Пытаетесь выполнить планирование ресурсов для миграции в Azure Cosmos DB? Можете использовать для этого сведения о существующем кластере базы данных.