Konfigurowanie dystrybucji globalnej usługi Azure Cosmos DB przy użyciu interfejsu SQL APISet up Azure Cosmos DB global distribution using the SQL API

W tym artykule pokazujemy, 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 SQL.In this article, we show how to use the Azure portal to setup Azure Cosmos DB global distribution and then connect using the SQL API.

W tym artykule opisano następujące zadania:This article covers the following tasks:

  • Konfigurowanie dystrybucji globalnej przy użyciu witryny Azure PortalConfigure global distribution using the Azure portal
  • Konfigurowanie dystrybucji globalnej przy użyciu interfejsów API SQLConfigure global distribution using the SQL APIs

Dodawanie regionów globalnej bazy danych przy użyciu witryny Azure PortalAdd global database regions using the Azure portal

Usługa Azure Cosmos DB jest dostępna we wszystkich regionach świadczenia usługi Azure na całym świecie.Azure Cosmos DB is available in all Azure regions worldwide. 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).After selecting the default consistency level for your database account, you can associate one or more regions (depending on your choice of default consistency level and global distribution needs).

  1. W witrynie Azure Portal na pasku po lewej stronie kliknij pozycję Azure Cosmos DB.In the Azure portal, in the left bar, click Azure Cosmos DB.

  2. Na stronie usługi Azure Cosmos DB wybierz konto bazy danych do modyfikacji.In the Azure Cosmos DB page, select the database account to modify.

  3. Na stronie konta kliknij w menu pozycję Replikuj dane globalnie.In the account page, click Replicate data globally from the menu.

  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.In the Replicate data globally page, select the regions to add or remove by clicking regions in the map, and then click Save. Dodanie regionu nic nie kosztuje, zobacz cennik lub artykuł Globalna dystrybucja danych za pomocą usługi Azure Cosmos DB, aby uzyskać więcej informacji.There is a cost to adding regions, see the pricing page or the Distribute data globally with Azure Cosmos DB article for more information.

    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.Once you add a second region, the Manual Failover option is enabled on the Replicate data globally page in the portal. Ta opcja umożliwia testowanie procesu pracy awaryjnej lub zmianę podstawowego regionu zapisu.You can use this option to test the failover process or change the primary write region. 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.Once you add a third region, the Failover Priorities option is enabled on the same page so that you can change the failover order for reads.

Wybieranie regionów globalnej bazy danychSelecting global database regions

