Samouczek: konfigurowanie dystrybucji globalnej usługi Azure Cosmos DB przy użyciu interfejsu API dla noSQL

  • Artykuł

DOTYCZY: NoSQL

W tym artykule pokazano, jak skonfigurować dystrybucję globalną usługi Azure Cosmos DB przy użyciu Azure Portal, a następnie nawiązać połączenie przy użyciu interfejsu API dla NoSQL.

W tym artykule opisano następujące zadania:

  • Konfigurowanie dystrybucji globalnej przy użyciu witryny Azure Portal
  • Konfigurowanie dystrybucji globalnej przy użyciu interfejsu API dla list NoSQLs

Dodawanie regionów globalnej bazy danych przy użyciu witryny Azure Portal

Usługa Azure Cosmos DB jest dostępna we wszystkich regionach świadczenia usługi Azure na całym świecie. Po wybraniu domyślnego poziomu spójności dla Twojego konta bazy danych możesz skojarzyć co najmniej jeden region (w zależności od wybranego domyślnego poziomu spójności i globalnych potrzeb dystrybucji).

  1. W witrynie Azure Portal na pasku po lewej stronie kliknij pozycję Azure Cosmos DB.

  2. Na stronie usługi Azure Cosmos DB wybierz konto bazy danych do modyfikacji.

  3. Na stronie konta kliknij w menu pozycję Replikuj dane globalnie.

  4. Na stronie Globalna replikacja danych wybierz regiony do dodania lub usunięcia, klikając regiony na mapie, a następnie klikając przycisk Zapisz. Dodanie regionu nic nie kosztuje, zobacz cennik lub artykuł Globalna dystrybucja danych za pomocą usługi Azure Cosmos DB, aby uzyskać więcej informacji.

    Kliknij regiony na mapie, aby je dodać lub usunąć

Po dodaniu drugiego regionu w portalu na stronie Globalna replikacja danych zostanie udostępniona opcja Ręczne przejście do trybu failover. Ta opcja umożliwia testowanie procesu pracy awaryjnej lub zmianę podstawowego regionu zapisu. Po dodaniu trzeciego regionu na tej samej stronie zostanie udostępniona opcja Priorytety trybu failover, dzięki czemu możesz zmienić kolejność pracy awaryjnej dla odczytów.

Wybieranie regionów globalnej bazy danych

Istnieją dwa typowe scenariusze konfigurowania co najmniej dwóch regionów:

  1. Zapewnienie użytkownikom końcowym dostępu z małym opóźnieniem niezależnie od tego, gdzie znajdują się na całym świecie
  2. Dodawanie regionalnych odporności dla ciągłości prowadzenia działalności biznesowej i odzyskiwania po awarii (BCDR)

Aby zapewnić użytkownikom końcowym małe opóźnienia, zalecane jest wdrożenie zarówno aplikacji, jak i usługi Azure Cosmos DB w regionach, które odpowiadają lokalizacjom użytkowników aplikacji.

W przypadku strategii BCDR zaleca się dodawanie regionów na podstawie par regionów opisanych w artykule Replikacja między regionami na platformie Azure: Ciągłość działania i odzyskiwanie po awarii .

Nawiązywanie połączenia z preferowanym regionem przy użyciu interfejsu API dla NoSQL

Aby można było korzystać z dystrybucji globalnej, w aplikacjach klienckich można określić uporządkowaną listę preferencji regionów, która będzie używana do wykonywania operacji na dokumentach. Na podstawie konfiguracji konta usługi Azure Cosmos DB, bieżącej dostępności regionalnej i określonej listy preferencji zestaw SDK SQL wybiera najbardziej optymalny punkt końcowy, w którym będą wykonywane operacje zapisu i odczytu.

Lista preferencji jest określana podczas inicjowania połączenia przy użyciu zestawów SDK SQL. Zestawy SDK akceptują opcjonalny parametr PreferredLocations , który jest uporządkowaną listą regionów świadczenia usługi Azure.

Zestaw SDK automatycznie wysyła wszystkie operacje zapisu do bieżącego regionu zapisu. Wszystkie operacje odczytu zostaną wysłane do pierwszego dostępnego regionu na liście preferowanych lokalizacji. Jeśli żądanie zakończy się niepowodzeniem, klient zakończy się niepowodzeniem z listy do następnego regionu.

Zestaw SDK podejmie próbę odczytu tylko z regionów określonych w preferowanych lokalizacjach. Na przykład jeśli konto usługi Azure Cosmos DB jest dostępne w czterech regionach, ale klient określa tylko dwa regiony odczytu (nie zapisu) w obrębie PreferredLocationsusługi , nie będą obsługiwane żadne operacje odczytu z regionu odczytu, który nie jest określony w elemecie PreferredLocations. Jeśli regiony odczytu określone na PreferredLocations liście nie są dostępne, odczyty będą obsługiwane poza regionem zapisu.

Aplikacja może zweryfikować bieżący punkt końcowy zapisu i punkt końcowy odczytu wybrany przez zestaw SDK, sprawdzając dwie właściwości WriteEndpoint i ReadEndpoint, dostępne w zestawie SDK w wersji 1.8 lub nowszej. Jeśli właściwość nie jest ustawiona PreferredLocations , wszystkie żądania będą obsługiwane z bieżącego regionu zapisu.

