Zelfstudie: Wereldwijde distributie van Azure Cosmos DB instellen met behulp van de API voor NoSQL

  • Artikel

VAN TOEPASSING OP: NoSQL

In dit artikel laten we zien hoe u de Azure Portal gebruikt om globale distributie van Azure Cosmos DB in te stellen en vervolgens verbinding te maken met behulp van de API voor NoSQL.

Dit artikel behandelt de volgende taken:

  • Wereldwijde distributie configureren met behulp van Azure Portal
  • Globale distributie configureren met behulp van de API voor NoSQLs

Globale databaseregio's toevoegen met Azure Portal

Azure Cosmos DB is wereldwijd beschikbaar in alle Azure-regio's. 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).

  1. Klik in Azure Portal in de linkerbalk op Azure Cosmos DB.

  2. Selecteer op de pagina Azure Cosmos DB het databaseaccount dat u wilt wijzigen.

  3. Klik op de accountpagina op Gegevens wereldwijd repliceren in het 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. 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.

    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. Deze optie kunt u gebruiken om het failoverproces te testen of om de primaire regio voor schrijfbewerkingen te wijzigen. Als u een derde regio toevoegt, komt op dezelfde pagina de optie Failoverprioriteiten beschikbaar. Hiermee kunt u de failovervolgorde voor leesbewerkingen wijzigen.

Globale databaseregio's selecteren

Er zijn twee gangbare scenario's voor het configureren van twee of meer regio's:

  1. Gegevenstoegang met lage latentie bieden aan eindgebruikers, ongeacht waar deze zich bevinden
  2. Regionale tolerantie toevoegen voor bedrijfscontinuïteit en herstel na noodgevallen (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.

Voor BCDR wordt aanbevolen om regio's toe te voegen op basis van de regioparen die worden beschreven in het artikel Replicatie tussen regio's in Azure: Bedrijfscontinuïteit en herstel na noodgevallen .

Verbinding maken met een voorkeursregio met behulp van de API voor NoSQL

Om te profiteren van wereldwijde distributie, kunnen clienttoepassingen de geordende voorkeurslijst met regio's opgeven die moet worden gebruikt voor het uitvoeren van documentbewerkingen. 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.

Deze voorkeurslijst wordt opgegeven bij het initialiseren van een verbinding met de SQL-SDK's. Met SDK's wordt de optionele parameter PreferredLocations geaccepteerd, die een geordende lijst met Azure-regio's bevat.

De SDK verzendt alle schrijfbewerkingen automatisch naar de huidige schrijfregio. Alle leesbewerkingen worden verzonden naar de eerst beschikbare regio in de lijst met voorkeurslocaties. Als de aanvraag mislukt, gaat de client naar de volgende regio in de lijst.

Met SDK wordt alleen geprobeerd om de regio's te lezen die zijn opgegeven in de lijst met voorkeurslocaties. Als het Azure Cosmos DB-account bijvoorbeeld beschikbaar is in vier regio's, maar de client slechts twee leesregio's (niet-schrijven) binnen de PreferredLocationsopgeeft, worden er geen leesbewerkingen geleverd vanuit de leesregio die niet is opgegeven in PreferredLocations. Als de leesregio's die zijn opgegeven in de lijst van PreferredLocations niet beschikbaar zijn, worden leesbewerkingen geleverd vanuit de schrijfregio.

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. Als de eigenschap PreferredLocations niet is ingesteld, worden alle aanvragen verwerkt vanuit de huidige schrijfregio.

Als u geen voorkeurslocaties hebt opgegeven maar de setCurrentLocation methode hebt gebruikt, worden met de SDK de voorkeurslocaties automatisch ingevuld op basis van de huidige regio waarin de-client wordt uitgevoerd. De regio's worden met de SDK gerangschikt op basis van de nabijheid van een regio ten opzicht van de huidige regio.

.NET SDK

De SDK kan worden gebruikt zonder codewijzigingen. In dit geval stuurt de SDK alle lees- en schrijfbewerkingen automatisch door naar de huidige schrijfregio.

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. Deze eigenschap is van het type Verzameling <string>, die een lijst met regionamen moet bevatten. De tekenreekswaarden zijn opgemaakt volgens de kolom voor de regionaam op de pagina Azure-regio's, zonder spaties vóór, respectievelijk na het eerste en laatste teken.

De huidige eindpunten voor schrijven en lezen zijn beschikbaar in respectievelijk DocumentClient.WriteEndpoint en DocumentClient.ReadEndpoint.

Notitie

De URL's voor de eindpunten moeten niet worden beschouwd als constanten met een lange levensduur. De service kan deze op elk gewenst moment bijwerken. De SDK verwerkt deze wijziging automatisch.

Als u met de .NET V2 SDK werkt, gebruikt u de eigenschap PreferredLocations om de voorkeursregio in te stellen.

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

U kunt ook de eigenschap SetCurrentLocation gebruiken en de voorkeurslocatie door de SDK laten bepalen op basis van nabijheid.

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

Notitie

De URL's voor de eindpunten moeten niet worden beschouwd als constanten met een lange levensduur. De service kan deze op elk gewenst moment bijwerken. De SDK verwerkt deze wijziging automatisch.

Hieronder ziet u een codevoorbeeld voor 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-SDK

De volgende code laat zien hoe u een voorkeurslocatie instelt met behulp van de Python SDK:

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

Java V4 SDK

De volgende code laat zien hoe u een voorkeurslocatie instelt met behulp van de Java SDK:

Java SDK V4 (Maven com.azure::azure-cosmos) Async API


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

Spark 3-connector

U kunt de gewenste regionale lijst definiëren met behulp van de spark.cosmos.preferredRegionsListconfiguratie, bijvoorbeeld:

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

REST

Zodra een databaseaccount beschikbaar is gesteld in meerdere regio's, kunnen clients de beschikbaarheid ervan opvragen door een GET-aanvraag uit te voeren op deze 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. De huidige schrijfregio wordt aangegeven in het antwoord. Vervolgens kan de client op de volgende wijze het juiste eindpunt voor alle verdere REST-API-aanvragen selecteren.

Voorbeeld van een antwoord

{
    "_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 schrijven
  • Alle GET-aanvragen en andere alleen-lezen aanvragen (zoals query's) kunnen verwijzen naar elk eindpunt dat de client aangeeft

Schrijfaanvragen naar alleen-lezen regio's mislukken met HTTP-foutcode 403 ('Verboden').

Als de schrijfregio verandert na de initiële detectiefase van de client, mislukken daaropvolgende schrijfbewerkingen naar de vorige schrijfregio met HTTP-foutcode 403 ('Verboden'). De client moet dan de lijst met regio's opnieuw ophalen om de bijgewerkte schrijfregio te krijgen.

En daarmee is deze zelfstudie voltooid. Informatie over het beheren van de consistentie van uw wereldwijd gerepliceerde account kunt u vinden in Consistentieniveaus 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.

Volgende stappen

In deze zelfstudie hebt u het volgende gedaan:

  • Wereldwijde distributie configureren met behulp van Azure Portal
  • Globale distributie configureren met behulp van de API voor NoSQLs

U kunt nu doorgaan met de volgende zelfstudie voor informatie over lokaal ontwikkelen met behulp van de lokale Azure Cosmos DB-emulator.

Lokaal ontwikkelen met de emulator

Probeert u capaciteitsplanning uit te voeren voor een migratie naar Azure Cosmos DB? U kunt informatie over uw bestaande databasecluster gebruiken voor capaciteitsplanning.