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

  • Статья

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

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

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

Добавление регионов глобальной базы данных с помощью портала 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);

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,
    credential,
    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);

ConnectionPolicy connectionPolicy = new ConnectionPolicy();

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

// initialize connection
DocumentClient docClient = new DocumentClient(
    accountEndPoint,
    credential,
    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, aadCredentials: tokenCredential, connectionPolicy: { preferredLocations } });

Пакет SDK для Python

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

connectionPolicy = documents.ConnectionPolicy()
connectionPolicy.PreferredLocations = ['West US', 'East US', 'North Europe']
client = cosmos_client.CosmosClient(ENDPOINT, credential=token_credential, connectionPolicy)

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

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

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

CosmosAsyncClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .credential(tokenCredential)
                .preferredRegions(preferredRegions)
                .contentResponseOnWriteEnabled(true)
                .buildAsyncClient();

Соединитель Spark 3

Вы можете определить предпочтительный региональный список с помощью spark.cosmos.preferredRegionsList конфигурации, например:

val sparkConnectorConfig = Map(
  "spark.cosmos.accountEndpoint" -> cosmosEndpoint,
  "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, Для планирования ресурсов можно использовать сведения об имеющемся кластере базы данных.