Jeśli nie określisz preferowanych lokalizacji, ale użyto setCurrentLocation metody, zestaw SDK automatycznie wypełni preferowane lokalizacje na podstawie bieżącego regionu, w którym działa klient. Zestaw SDK porządkuje regiony w oparciu o bliskość regionu do bieżącego regionu.

Zestaw SDK .NET

Zestawu SDK można używać bez konieczności wprowadzania jakichkolwiek zmian kodu. W takim przypadku zestaw SDK automatycznie kieruje operacje odczytu i zapisu do bieżącego regionu zapisu.

W wersji 1.8 (i nowszych) zestawu SDK .NET parametr ConnectionPolicy dla konstruktora DocumentClient ma właściwość o nazwie Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations. Jest to właściwość typu Collection <string>, która powinna zawierać listę nazw regionów. Wartości ciągu są formatowane zgodnie z kolumną nazwa regionu na stronie Regiony platformy Azure bez spacji przed ani po pierwszym i ostatnim znaku.

Bieżące punkty końcowe zapisu i odczytu są dostępne odpowiednio we właściwościach DocumentClient.WriteEndpoint i DocumentClient.ReadEndpoint.

Uwaga

Adresów URL punktów końcowych nie należy traktować jako długotrwałych stałych. Usługa może zaktualizować je w dowolnym momencie. Zestaw SDK obsługuje tę zmianę automatycznie.

Jeśli używasz zestawu .NET V2 SDK, użyj PreferredLocations właściwości , aby ustawić preferowany region.

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

Alternatywnie możesz użyć SetCurrentLocation właściwości i pozwolić zestawowi SDK wybrać preferowaną lokalizację w oparciu o bliskość.

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

Uwaga

Adresów URL punktów końcowych nie należy traktować jako długotrwałych stałych. Usługa może zaktualizować je w dowolnym momencie. Zestaw SDK obsługuje tę zmianę automatycznie.

Poniżej znajduje się przykład kodu dla 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 } });

Zestaw SDK dla języka Python

Poniższy kod pokazuje, jak ustawić preferowane lokalizacje przy użyciu zestawu SDK języka Python:

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

Zestaw SDK języka Java w wersji 4

Poniższy kod pokazuje, jak ustawić preferowane lokalizacje przy użyciu zestawu SDK języka Java:

Zestaw Java SDK w wersji 4 (Maven com.azure::azure-cosmos) Asynchroniczny interfejs 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();

Łącznik platformy Spark 3

Preferowaną listę regionalną można zdefiniować przy użyciu spark.cosmos.preferredRegionsListkonfiguracji, na przykład:

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

REST

Po udostępnieniu konta bazy danych w wielu regionach klienci mogą wykonywać zapytania dotyczące jego dostępności, wykonując żądanie GET dla tego identyfikatora URI https://{databaseaccount}.documents.azure.com/

Usługa zwraca listę regionów i odpowiadające im identyfikatory URI punktów końcowych usługi Azure Cosmos DB dla replik. W odpowiedzi jest wskazywany bieżący region zapisu. Klient może następnie wybrać odpowiedni punkt końcowy dla wszystkich kolejnych żądań interfejsu API REST w pokazany poniżej sposób.

Przykładowa odpowiedź

{
    "_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
}
  • Wszystkie żądania PUT, POST i DELETE muszą być przekazywane do wskazanego identyfikatora URI zapisu
  • Wszystkie żądania GET i inne żądania tylko do odczytu (na przykład zapytania) mogą przechodzić do dowolnego punktu końcowego wybranego klienta

Żądania zapisu w regionach tylko do odczytu kończą się niepowodzeniem i wyświetlany jest kod błędu HTTP 403 („Dostęp zabroniony”).

Jeśli region zapisu zmieni się po fazie początkowego odnajdywania klienta, kolejne zapisy w poprzednim regionie zapisu zakończy się niepowodzeniem z kodem błędu HTTP 403 ("Zabronione"). Klient powinien wówczas ponownie uzyskać (żądanie GET) listę regionów, aby zaktualizować region zapisu.

To wszystko — na tym kończy się ten samouczek. Aby dowiedzieć się, jak zarządzać spójnością globalnie replikowanego konta, przeczytaj Poziomy spójności w usłudze Azure Cosmos DB. Natomiast aby uzyskać więcej informacji na temat sposobu działania globalnej replikacji w usłudze Azure Cosmos DB, zobacz Dystrybuowanie danych globalnie za pomocą usługi Azure Cosmos DB.

Następne kroki

W tym samouczku wykonano następujące czynności:

  • Konfigurowanie dystrybucji globalnej przy użyciu witryny Azure Portal
  • Konfigurowanie dystrybucji globalnej przy użyciu interfejsu API dla list NoSQLs

Teraz możesz przejść do następnego samouczka, aby dowiedzieć się, jak programować lokalnie przy użyciu lokalnego emulatora usługi Azure Cosmos DB.

Programowanie lokalnie za pomocą emulatora

Próbujesz zaplanować pojemność migracji do usługi Azure Cosmos DB? Do planowania pojemności można użyć informacji o istniejącym klastrze bazy danych.