Zelf studie: Azure Cosmos DB globale distributie instellen met behulp van de SQL-APITutorial: Set up Azure Cosmos DB global distribution using the SQL API

In dit artikel laten we zien hoe Azure Portal kan worden gebruikt voor het instellen van wereldwijde distributie van Azure DB Cosmos en hoe u daarmee verbinding kunt maken met behulp van de SQL-API.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.

Dit artikel behandelt de volgende taken:This article covers the following tasks:

  • Wereldwijde distributie configureren met behulp van Azure PortalConfigure global distribution using the Azure portal
  • Globale distributie met behulp van de SQL-api's configurerenConfigure global distribution using the SQL APIs

Globale databaseregio's toevoegen met Azure PortalAdd global database regions using the Azure portal

Azure Cosmos DB is wereldwijd beschikbaar in alle Azure-regio's.Azure Cosmos DB is available in all Azure regions worldwide. Nadat u het standaardconsistentieniveau voor uw databaseaccount hebt geselecteerd, kunt u een of meer regio's aan het account koppelen (afhankelijk van uw keuze van het standaardconsistentieniveau en behoeften voor globale distributie).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. Klik in Azure Portal in de linkerbalk op Azure Cosmos DB.In the Azure portal, in the left bar, click Azure Cosmos DB.

  2. Selecteer op de pagina Azure Cosmos DB het databaseaccount dat u wilt wijzigen.In the Azure Cosmos DB page, select the database account to modify.

  3. Klik op de accountpagina op Gegevens globaal repliceren in het menu.In the account page, click Replicate data globally from the menu.

  4. Selecteer op de pagina Gegevens globaal repliceren de regio's die u wilt toevoegen of verwijderen door op de kaart op regio's te klikken. Klik vervolgens op Opslaan.In the Replicate data globally page, select the regions to add or remove by clicking regions in the map, and then click Save. Er zijn kosten verbonden aan het toevoegen van regio's. Raadpleeg de pagina met prijzen of het artikel Gegevens globaal distribueren met Azure Cosmos DB voor meer informatie.There is a cost to adding regions, see the pricing page or the Distribute data globally with Azure Cosmos DB article for more information.

    Klik op de kaart op de regio's die u wilt toevoegen of verwijderen

Zodra u een tweede regio toevoegt, komt de optie Handmatige failover beschikbaar op de pagina Gegevens globaal repliceren in de portal.Once you add a second region, the Manual Failover option is enabled on the Replicate data globally page in the portal. Deze optie kunt u gebruiken om het failoverproces te testen of om de primaire regio voor schrijfbewerkingen te wijzigen.You can use this option to test the failover process or change the primary write region. Als u een derde regio toevoegt, komt op dezelfde pagina de optie Failoverprioriteiten beschikbaar. Hiermee kunt u de failovervolgorde voor leesbewerkingen wijzigen.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.

Globale databaseregio's selecterenSelecting global database regions

Er zijn twee gangbare scenario's voor het configureren van twee of meer regio's:There are two common scenarios for configuring two or more regions:

  1. Gegevenstoegang met lage latentie bieden aan eindgebruikers, ongeacht waar deze zich bevindenDelivering low-latency access to data to end users no matter where they are located around the globe
  2. Regionale tolerantie toevoegen voor bedrijfscontinuïteit en herstel na noodgevallen (BCDR)Adding regional resiliency for business continuity and disaster recovery (BCDR)

In het eerste geval wordt het aanbevolen om zowel de toepassing als Azure Cosmos DB te implementeren in de regio's die overeenkomen met de gebieden waar de gebruikers van de toepassing zich bevinden.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.

Voor BCDR wordt het aanbevolen om regio's toe te voegen op basis van de regioparen die worden beschreven in het artikel Bedrijfscontinuïteit en herstel na noodgevallen (BCDR): gekoppelde Azure-regio’s.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.

Verbinding maken met een voorkeursregio met behulp van de SQL-APIConnecting to a preferred region using the SQL API

Om te profiteren van wereldwijde distributie, kunnen clienttoepassingen de geordende voorkeurslijst met regio's opgeven die moet worden gebruikt voor het uitvoeren van documentbewerkingen.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. Dat kan worden gedaan door het verbindingsbeleid in te stellen.This can be done by setting the connection policy. Op basis van de Azure Cosmos DB-accountconfiguratie, de huidige regionale beschikbaarheid en de opgegeven voorkeurslijst wordt het optimale eindpunt door de SQL-SDK gekozen voor het uitvoeren van schrijf- en leesbewerkingen.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.

Deze voorkeurslijst wordt opgegeven bij het initialiseren van een verbinding met de SQL-SDK's.This preference list is specified when initializing a connection using the SQL SDKs. De SDK's accepteren de optionele parameter 'PreferredLocations', die een geordende lijst met Azure-regio's bevat.The SDKs accept an optional parameter "PreferredLocations" that is an ordered list of Azure regions.

De SDK verzendt alle schrijfbewerkingen automatisch naar de huidige schrijfregio.The SDK will automatically send all writes to the current write region.

Alle leesbewerkingen worden verzonden naar de eerst beschikbare regio in de lijst PreferredLocations.All reads will be sent to the first available region in the PreferredLocations list. Als de aanvraag mislukt, gaat de client naar de volgende regio in de lijst, enzovoort.If the request fails, the client will fail down the list to the next region, and so on.

De SDK's proberen alleen de regio's te lezen die zijn opgegeven in PreferredLocations.The SDKs will only attempt to read from the regions specified in PreferredLocations. Dus als bijvoorbeeld het databaseaccount in vier verschillende regio's beschikbaar is, maar de client alleen twee leesregio's (waarnaar niet kan worden geschreven) voor PreferredLocations opgeeft, worden er geen leesbewerkingen geleverd vanuit de leesregio die niet is opgegeven in 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. Als de leesregio's die zijn opgegeven in PreferredLocations niet beschikbaar zijn, worden leesbewerkingen geleverd vanuit de schrijfregio.If the read regions specified in the PreferredLocations are not available, reads will be served out of write region.