Istnieją dwa typowe scenariusze konfigurowania co najmniej dwóch regionów:There are two common scenarios for configuring two or more regions:

  1. Zapewnienie użytkownikom końcowym dostępu z małym opóźnieniem niezależnie od tego, gdzie znajdują się na całym świecieDelivering low-latency access to data to end users no matter where they are located around the globe
  2. Dodawanie regionalnych odporności dla ciągłości prowadzenia działalności biznesowej i odzyskiwania po awarii (BCDR)Adding regional resiliency for business continuity and disaster recovery (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.For delivering low-latency to end users, it is recommended that you deploy both the application and Azure Cosmos DB in the regions that correspond to where the application's users are located.

W przypadku BCDR zalecane jest dodawanie regionów na podstawie par regionów opisanych w artykule Ciągłość działania i odzyskiwanie po awarii (BCDR): sparowane regiony platformy Azure.For BCDR, it is recommended to add regions based on the region pairs described in the Business continuity and disaster recovery (BCDR): Azure Paired Regions article.

Nawiązywanie połączenia z preferowanym regionem przy użyciu interfejsu API SQLConnecting to a preferred region using the SQL API

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.In order to take advantage of global distribution, client applications can specify the ordered preference list of regions to be used to perform document operations. Można to zrobić, ustawiając zasady połączenia.This can be done by setting the connection policy. 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.Based on the Azure Cosmos DB account configuration, current regional availability and the preference list specified, the most optimal endpoint will be chosen by the SQL SDK to perform write and read operations.

Lista preferencji jest określana podczas inicjowania połączenia przy użyciu zestawów SDK SQL.This preference list is specified when initializing a connection using the SQL SDKs. Zestawy SDK akceptują opcjonalny parametr „PreferredLocations”, to znaczy uporządkowaną listę regionów świadczenia usługi Azure.The SDKs accept an optional parameter "PreferredLocations" that is an ordered list of Azure regions.

Zestaw SDK automatycznie wysyła wszystkie operacje zapisu do bieżącego regionu zapisu.The SDK will automatically send all writes to the current write region.

Wszystkie operacje odczytu są wysyłane do pierwszego dostępnego regionu na liście PreferredLocations.All reads will be sent to the first available region in the PreferredLocations list. Jeśli żądanie kończy się niepowodzeniem, klient przechodzi do następnego regionu z listy itd.If the request fails, the client will fail down the list to the next region, and so on.

Zestawy SDK podejmują próby odczytu tylko z regionów określonych na liście PreferredLocations.The SDKs will only attempt to read from the regions specified in PreferredLocations. Na przykład jeśli konto bazy danych jest dostępne w czterech regionach, ale klient określa tylko dwa regiony odczytu (nie zapisu) na liście PreferredLocations, operacje odczytu z regionu odczytu, który nie jest określony na liście PreferredLocations, nie są obsługiwane.So, for example, if the Database Account is available in four regions, but the client only specifies two read(non-write) regions for PreferredLocations, then no reads will be served out of the read region that is not specified in PreferredLocations. Jeśli regiony odczytu określone na liście PreferredLocations są niedostępne, operacje odczytu są obsługiwane przez region zapisu.If the read regions specified in the PreferredLocations are not available, reads will be served out of write region.

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 i nowszych.The application can verify the current write endpoint and read endpoint chosen by the SDK by checking two properties, WriteEndpoint and ReadEndpoint, available in SDK version 1.8 and above.

Jeśli właściwość PreferredLocations nie została określona, wszystkie żądania są obsługiwane z bieżącego regionu zapisu.If the PreferredLocations property is not set, all requests will be served from the current write region.

Zestaw SDK .NET.NET SDK

Zestawu SDK można używać bez konieczności wprowadzania jakichkolwiek zmian kodu.The SDK can be used without any code changes. W takim przypadku zestaw SDK automatycznie kieruje operacje odczytu i zapisu do bieżącego regionu zapisu.In this case, the SDK automatically directs both reads and writes to the current write region.

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.In version 1.8 and later of the .NET SDK, the ConnectionPolicy parameter for the DocumentClient constructor has a property called Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations. Jest to właściwość typu Collection <string>, która powinna zawierać listę nazw regionów.This property is of type Collection <string> and should contain a list of region names. Wartości ciągu są sformatowane według kolumny Nazwa regionu na regionów platformy Azure strony, bez spacji przed ani po pierwszym i ostatnim znaku.The string values are formatted per the Region Name column on the Azure Regions page, with no spaces before or after the first and last character respectively.

Bieżące punkty końcowe zapisu i odczytu są dostępne odpowiednio we właściwościach DocumentClient.WriteEndpoint i DocumentClient.ReadEndpoint.The current write and read endpoints are available in DocumentClient.WriteEndpoint and DocumentClient.ReadEndpoint respectively.

Uwaga

Adresów URL punktów końcowych nie należy traktować jako długotrwałych stałych.The URLs for the endpoints should not be considered as long-lived constants. Usługa może zaktualizować je w dowolnym momencie.The service may update these at any point. Zestaw SDK obsługuje tę zmianę automatycznie.The SDK handles this change automatically.

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

Node.js/JavaScriptNode.js/JavaScript

Zestawu SDK można używać bez konieczności wprowadzania jakichkolwiek zmian kodu.The SDK can be used without any code changes. W takim przypadku zestaw SDK automatycznie kieruje operacje odczytu i zapisu do bieżącego regionu zapisu.In this case, the SDK will automatically direct both reads and writes to the current write region.

W wersji 1.8 (i nowszych) każdego zestawu SDK parametr ConnectionPolicy dla konstruktora DocumentClient ma nową właściwość o nazwie DocumentClient.ConnectionPolicy.PreferredLocations.In version 1.8 and later of each SDK, the ConnectionPolicy parameter for the DocumentClient constructor a new property called DocumentClient.ConnectionPolicy.PreferredLocations. Ten parametr jest tablicą ciągów, która przyjmuje listę nazw regionów.This is parameter is an array of strings that takes a list of region names. Nazwy są sformatowane według kolumny Nazwa regionu regionów platformy Azure strony.The names are formatted per the Region Name column in the Azure Regions page. Możesz również używać wstępnie zdefiniowanych stałych w obiekcie wygody AzureDocuments.RegionsYou can also use the predefined constants in the convenience object AzureDocuments.Regions

Bieżące punkty końcowe zapisu i odczytu są dostępne odpowiednio we właściwościach DocumentClient.getWriteEndpoint i DocumentClient.getReadEndpoint.The current write and read endpoints are available in DocumentClient.getWriteEndpoint and DocumentClient.getReadEndpoint respectively.

Uwaga

Adresów URL punktów końcowych nie należy traktować jako długotrwałych stałych.The URLs for the endpoints should not be considered as long-lived constants. Usługa może zaktualizować je w dowolnym momencie.The service may update these at any point. Zestaw SDK obsługuje tę zmianę automatycznie.The SDK will handle this change automatically.

Poniżej przedstawiono przykładowy kod dla Node.js/Javascript.Below is a code example for Node.js/Javascript.

// Creating a ConnectionPolicy object
var connectionPolicy = new DocumentBase.ConnectionPolicy();

// Setting read region selection preference, in the following order -
// 1 - West US
// 2 - East US
// 3 - North Europe
connectionPolicy.PreferredLocations = ['West US', 'East US', 'North Europe'];

// initialize the connection
var client = new DocumentDBClient(host, { masterKey: masterKey }, connectionPolicy);

Zestaw SDK dla języka PythonPython SDK

Poniższy kod pokazuje, jak skonfigurować preferowanych lokalizacji przy użyciu zestawu SDK języka Python:The following code shows how to set preferred locations by using the Python SDK:


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

Java V2 SDKJava V2 SDK

Poniższy kod pokazuje, jak skonfigurować preferowanych lokalizacji przy użyciu zestawu Java SDK:The following code shows how to set preferred locations by using the Java SDK:

ConnectionPolicy policy = new ConnectionPolicy();
policy.setUsingMultipleWriteLocations(true);
policy.setPreferredLocations(Arrays.asList("East US", "West US", "Canada Central"));
AsyncDocumentClient client =
        new AsyncDocumentClient.Builder()
                .withMasterKeyOrResourceToken(this.accountKey)
                .withServiceEndpoint(this.accountEndpoint)
                .withConnectionPolicy(policy)
                .build();

RESTREST

Gdy konto bazy danych zostało udostępnione w wielu regionach, klienci mogą wysyłać zapytania o jego dostępność, wykonując żądanie GET względem poniższego identyfikatora URI.Once a database account has been made available in multiple regions, clients can query its availability by performing a GET request on the following 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.The service will return a list of regions and their corresponding Azure Cosmos DB endpoint URIs for the replicas. W odpowiedzi jest wskazywany bieżący region zapisu.The current write region will be indicated in the response. Klient może następnie wybrać odpowiedni punkt końcowy dla wszystkich kolejnych żądań interfejsu API REST w pokazany poniżej sposób.The client can then select the appropriate endpoint for all further REST API requests as follows.

Przykładowa odpowiedźExample response

{
    "_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 zapisuAll PUT, POST and DELETE requests must go to the indicated write URI
  • Wszystkie żądania GET i pozostałe żądania tylko do odczytu (na przykład zapytania) mogą być przekazywane do dowolnego punktu końcowego wybranego przez klientaAll GETs and other read-only requests (for example queries) may go to any endpoint of the client’s choice

Żądania zapisu w regionach tylko do odczytu kończą się niepowodzeniem i wyświetlany jest kod błędu HTTP 403 („Dostęp zabroniony”).Write requests to read-only regions will fail with HTTP error code 403 ("Forbidden").

Jeśli region zapisu zmienia się po fazie początkowego odnajdywania klienta, kolejne operacje zapisu w poprzednim regionie zapisu kończą się niepowodzeniem i wyświetlany jest kod błędu HTTP 403 („Dostęp zabroniony”).If the write region changes after the client’s initial discovery phase, subsequent writes to the previous write region will fail with HTTP error code 403 ("Forbidden"). Klient powinien wówczas ponownie uzyskać (żądanie GET) listę regionów, aby zaktualizować region zapisu.The client should then GET the list of regions again to get the updated write region.

To wszystko — na tym kończy się ten samouczek.That's it, that completes this tutorial. Aby dowiedzieć się, jak zarządzać spójnością globalnie replikowanego konta, przeczytaj Poziomy spójności w usłudze Azure Cosmos DB.You can learn how to manage the consistency of your globally replicated account by reading Consistency levels in 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.And for more information about how global database replication works in Azure Cosmos DB, see Distribute data globally with Azure Cosmos DB.

Następne krokiNext steps

W tym samouczku wykonano następujące czynności:In this tutorial, you've done the following:

  • Konfigurowanie dystrybucji globalnej przy użyciu witryny Azure PortalConfigure global distribution using the Azure portal
  • Konfigurowanie dystrybucji globalnej przy użyciu interfejsów API SQLConfigure global distribution using the SQL APIs

Teraz możesz przejść do następnego samouczka, aby dowiedzieć się, jak programować lokalnie przy użyciu lokalnego emulatora usługi Azure Cosmos DB.You can now proceed to the next tutorial to learn how to develop locally using the Azure Cosmos DB local emulator.