Tutorial: Configuración de la distribución global de Azure Cosmos DB mediante la API para NoSQL

  • Artículo

SE APLICA A: NoSQL

En este artículo se muestra cómo usar Azure Portal para configurar la distribución global de Azure Cosmos DB y luego conectarse mediante la API para NoSQL.

En este artículo se tratan las tareas siguientes:

  • Configuración de la distribución global con Azure Portal
  • Configuración de la distribución global con la API para NoSQL

Incorporación de regiones a la base de datos global mediante Azure Portal

Azure Cosmos DB está disponible en todas las regiones de Azure globales. Tras seleccionar el nivel de coherencia predeterminado para la cuenta de base de datos, puede asociar una o varias regiones (según la elección del nivel de coherencia y las necesidades de distribución global).

  1. En la barra izquierda de Azure Portal, haga clic en Azure Cosmos DB.

  2. En la página Azure Cosmos DB, seleccione la cuenta de base de datos que quiere modificar.

  3. En la página de la cuenta, haga clic en Replicar datos globalmente en el menú.

  4. En la página Replicar datos globalmente, seleccione las regiones que quiere agregar o quitar haciendo clic en ellas en el mapa y, después, haga clic en Guardar. Agregar regiones conlleva un costo; consulte la página de precios o el artículo Distribución de datos global con Azure Cosmos DB para más información.

    Haga clic en las regiones en el mapa para agregarlas o quitarlas

Cuando agrega una segunda región, se habilita la opción Conmutación por error manual en la página Replicar datos globalmente del portal. Puede usar esta opción para probar el proceso de conmutación por error o cambiar la región de escritura principal. Cuando agrega una tercera región, la opción Prioridades de conmutación por error se habilita en la misma página para que pueda cambiar el orden de la conmutación por error en las lecturas.

Selección de regiones de la base de datos global

Hay dos escenarios comunes para configurar dos o más regiones:

  1. Proporcionar acceso de baja latencia a los datos a los usuarios finales, independientemente de la región del mundo en la que se encuentren.
  2. Agregar resistencia regional para la continuidad empresarial y la recuperación ante desastres (BCDR).

Para proporcionar latencia baja a los usuarios finales, se recomienda implementar la aplicación y Azure Cosmos DB en las regiones correspondientes a la ubicación de los usuarios de la aplicación.

En el caso de BCDR, se recomienda agregar las regiones en función de los pares de regiones descritos en el artículo Replicación entre regiones de Azure: Continuidad empresarial y recuperación ante desastres.

Conexión a una región de preferencia con la API para NoSQL

Para aprovechar las ventajas de la distribución global, las aplicaciones cliente pueden especificar la lista del orden de preferencia de regiones que se usará para llevar a cabo operaciones de documentos. Según la configuración de la cuenta de Azure Cosmos DB, la disponibilidad regional actual y la lista de preferencias especificada, el SDK de SQL elegirá el punto de conexión óptimo para realizar las operaciones de lectura y escritura.

Esta lista de preferencias se especifica cuando se inicializa una conexión mediante los SDK de SQL. Los SDK aceptan un parámetro opcional PreferredLocations, que es una lista ordenada de regiones de Azure.

El SDK enviará automáticamente todas las escrituras a la región de escritura actual. Todas las lecturas se enviarán a la primera región disponible de la lista de ubicaciones preferidas. Si se produce un error en la solicitud, el cliente pasará a la siguiente región de la lista.

Los SDK solo intentarán leer en las regiones especificadas en las ubicaciones preferidas. Así que, por ejemplo, si la cuenta de Azure Cosmos DB está disponible en cuatro regiones, pero el cliente solo especifica dos regiones de lectura (no escritura) en PreferredLocations, no se atenderá ninguna lectura desde la región de lectura que no se especifique en PreferredLocations. Si las regiones de lectura especificadas en PreferredLocations no están disponibles, las lecturas se atenderán fuera de la región de escritura.

La aplicación puede comprobar los puntos de conexión de escritura y lectura actuales elegidos por el SDK. Para ello, comprueba dos propiedades, WriteEndpoint y ReadEndpoint, disponibles en el SDK 1.8 y versiones posteriores. Si la propiedad PreferredLocations no está establecida, atenderá todas las solicitudes procedentes de la región de escritura actual.

