Dela via

Självstudie: Konfigurera global distribution med Hjälp av Azure Cosmos DB för NoSQL

  • Artikel

GÄLLER FÖR: NoSQL

I den här artikeln visar vi hur du använder Azure Portal för att konfigurera global distribution i Azure Cosmos DB och sedan ansluta med hjälp av API:et för NoSQL.

Den här artikeln beskriver följande uppgifter:

  • Konfigurera global distribution med Azure Portal
  • Konfigurera global distribution med hjälp av API:et för NoSQLs

Lägg till globala databasregioner med Azure Portal

Azure Cosmos DB är tillgängligt i alla Azure-regioner över hela världen. När du har valt standardkonsekvensnivå för ditt databaskonto, så kan du associera en eller flera regioner (beroende på ditt val av standardkonsekvensnivå och globala distributionsbehov).

  1. Klicka på Azure Cosmos DB i fältet till vänster i Azure Portal.

  2. Markera det databaskonto du vill ändra på sidan Azure Cosmos DB.

  3. Klicka på Replikera data globalt på menyn på kontosidan.

  4. Välj de regioner som ska läggas till eller tas bort genom att klicka på regioner på kartan på sidan Replikera data globalt och klicka sedan på Spara. Det kostar att lägga till regioner. Mer information finns på sidan om prissättning eller i artikeln Distribuera data globalt med Azure Cosmos DB.

    Lägg till eller ta bort regioner på kartan genom att klicka på dem

När du lägger till en andra region aktiveras alternativet manuell redundans på sidan Replikera data globalt i portalen. Du kan använda det här alternativet för att testa redundansprocessen eller ändra den primära skrivningsregionen. När du lägger till en tredje region aktiveras alternativet Redundansprioriteringar på samma sida, så att du kan ändra redundansordningen för läsningar.

Välja globala databasregioner

Det finns två vanliga scenarier när det gäller att konfigurera två eller flera regioner:

  1. Leverera åtkomst med låg latens till data för slutanvändare oavsett var i världen de befinner sig
  2. Lägga till regional återhämtning till affärskontinuitet och haveriberedskap (BCDR)

När det gäller att leverera låg latens till slutanvändare bör du distribuera både programmet och Azure Cosmos DB i de regioner som motsvarar de platser där programmets användare finns.

För BCDR rekommenderar vi att du lägger till regioner baserat på de regionpar som beskrivs i artikeln Replikering mellan regioner i Azure: Affärskontinuitet och haveriberedskap .

Ansluta till en önskad region med hjälp av API:et för NoSQL

I syfte att dra nytta av den globala distributionen kan klientprogrammen ange den beställda listan med inställningar för regioner som ska användas för att utföra dokumentåtgärder. Utifrån Azure Cosmos DB-kontokonfigurationen, den aktuella regionala tillgängligheten och den angivna listan över inställningar, så väljs den mest optimala slutpunkten för genomförande av skriv- och läsåtgärder av SQL-SDK:n.

Denna lista över inställningar anges när en anslutning initieras med SQL-SDK:erna. SDK:erna accepterar en valfri parameter PreferredLocations som är en ordnad lista över Azure-regioner.

SDK:n skickar automatiskt alla skrivningar till den aktuella skrivregionen. Alla läsningar skickas till den första tillgängliga regionen i listan över önskade platser. Om begäran misslyckas redundansväxlar klienten listan till nästa region.

SDK:et försöker bara läsa från de regioner som anges på önskade platser. Om Azure Cosmos DB-kontot till exempel är tillgängligt i fyra regioner, men klienten endast anger två läsregioner (icke-skrivbara) i PreferredLocations, kommer inga läsningar att hanteras från den läsregion som inte anges i PreferredLocations. Om de läsregioner som anges i PreferredLocations listan inte är tillgängliga, hanteras läsningar från skrivregionen.

Programmet kan verifiera den aktuella skrivslutpunkten och lässlutpunkten som valts av SDK genom att kontrollera två egenskaper WriteEndpoint och ReadEndpoint, som är tillgängliga i SDK version 1.8 och senare. Om egenskapen PreferredLocations inte har angetts hanteras alla begäranden från den aktuella skrivregionen.

Om du inte anger de önskade platserna men använde setCurrentLocation metoden fyller SDK automatiskt i de önskade platserna baserat på den aktuella region som klienten körs i. SDK:et beställer regionerna baserat på närheten av en region till den aktuella regionen.

.NET SDK

SDK:n kan användas utan några kodändringar. I det här fallet styr SDK:n automatiskt både läsningar och skrivningar till den aktuella skrivregionen. Parametern ConnectionPolicy för DocumentClient-konstruktorn har en egenskap som kallas Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations i .NET SDK version 1.8 och senare. Den här egenskapen är av typen samling <string> och bör innehålla en lista med regionnamn. Strängvärdena formateras enligt kolumnen regionnamn på sidan Azure-regioner , utan blanksteg före respektive efter det första respektive sista tecknet.

