Configuration de la distribution mondiale Azure Cosmos DB à l’aide de l’API SQLSet up Azure Cosmos DB global distribution using the SQL API

Dans cet article, nous vous montrons comment utiliser le portail Azure pour configurer la diffusion mondiale d’Azure Cosmos DB, puis établir une connexion à l’aide de l’API SQL.In this article, we show how to use the Azure portal to setup Azure Cosmos DB global distribution and then connect using the SQL API.

Cet article décrit les tâches suivantes :This article covers the following tasks:

  • Configurer la diffusion mondiale à l’aide du portail AzureConfigure global distribution using the Azure portal
  • Configurer la distribution mondiale à l’aide des API SQLConfigure global distribution using the SQL APIs

Ajouter des régions de bases de donnée mondiales à l’aide du portail AzureAdd global database regions using the Azure portal

Azure Cosmos DB est disponible dans toutes les régions Azure à travers le monde.Azure Cosmos DB is available in all Azure regions worldwide. 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).After selecting the default consistency level for your database account, you can associate one or more regions (depending on your choice of default consistency level and global distribution needs).

  1. Dans la barre à gauche du portail Azure, cliquez sur Azure Cosmos DB.In the Azure portal, in the left bar, click Azure Cosmos DB.

  2. Dans la page Azure Cosmos DB, sélectionnez le compte de base de données à modifier.In the Azure Cosmos DB page, select the database account to modify.

  3. Dans la page du compte, cliquez sur Répliquer les données globalement à partir du menu.In the account page, click Replicate data globally from the 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.In the Replicate data globally page, select the regions to add or remove by clicking regions in the map, and then click Save. 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.There is a cost to adding regions, see the pricing page or the Distribute data globally with Azure Cosmos DB article for more information.

    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.Once you add a second region, the Manual Failover option is enabled on the Replicate data globally page in the portal. Vous pouvez utiliser cette option pour tester le processus de basculement ou modifier la région principale d’écriture.You can use this option to test the failover process or change the primary write region. 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.Once you add a third region, the Failover Priorities option is enabled on the same page so that you can change the failover order for reads.

Sélection de régions de base de données mondialeSelecting global database regions

