Tutoriel : Configurer la distribution globale d’Azure Cosmos DB à l’aide de l’API pour NoSQL

  • Article

S’APPLIQUE À : NoSQL

Cet article montre comment utiliser le portail Azure pour configurer la diffusion mondiale d’Azure Cosmos DB, puis établir une connexion à l’aide de l’API pour NoSQL.

Cet article décrit les tâches suivantes :

  • Configurer la diffusion mondiale à l’aide du portail Azure
  • Configurer la diffusion mondiale à l’aide de l’API pour NoSQL

Ajouter des régions de bases de donnée mondiales à l’aide du portail Azure

Azure Cosmos DB est disponible dans toutes les régions Azure à travers le monde. Après avoir sélectionné le niveau de cohérence par défaut pour votre compte de base de données, vous pouvez associer une ou plusieurs régions (en fonction de votre choix de niveau de cohérence par défaut et de vos besoins de distribution mondiale).

  1. Dans la barre à gauche du portail Azure, cliquez sur Azure Cosmos DB.

  2. Dans la page Azure Cosmos DB, sélectionnez le compte de base de données à modifier.

  3. Dans la page du compte, cliquez sur Répliquer les données globalement à partir du menu.

  4. Dans la page Répliquer les données globalement, sélectionnez les régions à ajouter ou à supprimer en cliquant sur des régions sur la carte, puis cliquez sur Enregistrer. L’ajout de régions est payant. Pour plus d’informations, consultez la page de tarification ou l’article Distribution mondiale des données avec Azure Cosmos DB.

    Cliquez sur les régions dans la carte pour les ajouter ou les supprimer.

Une fois que vous ajoutez une deuxième région, l’option Basculement manuel est activée sur la page Répliquer les données globalement dans le portail. Vous pouvez utiliser cette option pour tester le processus de basculement ou modifier la région principale d’écriture. Une fois que vous ajoutez une troisième région, l’option Priorités de basculement est activée sur la même page afin que vous puissiez modifier l’ordre de basculement pour les lectures.

Sélection de régions de base de données mondiale

Il existe deux scénarios courants pour la configuration de deux ou plusieurs régions :

  1. La fourniture aux utilisateurs finaux d’un accès à faible latence aux données, où qu’ils se trouvent dans le monde
  2. L’ajout d’une résilience régionale pour la continuité d’activité et la reprise d’activité (BCDR)

Pour fournir une faible latence aux utilisateurs finaux, il est recommandé de déployer l’application et Azure Cosmos DB dans les régions correspondant à la localisation géographique des utilisateurs de l’application.

Pour BCDR, il est recommandé d’ajouter les régions en fonction des paires de régions décrites dans l’article Réplication interrégionale dans Azure : continuité de l’activité et reprise d’activité.

Connexion à une région de prédilection à l’aide de l’API pour NoSQL

Pour tirer parti de la distribution mondiale, les applications clientes peuvent spécifier la liste ordonnée de préférences de régions à utiliser pour effectuer des opérations sur les documents. Selon la configuration du compte Azure Cosmos DB, la disponibilité régionale actuelle et la liste de préférences spécifiée, le Kit de développement logiciel (SDK) SQL choisit le point de terminaison optimal pour les opérations de lecture et d’écriture.

Cette liste de préférences est spécifiée lors de l’initialisation d’une connexion à l’aide des SDK SQL. Les SDK acceptent un paramètre facultatif PreferredLocations qui est une liste ordonnée des régions Azure.

Le SDK envoie automatiquement toutes les écritures vers la région d’écriture en cours. Toutes les lectures sont envoyées vers la première région disponible dans la liste des emplacements préférés. Si la demande échoue, le client passe à la région suivante dans la liste.

Le SDK tente des opérations de lecture uniquement à partir des régions spécifiées dans les emplacements préférés. Ainsi, par exemple, si le compte Azure Cosmos DB est disponible dans quatre régions, mais que le client spécifie uniquement deux régions de lecture (sans écriture) dans PreferredLocations, aucune lecture n’est prise en charge en dehors de la région de lecture si elle n’est pas spécifiée dans PreferredLocations. Si les régions de lecture spécifiées dans la liste PreferredLocations ne sont pas disponibles, les lectures sont prises en charge en dehors de la région d’écriture.

L’application peut vérifier le point de terminaison d’écriture et le point de terminaison de lecture actuels choisis par le SDK en vérifiant deux propriétés, WriteEndpoint et ReadEndpoint, disponibles dans le SDK version 1.8 et ultérieure. Si la propriété PreferredLocations n’est pas définie, toutes les demandes seront traitées par la zone d’écriture en cours.

