Udostępnij przez

Samouczek: konfigurowanie dystrybucji globalnej przy użyciu usługi Azure Cosmos DB for NoSQL

  • Dotyczy: ✅ NoSQL

W tym artykule pokazano, jak za pomocą witryny Azure Portal skonfigurować dystrybucję globalną usługi Azure Cosmos DB, 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 za pomocą interfejsu API dla baz danych NoSQL

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 opcja Ręczne przełączenie awaryjne zostanie udostępniona na stronie Globalna replikacja danych w portalu. Ta opcja umożliwia testowanie procesu pracy awaryjnej lub zmianę podstawowego regionu zapisu. Po dodaniu trzeciego regionu na tej samej stronie zostaje udostępniona opcja Priorytety trybu failover, dzięki czemu możesz zmienić kolejność failover 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 regionalnej odporności dla ciągłości 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 BCDR zaleca się dodawanie regionów w oparciu o pary regionów opisane 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 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 są wysyłane do pierwszego dostępnego regionu na liście preferowanych lokalizacji. Jeśli żądanie zakończy się niepowodzeniem, klient przejdzie na następny region z listy.

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 PreferredLocations, nie są obsługiwane żadne operacje odczytu z regionu odczytu, który nie jest określony w pliku PreferredLocations. Jeśli regiony odczytu określone na PreferredLocations liście nie są dostępne, odczyty są 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 i WriteEndpointReadEndpoint, dostępną w zestawie SDK w wersji 1.8 lub nowszej. Jeśli właściwość nie jest ustawiona PreferredLocations , wszystkie żądania są 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.

Pakiet SDK dla platformy .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 lub 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 / Notatka

Adresy URL punktów końcowych nie powinny być traktowane jako stałe długotrwałe. 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);

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

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

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

Uwaga / Notatka

Adresy URL punktów końcowych nie powinny być traktowane jako stałe długotrwałe. 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, aadCredentials: tokenCredential, 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, credential=token_credential, 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:

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

Łą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.preferredRegionsList" -> "[West US, East US, North Europe]"
  // other settings
)

Zestaw SDK dla języka Go

Aby włączyć wiele regionów w aplikacji, użyj polecenia PreferredRegionsClientOptions:

client, err := azcosmos.NewClient(endpoint, token, &azcosmos.ClientOptions{
	PreferredRegions: []string{"West US", "Central US"},
})

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ących im identyfikatorów URI punktów końcowych usługi Azure Cosmos DB dla replik. Bieżący region zapisu jest wskazywany w odpowiedzi. 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ć kierowane do wskazanego URI zapisu
  • Wszystkie żądania GET i inne żądania tylko do odczytu (na przykład zapytania) mogą trafić do dowolnego punktu końcowego według wyboru 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 początkowej fazie odkrywania przez klienta, kolejne zapisy w poprzednim regionie zapisu zakończą 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.

Dalsze 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ć zasoby na potrzeby migracji do usługi Azure Cosmos DB? Informacje o istniejącym klastrze bazy danych można użyć do planowania pojemności.

  • Last updated on