De aktuella skriv- och lässlutpunkterna är tillgängliga i DocumentClient.WriteEndpoint respektive DocumentClient.ReadEndpoint.

Kommentar

Slutpunkternas URL:er ska inte betraktas som långlivade konstanter. Tjänsten kan uppdatera dem när som helst. SDK:n hanterar sådana ändringar automatiskt.

Om du använder .NET V2 SDK använder du PreferredLocations egenskapen för att ange önskad region.

// Getting endpoints from application settings or other configuration location
Uri accountEndPoint = new Uri(Properties.Settings.Default.GlobalDatabaseUri);

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,
    credential,
    connectionPolicy);

// connect to DocDB
await docClient.OpenAsync().ConfigureAwait(false);

Du kan också använda SetCurrentLocation egenskapen och låta SDK:et välja önskad plats baserat på närhet.

// Getting endpoints from application settings or other configuration location
Uri accountEndPoint = new Uri(Properties.Settings.Default.GlobalDatabaseUri);

ConnectionPolicy connectionPolicy = new ConnectionPolicy();

connectionPolicy.SetCurrentLocation("West US 2"); /

// initialize connection
DocumentClient docClient = new DocumentClient(
    accountEndPoint,
    credential,
    connectionPolicy);

// connect to DocDB
await docClient.OpenAsync().ConfigureAwait(false);

Node.js/JavaScript

Kommentar

Slutpunkternas URL:er ska inte betraktas som långlivade konstanter. Tjänsten kan uppdatera dem när som helst. SDK:n hanterar sådana ändringar automatiskt.

Nedan visas ett kodexempel för 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, aadCredentials: tokenCredential, connectionPolicy: { preferredLocations } });

Python SDK

Följande kod visar hur du anger önskade platser med hjälp av Python SDK:

connectionPolicy = documents.ConnectionPolicy()
connectionPolicy.PreferredLocations = ['West US', 'East US', 'North Europe']
client = cosmos_client.CosmosClient(ENDPOINT, credential=token_credential, connectionPolicy)

Java V4 SDK

Följande kod visar hur du anger önskade platser med hjälp av Java SDK:

ArrayList<String> preferredRegions = new ArrayList<String>();
preferredRegions.add("East US");
preferredRegions.add( "West US");
preferredRegions.add("Canada Central");

CosmosAsyncClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .credential(tokenCredential)
                .preferredRegions(preferredRegions)
                .contentResponseOnWriteEnabled(true)
                .buildAsyncClient();

Spark 3-anslutningsprogram

Du kan definiera den önskade regionala listan med hjälp av konfigurationen spark.cosmos.preferredRegionsList , till exempel:

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

REST

När ett databaskonto har gjorts tillgängligt i flera regioner kan klienter köra frågor mot dess tillgänglighet genom att utföra en GET-begäran på den här URI:n https://{databaseaccount}.documents.azure.com/

Tjänsten returnerar en lista med regioner och URI:erna för deras motsvarande Azure Cosmos DB-slutpunkter för replikerna. Den aktuella skrivregionen indikeras i svaret. Klienten kan sedan välja lämplig slutpunkt för alla ytterligare REST API-förfrågningar enligt följande.

Exempelsvar

{
    "_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
}
  • Alla PUT-, POST- och DELETE-begäranden måste gå till angiven skriv-URI
  • Alla GET och andra skrivskyddade begäranden (till exempel frågor) kan gå till valfri slutpunkt för klienten

Skrivförfrågningar till skrivskyddade regioner misslyckas med HTTP-felkoden 403 (Forbidden (Förbjudet)).

Om skrivregionen ändras efter klientens inledande identifieringsfas misslyckas efterföljande skrivningar till den tidigare skrivregionen med HTTP-felkoden 403 ("Förbjudet"). Klienten bör sedan få listan med regioner igen och därigenom få den uppdaterade skrivregionen.

Och med detta är den här självstudiekursen klar. Mer information om hur du kan hantera ditt globalt replikerade kontos konsekvens finns i Konsekvensnivåer i Azure Cosmos DB. Mer information om hur global databasreplikering fungerar i Azure Cosmos DB finns i Distribuera data globalt med Azure Cosmos DB.

Nästa steg

I den här självstudien har du gjort följande:

  • Konfigurera global distribution med Azure Portal
  • Konfigurera global distribution med hjälp av API:et för NoSQLs

Du kan nu fortsätta till nästa självstudiekurs och lära dig hur du utvecklar lokalt med hjälp av den lokala Azure Cosmos DB-emulatorn.

Utveckla lokalt med emulatorn

Försöker du planera kapacitet för en migrering till Azure Cosmos DB? Du kan använda information om ditt befintliga databaskluster för kapacitetsplanering.