De toepassing kan het huidige, door de SDK gekozen eindpunt voor lezen en eindpunt voor schrijven verifiëren door het controleren van de twee eigenschappen, WriteEndpoint en ReadEndpoint, die beschikbaar zijn in SDK-versie 1.8 en hoger.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.

Als de eigenschap PreferredLocations niet is ingesteld, worden alle aanvragen verwerkt vanuit de huidige schrijfregio.If the PreferredLocations property is not set, all requests will be served from the current write region.

.NET SDK.NET SDK

De SDK kan worden gebruikt zonder codewijzigingen.The SDK can be used without any code changes. In dit geval stuurt de SDK alle lees- en schrijfbewerkingen automatisch door naar de huidige schrijfregio.In this case, the SDK automatically directs both reads and writes to the current write region.

In versie 1.8 en hoger van de .NET SDK heeft de ConnectionPolicy-parameter voor de DocumentClient-constructor de eigenschap 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. Deze eigenschap is van het type Verzameling <string>, die een lijst met regionamen moet bevatten.This property is of type Collection <string> and should contain a list of region names. De tekenreekswaarden zijn opgemaakt volgens de kolom Regionaam op de pagina Azure-regio's, zonder spaties vóór, respectievelijk na het eerste en laatste teken.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.

De huidige eindpunten voor schrijven en lezen zijn beschikbaar in respectievelijk DocumentClient.WriteEndpoint en DocumentClient.ReadEndpoint.The current write and read endpoints are available in DocumentClient.WriteEndpoint and DocumentClient.ReadEndpoint respectively.

Notitie

De URL's voor de eindpunten moeten niet worden beschouwd als constanten met een lange levensduur.The URLs for the endpoints should not be considered as long-lived constants. De service kan deze op elk gewenst moment bijwerken.The service may update these at any point. De SDK verwerkt deze wijziging automatisch.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/java scriptNode.js/JavaScript

Notitie

De URL's voor de eindpunten moeten niet worden beschouwd als constanten met een lange levensduur.The URLs for the endpoints should not be considered as long-lived constants. De service kan deze op elk gewenst moment bijwerken.The service may update these at any point. De SDK verwerkt deze wijziging automatisch.The SDK will handle this change automatically.

Hieronder vindt u een code voorbeeld voor node. js/java script.Below is a code example for 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 } });

Python-SDKPython SDK

De volgende code laat zien hoe u voorkeurs locaties kunt instellen met behulp van de python-SDK: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)

Java v2 SDKJava V2 SDK

De volgende code laat zien hoe u voorkeurs locaties kunt instellen met behulp van de Java SDK: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

Zodra een databaseaccount in meerdere regio's beschikbaar komt, kunnen clients de beschikbaarheid ervan opvragen door een GET-aanvraag voor de volgende URI uit te voeren.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/

De service retourneert een lijst met regio's en hun bijbehorende Azure Cosmos DB-eindpunt-URI's voor de replica's.The service will return a list of regions and their corresponding Azure Cosmos DB endpoint URIs for the replicas. De huidige schrijfregio wordt aangegeven in het antwoord.The current write region will be indicated in the response. Vervolgens kan de client op de volgende wijze het juiste eindpunt voor alle verdere REST-API-aanvragen selecteren.The client can then select the appropriate endpoint for all further REST API requests as follows.

Voorbeeld van een antwoordExample 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
}
  • Alle PUT-, POST- en DELETE-aanvragen moeten verwijzen naar de opgegeven URI voor schrijvenAll PUT, POST and DELETE requests must go to the indicated write URI
  • Alle haalt en andere alleen-lezen aanvragen (bijvoorbeeld query's) naar een eind punt van de keuze van de clientAll GETs and other read-only requests (for example queries) may go to any endpoint of the client's choice

Schrijfaanvragen naar alleen-lezen regio's mislukken met HTTP-foutcode 403 ('Verboden').Write requests to read-only regions will fail with HTTP error code 403 ("Forbidden").

Als de schrijf regio wordt gewijzigd na de eerste detectie fase van de client, mislukt de volgende keer dat er naar de vorige schrijf regio wordt geschreven met de HTTP-fout code 403 ("verboden").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"). De client moet dan de lijst met regio's opnieuw ophalen om de bijgewerkte schrijfregio te krijgen.The client should then GET the list of regions again to get the updated write region.

En daarmee is deze zelfstudie voltooid.That's it, that completes this tutorial. Informatie over het beheren van de consistentie van uw wereldwijd gerepliceerde account kunt u vinden in Consistentieniveaus in Azure Cosmos DB.You can learn how to manage the consistency of your globally replicated account by reading Consistency levels in Azure Cosmos DB. En voor meer informatie over hoe wereldwijde databasereplicatie werkt in Azure Cosmos DB, gaat u naar Gegevens wereldwijd distribueren met 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.

Volgende stappenNext steps

In deze zelfstudie hebt u het volgende gedaan:In this tutorial, you've done the following:

  • Wereldwijde distributie configureren met behulp van Azure PortalConfigure global distribution using the Azure portal
  • Wereldwijde distributie configureren met behulp van de SQL-API'sConfigure global distribution using the SQL APIs

U kunt nu doorgaan met de volgende zelfstudie voor informatie over lokaal ontwikkelen met behulp van de lokale Azure Cosmos DB-emulator.You can now proceed to the next tutorial to learn how to develop locally using the Azure Cosmos DB local emulator.