Kurz: Nastavení globální distribuce pomocí služby Azure Cosmos DB for NoSQL

  • Článek

PLATÍ PRO: NoSQL

V tomto článku si ukážeme, jak pomocí webu Azure Portal nastavit globální distribuci služby Azure Cosmos DB a pak se připojit pomocí rozhraní API pro NoSQL.

Tento článek se zabývá následujícími úkony:

Přidání globálních oblastí databáze pomocí webu Azure Portal

Azure Cosmos DB je k dispozici ve všech oblastech Azure po celém světě. Po výběru výchozí úrovně konzistence účtu databáze k němu můžete přidružit jednu nebo několik oblastí (v závislosti na výběru výchozí úrovně konzistence a potřebách globální distribuce).

  1. V levém panelu na webu Azure Portal klikněte na Azure Cosmos DB.

  2. Na stránce Azure Cosmos DB vyberte účet databáze, který chcete upravit.

  3. V nabídce na stránce účtu klikněte na Globální replikace dat.

  4. Na stránce Globální replikace dat vyberte kliknutím na oblasti na mapě oblasti, které chcete přidat nebo odebrat, a pak klikněte na Uložit. Za přidání oblastí se neúčtují žádné poplatky. Další informace najdete na stránce s cenami nebo v článku Globální distribuce dat pomocí služby Azure Cosmos DB.

    Přidání nebo odebrání oblastí kliknutím na oblasti na mapě

Po přidání druhé oblasti se na stránce portálu Globální replikace dat povolí možnost Ruční převzetí služeb při selhání. Pomocí této možnosti můžete otestovat proces převzetí služeb při selhání nebo změnit primární oblast pro zápis. Po přidání třetí oblasti se na stejné stránce povolí možnost Priority převzetí služeb při selhání, abyste mohli změnit pořadí převzetí služeb při selhání pro čtení.

Výběr globálních oblastí databáze

Pro konfiguraci dvou nebo více oblastí existují dva běžné scénáře:

  1. Poskytování přístupu k datům s nízkou latencí koncovým uživatelům po celém světe bez ohledu na to, kde se nacházejí.
  2. Přidání oblastní odolnosti pro zajištění provozní kontinuity a zotavení po havárii (BCDR)

Pro zajištění nízké latence pro koncové uživatele se doporučuje nasadit aplikaci i službu Azure Cosmos DB v oblastech, které odpovídají umístění uživatelů aplikace.

Pro BCDR se doporučuje přidat oblasti na základě párů oblastí popsaných v replikaci mezi oblastmi v Azure: Provozní kontinuita a zotavení po havárii.

Připojení k upřednostňované oblasti pomocí rozhraní API pro NoSQL

Aby mohly využívat globální distribuci, můžou mít klientské aplikace určený seřazený seznam preferovaných oblastí, které se mají použít k provádění operací s dokumenty. V závislosti na konfiguraci účtu služby Azure Cosmos DB, aktuální regionální dostupnosti a zadaného seznamu preferencí zvolí sada SQL SDK optimální koncový bod, který bude provádět operace čtení a zápisu.

Tento seznam preferencí se zadává při inicializaci připojení pomocí sad SQL SDK. Sady SDK přijímají volitelný parametr PreferredLocations , který je seřazeným seznamem oblastí Azure.

Sada SDK bude automaticky odesílat všechny operace zápisu do aktuální oblasti pro zápis. Všechna čtení se odesílají do první dostupné oblasti v seznamu upřednostňovaných umístění. Pokud požadavek selže, klient seznam se nezdaří do další oblasti.

Sada SDK se pokusí číst pouze z oblastí zadaných v upřednostňovaných umístěních. Takže pokud je například účet služby Azure Cosmos DB dostupný ve čtyřech oblastech, ale klient určuje pouze dvě oblasti čtení (bez zápisu PreferredLocations) v rámci , nebudou z oblasti čtení, která není zadaná v PreferredLocations. Pokud oblasti pro čtení zadané v PreferredLocations seznamu nejsou dostupné, budou čtení obsluhována mimo oblast zápisu.

Aplikace může ověřit aktuální koncový bod zápisu a koncový bod pro čtení zvolený sadou SDK kontrolou dvou vlastností WriteEndpoint a ReadEndpointdostupnými ve verzi 1.8 a vyšší. PreferredLocations Pokud vlastnost není nastavená, budou všechny požadavky obsluhovány z aktuální oblasti zápisu.