Si vous ne spécifiez pas les emplacements préférés, mais que vous avez utilisé la méthode setCurrentLocation, le SDK remplit automatiquement les emplacements préférés en fonction de la région actuelle dans laquelle le client se trouve. Le SDK ordonne les régions en fonction de la proximité d’une région par rapport à la région actuelle.

Kit de développement logiciel (SDK) .NET

Le SDK peut être utilisé sans aucune modification du code. Dans ce cas, le SDK dirige automatiquement les lectures et les écritures vers la région d’écriture en cours.

Dans la version 1.8 et ultérieure du SDK .NET, le paramètre ConnectionPolicy du constructeur DocumentClient comporte une propriété appelée Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations. Cette propriété est de type Collection <string> et doit contenir une liste des noms de région. Les valeurs de chaîne sont mises en forme en fonction de la colonne Nom de la région, dans la page Régions Azure, sans espaces avant ou après le premier et le dernier caractère, respectivement.

Les points de terminaison d’écriture et de lecture en cours sont disponibles dans DocumentClient.WriteEndpoint et DocumentClient.ReadEndpoint, respectivement.

Notes

Les URL des points de terminaison ne doivent pas être considérées comme des constantes à long terme. Le service peut les mettre à jour à tout moment. Le SDK gère ce changement automatiquement.

Si vous utilisez le SDK .NET v2, utilisez la propriété PreferredLocations pour définir la région préférée.

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

Vous pouvez également utiliser la propriété SetCurrentLocation et laisser le SDK choisir l’emplacement préféré en fonction de la proximité.

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

Notes

Les URL des points de terminaison ne doivent pas être considérées comme des constantes à long terme. Le service peut les mettre à jour à tout moment. Le SDK gère ce changement automatiquement.

Voici un exemple de code pour 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 } });

Kit de développement logiciel (SDK) Python

Le code suivant montre comment définir des emplacements préférés à l’aide du SDK Python :

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

SDK Java V4

Le code suivant montre comment définir des emplacements préférés à l’aide du SDK Java :

API asynchrone du kit SDK Java V4 (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();

Connecteur Spark 3

Vous pouvez définir la liste régionale préférée à l’aide de la spark.cosmos.preferredRegionsListconfiguration, par exemple :

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

REST

Une fois qu’un compte de base de données est mis à disposition dans plusieurs régions, les clients peuvent interroger sa disponibilité en exécutant une requête GET sur cet URI https://{databaseaccount}.documents.azure.com/

Le service renvoie une liste des régions et leurs URI de points de terminaison Azure Cosmos DB correspondants pour les réplicas. La région d’écriture en cours est indiquée dans la réponse. Le client peut ensuite sélectionner le point de terminaison approprié pour toutes les autres requêtes d’API REST, comme suit.

Exemple de réponse

{
    "_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
}
  • Les requêtes PUT, POST et DELETE doivent accéder à l’URI d’écriture indiqué
  • Toutes les requêtes GET et autres demandes en lecture seule (par ex., Requêtes) peuvent accéder à n’importe quel point de terminaison choisi par le client

L’écriture de demandes dans les régions en lecture seule échoue avec le code d’erreur HTTP 403 (« Interdit »).

Si la région d’écriture change après la phase de découverte initiale du client, les écritures suivantes dans la région d’écriture précédente échouent avec le code d’erreur HTTP 403 (« Interdit »). Le client doit alors exécuter à nouveau la requête GET sur la liste des régions pour obtenir la région d’écriture mise à jour.

C’est ici que s’achève ce didacticiel. Découvrez comment gérer la cohérence de votre compte répliqué à l’échelle mondiale en lisant l’article Niveaux de cohérence dans Azure Cosmos DB. Pour plus d’informations sur le fonctionnement de la réplication de base de données à l’échelle mondiale dans Azure Cosmos DB, voir Diffuser des données à l’échelle mondiale avec Azure Cosmos DB.

Étapes suivantes

Dans ce tutoriel, vous avez :

  • Configurer la diffusion mondiale à l’aide du portail Azure
  • Configurer la diffusion mondiale à l’aide de l’API pour NoSQL

Vous pouvez maintenant passer au didacticiel suivant pour apprendre à développer en local à l’aide de l’émulateur local Azure Cosmos DB.

Développer en local avec l’émulateur

Vous tentez d’effectuer une planification de la capacité pour une migration vers Azure Cosmos DB ? Vous pouvez utiliser les informations sur votre cluster de bases de données existant pour la planification de la capacité.