Il existe deux scénarios courants pour la configuration de deux ou plusieurs régions :There are two common scenarios for configuring two or more regions:

  1. La fourniture aux utilisateurs finaux d’un accès à faible latence aux données, où qu’ils se trouvent dans le mondeDelivering low-latency access to data to end users no matter where they are located around the globe
  2. L’ajout d’une résilience régionale pour la continuité des activités et la récupération d’urgence (BCDR)Adding regional resiliency for business continuity and disaster recovery (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.For delivering low-latency to end users, it is recommended that you deploy both the application and Azure Cosmos DB in the regions that correspond to where the application's users are located.

Pour BCDR, nous vous recommandons d’ajouter les régions en fonction des paires de régions décrites dans l’article Continuité des activités et récupération d’urgence (BCDR) : régions jumelées d’Azure.For BCDR, it is recommended to add regions based on the region pairs described in the Business continuity and disaster recovery (BCDR): Azure Paired Regions article.

Se connecter à une région de prédilection avec l’API SQLConnecting to a preferred region using the SQL API

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.In order to take advantage of global distribution, client applications can specify the ordered preference list of regions to be used to perform document operations. Pour cela, vous devez configurer la stratégie de connexion.This can be done by setting the connection policy. 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.Based on the Azure Cosmos DB account configuration, current regional availability and the preference list specified, the most optimal endpoint will be chosen by the SQL SDK to perform write and read operations.

Cette liste de préférences est spécifiée lors de l’initialisation d’une connexion à l’aide des SDK SQL.This preference list is specified when initializing a connection using the SQL SDKs. Les SDK acceptent un paramètre facultatif « PreferredLocations » qui est une liste ordonnée des régions Azure.The SDKs accept an optional parameter "PreferredLocations" that is an ordered list of Azure regions.

Le SDK envoie automatiquement toutes les écritures vers la région d’écriture en cours.The SDK will automatically send all writes to the current write region.

Toutes les lectures sont envoyées vers la première région disponible dans la liste PreferredLocations.All reads will be sent to the first available region in the PreferredLocations list. Si la demande échoue, le client passe à la région suivante dans la liste et ainsi de suite.If the request fails, the client will fail down the list to the next region, and so on.

Les SDK tentent des opérations de lecture uniquement à partir des régions spécifiées dans PreferredLocations.The SDKs will only attempt to read from the regions specified in PreferredLocations. Ainsi, par exemple, si le compte de base de données est disponible dans quatre régions, mais que le client spécifie uniquement deux régions de lecture (sans écriture) pour PreferredLocations, aucune lecture ne sera prise en charge en dehors de la région de lecture si elle n’est pas spécifiée dans PreferredLocations.So, for example, if the Database Account is available in four regions, but the client only specifies two read(non-write) regions for PreferredLocations, then no reads will be served out of the read region that is not specified in PreferredLocations. Si les régions de lecture spécifiées dans PreferredLocations ne sont pas disponibles, les lectures seront prises en charge en dehors de la région d’écriture.If the read regions specified in the PreferredLocations are not available, reads will be served out of write region.

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.The application can verify the current write endpoint and read endpoint chosen by the SDK by checking two properties, WriteEndpoint and ReadEndpoint, available in SDK version 1.8 and above.

Si la propriété PreferredLocations n’est pas définie, toutes les demandes seront traitées par la zone d’écriture en cours.If the PreferredLocations property is not set, all requests will be served from the current write region.

Kit de développement logiciel (SDK) .NET.NET SDK

Le SDK peut être utilisé sans aucune modification du code.The SDK can be used without any code changes. Dans ce cas, le SDK dirige automatiquement les lectures et les écritures vers la région d’écriture en cours.In this case, the SDK automatically directs both reads and writes to the current write region.

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.In version 1.8 and later of the .NET SDK, the ConnectionPolicy parameter for the DocumentClient constructor has a property called Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations. Cette propriété est de type Collection <string> et doit contenir une liste des noms de région.This property is of type Collection <string> and should contain a list of region names. 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.The string values are formatted per the Region Name column on the Azure Regions page, with no spaces before or after the first and last character respectively.

Les points de terminaison d’écriture et de lecture en cours sont disponibles dans DocumentClient.WriteEndpoint et DocumentClient.ReadEndpoint, respectivement.The current write and read endpoints are available in DocumentClient.WriteEndpoint and DocumentClient.ReadEndpoint respectively.

Notes

Les URL des points de terminaison ne doivent pas être considérées comme des constantes à long terme.The URLs for the endpoints should not be considered as long-lived constants. Le service peut les mettre à jour à tout moment.The service may update these at any point. Le SDK gère ce changement automatiquement.The SDK handles this change automatically.

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

Node.js/JavaScriptNode.js/JavaScript

Le SDK peut être utilisé sans aucune modification du code.The SDK can be used without any code changes. Dans ce cas, le SDK dirige automatiquement les lectures et les écritures vers la région d’écriture en cours.In this case, the SDK will automatically direct both reads and writes to the current write region.

Dans la version 1.8 et ultérieure de chaque SDK, le paramètre ConnectionPolicy du constructeur DocumentClient comporte une nouvelle propriété appelée DocumentClient.ConnectionPolicy.PreferredLocations.In version 1.8 and later of each SDK, the ConnectionPolicy parameter for the DocumentClient constructor a new property called DocumentClient.ConnectionPolicy.PreferredLocations. Ce paramètre est un tableau de chaînes qui prend une liste de noms de régions.This is parameter is an array of strings that takes a list of region names. Les noms sont mis en forme en fonction de la colonne Nom de la région, dans la page Régions Azure.The names are formatted per the Region Name column in the Azure Regions page. Vous pouvez également utiliser des constantes prédéfinies dans l’objet de commodité AzureDocuments.RegionsYou can also use the predefined constants in the convenience object AzureDocuments.Regions

Les points de terminaison d’écriture et de lecture en cours sont disponibles dans DocumentClient.getWriteEndpoint et DocumentClient.getReadEndpoint, respectivement.The current write and read endpoints are available in DocumentClient.getWriteEndpoint and DocumentClient.getReadEndpoint respectively.

Notes

Les URL des points de terminaison ne doivent pas être considérées comme des constantes à long terme.The URLs for the endpoints should not be considered as long-lived constants. Le service peut les mettre à jour à tout moment.The service may update these at any point. Le SDK gère ce changement automatiquement.The SDK will handle this change automatically.

Voici un exemple de code pour Node.js/Javascript.Below is a code example for Node.js/Javascript.

// Creating a ConnectionPolicy object
var connectionPolicy = new DocumentBase.ConnectionPolicy();

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

// initialize the connection
var client = new DocumentDBClient(host, { masterKey: masterKey }, connectionPolicy);

Kit de développement logiciel (SDK) PythonPython SDK

Le code suivant montre comment définir des emplacements préférés à l’aide du SDK Python :The following code shows how to set preferred locations by using the Python SDK:


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

SDK Java V2Java V2 SDK

Le code suivant montre comment définir des emplacements préférés à l’aide du SDK Java :The following code shows how to set preferred locations by using the Java SDK:

ConnectionPolicy policy = new ConnectionPolicy();
policy.setUsingMultipleWriteLocations(true);
policy.setPreferredLocations(Arrays.asList("East US", "West US", "Canada Central"));
AsyncDocumentClient client =
        new AsyncDocumentClient.Builder()
                .withMasterKeyOrResourceToken(this.accountKey)
                .withServiceEndpoint(this.accountEndpoint)
                .withConnectionPolicy(policy)
                .build();

RESTREST

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 l’URI suivant.Once a database account has been made available in multiple regions, clients can query its availability by performing a GET request on the following 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.The service will return a list of regions and their corresponding Azure Cosmos DB endpoint URIs for the replicas. La région d’écriture en cours est indiquée dans la réponse.The current write region will be indicated in the response. Le client peut ensuite sélectionner le point de terminaison approprié pour toutes les autres requêtes d’API REST, comme suit.The client can then select the appropriate endpoint for all further REST API requests as follows.

Exemple de réponseExample response

{
    "_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éAll PUT, POST and DELETE requests must go to the indicated write URI
  • 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 clientAll GETs and other read-only requests (for example queries) may go to any endpoint of the client’s choice

L’écriture de demandes dans les régions en lecture seule échoue avec le code d’erreur HTTP 403 (« Interdit »).Write requests to read-only regions will fail with HTTP error code 403 ("Forbidden").

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 »).If the write region changes after the client’s initial discovery phase, subsequent writes to the previous write region will fail with HTTP error code 403 ("Forbidden"). 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.The client should then GET the list of regions again to get the updated write region.

C’est ici que s’achève ce didacticiel.That's it, that completes this tutorial. 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.You can learn how to manage the consistency of your globally replicated account by reading Consistency levels in 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.And for more information about how global database replication works in Azure Cosmos DB, see Distribute data globally with Azure Cosmos DB.

Étapes suivantesNext steps

Dans ce tutoriel, vous avez :In this tutorial, you've done the following:

  • Configurer la diffusion mondiale à l’aide du portail AzureConfigure global distribution using the Azure portal
  • Configurer la distribution mondiale à l’aide des API SQLConfigure global distribution using the SQL APIs

Vous pouvez maintenant passer au didacticiel suivant pour apprendre à développer en local à l’aide de l’émulateur local Azure Cosmos DB.You can now proceed to the next tutorial to learn how to develop locally using the Azure Cosmos DB local emulator.