Pokud nezadáte upřednostňovaná umístění, ale použijete metodu setCurrentLocation , sada SDK automaticky naplní upřednostňovaná umístění na základě aktuální oblasti, ve které klient běží. Sada SDK objedná oblasti na základě blízkosti oblasti k aktuální oblasti.

.NET SDK

Sadu SDK můžete využívat bez jakýchkoli změn kódu. V tomto případě sada SDK automaticky směruje operace čtení i zápisu do aktuální oblasti pro zápis. V sadě .NET SDK verze 1.8 a novější má parametr ConnectionPolicy pro konstruktor DocumentClient vlastnost Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations. Tato vlastnost je typu Kolekce <string> a měla by obsahovat seznam názvů oblastí. Řetězcové hodnoty jsou naformátované podle sloupce názvu oblasti na stránce Oblasti Azure bez mezer před nebo za prvním a posledním znakem.

Aktuální koncové body pro čtení a zápis jsou k dispozici ve vlastnostech DocumentClient.WriteEndpoint a DocumentClient.ReadEndpoint.

Poznámka:

Adresy URL koncových bodů by se neměly považovat za dlouhodobé konstanty. Služba je může kdykoli aktualizovat. Sada SDK tuto změnu zpracuje automaticky.

Pokud používáte sadu .NET SDK V2, nastavte upřednostňovanou oblast pomocí PreferredLocations vlastnosti.

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

Alternativně můžete použít SetCurrentLocation vlastnost a nechat sadu SDK zvolit upřednostňované umístění na základě blízkosti.

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

Poznámka:

Adresy URL koncových bodů by se neměly považovat za dlouhodobé konstanty. Služba je může kdykoli aktualizovat. Sada SDK tuto změnu zpracuje automaticky.

Níže je příklad kódu pro 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

Následující kód ukazuje, jak nastavit upřednostňovaná umístění pomocí sady 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

Následující kód ukazuje, jak nastavit upřednostňovaná umístění pomocí sady 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();

Konektor Spark 3

Upřednostňovaný místní seznam můžete definovat pomocí spark.cosmos.preferredRegionsList konfigurace, například:

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

REST

Po zpřístupnění databázového účtu ve více oblastech můžou klienti dotazovat svou dostupnost provedením požadavku GET na tento identifikátor URI. https://{databaseaccount}.documents.azure.com/

Služba vrátí seznam oblastí a jejich odpovídajících identifikátorů URI koncových bodů služby Azure Cosmos DB pro repliky. V odpovědi bude uvedená aktuální oblast pro zápis. Klient si pak může vybrat vhodný koncový bod pro všechny další požadavky rozhraní REST API následujícím způsobem.

Příklad odpovědi

{
    "_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
}
  • Všechny požadavky PUT, POST a DELETE musí jít na uvedený identifikátor URI zápisu.
  • Všechny požadavky GET a další požadavky jen pro čtení (například dotazy) můžou přejít do libovolného koncového bodu zvoleného klienta.

Požadavky na zápis do oblastí jen pro čtení nebudou úspěšné. Zobrazí se kód chyby HTTP 403 (zakázáno).

Pokud se oblast zápisu změní po počáteční fázi zjišťování klienta, následné zápisy do předchozí oblasti zápisu selžou s kódem chyby HTTP 403 (Zakázáno). Klient pak musí pomocí požadavku GET znovu získat seznam oblastí, aby získal aktualizovanou oblast pro zápis.

To je vše, tento kurz je u konce. Informace o správě konzistence vašeho globálně replikovaného účtu najdete v tématu Úrovně konzistence ve službě Azure Cosmos DB. Další informace o fungování globální replikace databází ve službě Azure Cosmos DB najdete v tématu Globální distribuce dat pomocí služby Azure Cosmos DB.

Další kroky

V tomto kurzu jste provedli následující:

  • Konfigurace globální distribuce pomocí webu Azure Portal
  • Konfigurace globální distribuce pomocí rozhraní API pro seznamy NoSQLS

Teď můžete přejít k dalšímu kurzu, ve kterém se naučíte vyvíjet místně s využitím místního emulátoru služby Azure Cosmos DB.

Místní vývoj s využitím emulátoru

Pokoušíte se naplánovat kapacitu migrace do služby Azure Cosmos DB? Informace o stávajícím databázovém clusteru můžete použít k plánování kapacity.