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

  • Článek

PLATÍ PRO: NoSQL

V tomto článku si ukážeme, jak pomocí 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:

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

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 článku Replikace 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 odešlou do první dostupné oblasti v seznamu upřednostňovaných umístění. Pokud požadavek selže, klient selhává v seznamu do další oblasti.

Sada SDK se pokusí číst jenom 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 pro čtení (bez zápisu PreferredLocations) v rámci , pak se z oblasti čtení, která není uvedená v , nebude obsluhovat žádné čtení z oblasti čtení, která není zadána v PreferredLocations. Pokud oblasti čtení zadané v PreferredLocations seznamu nejsou k dispozici, čtení se bude obsluhovat mimo oblast zápisu.

Aplikace může ověřit aktuální koncový bod pro zápis a koncový bod pro čtení zvolený sadou SDK kontrolou dvou vlastností WriteEndpoint a ReadEndpoint, které jsou dostupné v sadě SDK verze 1.8 a vyšší. Pokud vlastnost PreferredLocations 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é je klient spuštěný. Sada SDK seskuzuje 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 formátované podle sloupce název oblasti na stránce Oblasti Azure bez mezer před prvním a posledním znakem v uvedeném pořadí.

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

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

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, key, 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, {'masterKey': MASTER_KEY}, connectionPolicy)

Java V4 SDK

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

Konektor Spark 3

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

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

REST

Jakmile je databázový účet dostupný ve více oblastech, klienti se můžou dotazovat na jeho 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í směřovat na uvedený identifikátor URI pro zápis.
  • 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 podle výběru 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 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 pro migraci do služby Azure Cosmos DB? Informace o existujícím databázovém clusteru můžete použít k plánování kapacity.