Si no se especifican las ubicaciones preferidas pero se usa el método setCurrentLocation, el SDK rellena automáticamente las ubicaciones preferidas en función de la región actual en la que se ejecute el cliente. El SDK ordena las regiones en función de la proximidad de una región a la región actual.

.NET SDK

Se puede usar el SDK sin cambiar el código. En este caso, el SDK dirige automáticamente tanto las lecturas como las escrituras a la región de escritura actual.

En la versión 1.8 y posteriores del SDK de .NET, el parámetro ConnectionPolicy para el constructor DocumentClient tiene una propiedad denominada Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations. Esta propiedad es del tipo Collection <string> y debería contener una lista de nombres de región. Se da formato a los valores de cadena según la columna de nombre de región en la página Regiones de Azure, sin espacios antes ni después del primer o el último carácter, respectivamente.

Los puntos de conexión de lectura y escritura actuales están disponibles en DocumentClient.ReadEndpoint y DocumentClient.WriteEndpoint, respectivamente.

Nota:

Las direcciones URL de los puntos de conexión no deben considerarse constantes de larga duración. El servicio puede actualizarlas en cualquier momento. El SDK administra este cambio automáticamente.

Si emplea el SDK de .NET v2, use la propiedad PreferredLocations para establecer la región preferida.

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

Como alternativa, puede usar la propiedad SetCurrentLocation y dejar que el SDK elija la ubicación preferida en función de la proximidad.

// 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 o JavaScript

Nota:

Las direcciones URL de los puntos de conexión no deben considerarse constantes de larga duración. El servicio puede actualizarlas en cualquier momento. El SDK administrará este cambio automáticamente.

A continuación, se muestra un ejemplo de código para Node.js y 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 de Python

El siguiente código muestra cómo establecer ubicaciones preferidas con el SDK de Python:

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

SDK de Java V4

El siguiente código muestra cómo establecer las ubicaciones preferidas con el SDK de Java:

SDK para Java V4 (Maven com.azure::azure-cosmos) API asincrónica


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

Conector de Spark 3

Puede definir la lista regional preferida mediante la configuraciónspark.cosmos.preferredRegionsList; por ejemplo:

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

REST

Una vez que una cuenta de base de datos está disponible en varias regiones, los clientes pueden consultar su disponibilidad llevando a cabo una solicitud GET en este URI https://{databaseaccount}.documents.azure.com/

El servicio devolverá una lista de regiones y los URI de punto de conexión de Azure Cosmos DB correspondientes para las réplicas. Se indicará la región de escritura actual en la respuesta. Después, el cliente puede seleccionar el punto de conexión adecuado para las demás solicitudes de API de REST como sigue.

Respuesta de ejemplo

{
    "_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
}
  • Todas las solicitudes PUT, POST y DELETE deben ir al URI de escritura indicado.
  • Todas las solicitudes GET y otras solicitudes de solo lectura (como las consultas) pueden ir a cualquier punto de conexión elegido por el cliente.

Las solicitudes de escritura a regiones de solo lectura producirán un error con el código de error HTTP 403 ("Prohibido").

Si la región de escritura cambia después de la fase de descubrimiento inicial del cliente, se producirá un error en las escrituras posteriores en la región de escritura anterior con el código de error HTTP 403 ("Prohibido"). A continuación, el cliente debería de nuevo conseguir con GET la lista de regiones para obtener la región de escritura actualizada.

De este modo finaliza este tutorial. Para información sobre cómo administrar la coherencia de la cuenta replicada globalmente, lea Niveles de coherencia en Azure Cosmos DB. Para más información sobre cómo funciona la replicación global de bases de datos en Azure Cosmos DB, consulte Distribución global de datos con Azure Cosmos DB.

Pasos siguientes

En este tutorial, ha hecho lo siguiente:

  • Configuración de la distribución global con Azure Portal
  • Configuración de la distribución global con la API para NoSQL

Ahora puede continuar en el tutorial siguiente para aprender a desarrollar localmente con el emulador local de Azure Cosmos DB.

Desarrollo local con el emulador

¿Intenta planear la capacidad de una migración a Azure Cosmos DB? Para ello, puede usar información sobre el clúster de bases de datos existente.