Tutorial: Einrichten der globalen Verteilung von Azure Cosmos DB mithilfe der SQL-APITutorial: Set up Azure Cosmos DB global distribution using the SQL API

In diesem Artikel wird beschrieben, wie Sie mit dem Azure-Portal die globale Verteilung von Azure Cosmos DB einrichten und dann mithilfe der SQL-API eine Verbindung herstellen.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.

In diesem Artikel werden die folgenden Aufgaben behandelt:This article covers the following tasks:

  • Konfigurieren der globalen Verteilung mit dem Azure-PortalConfigure global distribution using the Azure portal
  • Konfigurieren der globalen Verteilung mit den SQL-APIsConfigure global distribution using the SQL APIs

Hinzufügen globaler Datenbankregionen über das Azure-PortalAdd global database regions using the Azure portal

Azure Cosmos DB ist in allen Azure-Regionen weltweit verfügbar.Azure Cosmos DB is available in all Azure regions worldwide. Nachdem Sie die Standardkonsistenzebene für Ihr Datenbankkonto ausgewählt haben, können Sie dem Konto eine oder mehrere Regionen zuordnen (je nachdem, welche Konsistenzebene Sie ausgewählt haben und welche Anforderungen an eine globale Verteilung bestehen).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. Klicken Sie im Azure-Portal auf der linken Leiste auf Azure Cosmos DB.In the Azure portal, in the left bar, click Azure Cosmos DB.

  2. Wählen Sie auf der Seite Azure Cosmos DB das zu ändernde Datenbankkonto aus.In the Azure Cosmos DB page, select the database account to modify.

  3. Klicken Sie auf der Kontoseite im Menü auf Daten global replizieren.In the account page, click Replicate data globally from the menu.

  4. Wählen Sie auf der Seite Daten global replizieren die Regionen aus, die Sie hinzufügen oder entfernen möchten. Klicken Sie hierzu auf die Regionen auf der Karte, und klicken Sie anschließend auf Speichern.In the Replicate data globally page, select the regions to add or remove by clicking regions in the map, and then click Save. Für das Hinzufügen von Regionen entstehen Kosten. Weitere Informationen hierzu finden Sie auf der Seite mit Preisinformationen sowie im Artikel Globale Verteilung von Daten mit Azure Cosmos DB.There is a cost to adding regions, see the pricing page or the Distribute data globally with Azure Cosmos DB article for more information.

    Hinzufügen oder Entfernen von Regionen per Klick auf die Regionen auf der Karte

Nachdem Sie eine zweite Region hinzugefügt haben, wird im Portal auf der Seite Daten global replizieren die Option Manuelles Failover aktiviert.Once you add a second region, the Manual Failover option is enabled on the Replicate data globally page in the portal. Sie können diese Option verwenden, um den Failovervorgang, zu testen oder die primäre Schreibregion zu ändern.You can use this option to test the failover process or change the primary write region. Nachdem Sie eine dritte Region hinzugefügt haben, wird auf der gleichen Seite die Option Failoverprioritäten aktiviert, sodass Sie die Failoverreihenfolge für Lesevorgänge ändern können.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.

Auswählen von globalen DatenbankregionenSelecting global database regions

Es gibt zwei gängige Szenarios zum Konfigurieren von mindestens zwei oder mehr Regionen:There are two common scenarios for configuring two or more regions:

  1. Übermitteln von niedriger Latenz beim Zugriff auf Daten für Endbenutzer, unabhängig davon, wo sie sich befindenDelivering low-latency access to data to end users no matter where they are located around the globe
  2. Hinzufügen von regionaler Resilienz für Geschäftskontinuität und Notfallwiederherstellung (BCDR)Adding regional resiliency for business continuity and disaster recovery (BCDR)

Zur Gewährleistung geringer Wartezeiten für Endbenutzer empfiehlt es sich, sowohl die Anwendung als auch Azure Cosmos DB in den Regionen bereitzustellen, in denen sich die Benutzer der Anwendung befinden.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.

Für BCDR empfiehlt es sich, die Regionen basierend auf den Regionspaaren hinzuzufügen, die im Artikel Geschäftskontinuität und Notfallwiederherstellung: Azure-Regionspaare beschrieben werden.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.

Herstellen einer Verbindung mit einer bevorzugten Region mithilfe der SQL-APIConnecting to a preferred region using the SQL API

Um von der globalen Verteilungzu profitieren, können Clientanwendungen in einer Liste die Reihenfolge angeben, in der Regionen bei Dokumentvorgängen bevorzugt verwendet werden sollen.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. Dies lässt sich durch Einrichten einer Verbindungsrichtlinie erreichen.This can be done by setting the connection policy. Basierend auf der Azure Cosmos DB-Kontokonfiguration, der aktuellen regionalen Verfügbarkeit und der angegebenen Liste der bevorzugten Regionen wählt das SQL SDK den optimalen Endpunkt für Schreib- und Lesevorgänge aus.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.

Diese Liste wird beim Initialisieren einer Verbindung mithilfe der SQL SDKs angegeben.This preference list is specified when initializing a connection using the SQL SDKs. Die SDKs akzeptieren einen optionalen Parameter „PreferredLocations“, bei dem es sich um eine sortierte Liste von Azure-Regionen handelt.The SDKs accept an optional parameter "PreferredLocations" that is an ordered list of Azure regions.

Das SDK sendet automatisch alle Schreibvorgänge an die aktuell für solche Vorgänge ausgewählte Region.The SDK will automatically send all writes to the current write region.

Alle Lesevorgänge werden an die erste verfügbare Region in der Liste der bevorzugten Regionen gesendet.All reads will be sent to the first available region in the PreferredLocations list. Wenn bei der Anforderung ein Fehler auftritt, führt der Client ein Failover zur nächsten Region auf der Liste durch, usw.If the request fails, the client will fail down the list to the next region, and so on.

Die SDKs versuchen nur, in den in „PreferredLocations“ angegebenen Regionen Lesevorgänge auszuführen.The SDKs will only attempt to read from the regions specified in PreferredLocations. Wenn ein Datenbankkonto in vier Regionen verfügbar ist, der Client aber nur zwei Leseregionen (non-write) für PreferredLocations angibt, werden keine Lesevorgänge aus einer Leseregion verarbeitet, die nicht in PreferredLocations angegeben ist.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. Wenn die in den PreferredLocations angegebenen Leseregionen nicht verfügbar sind, werden Lesevorgänge aus der Schreibregion verarbeitet.If the read regions specified in the PreferredLocations are not available, reads will be served out of write region.

Die Anwendung kann die vom SDK ausgewählten aktuellen Schreib- und Leseendpunkte anhand von zwei Eigenschaften überprüfen: WriteEndpoint und ReadEndpoint. Diese stehen im SDK der Version 1.8 und höher zur Verfügung.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.

Wenn die PreferredLocations-Eigenschaft nicht festgelegt ist, werden alle Anforderungen von der aktuellen Schreibregion verarbeitet.If the PreferredLocations property is not set, all requests will be served from the current write region.

.NET SDK.NET SDK

Das SDK kann ohne Codeänderungen verwendet werden.The SDK can be used without any code changes. In diesem Fall sendet das SDK automatisch sowohl Lese- als auch Schreibvorgänge an die aktuelle Schreibregion.In this case, the SDK automatically directs both reads and writes to the current write region.

Im .NET SDK, Version 1.8 oder höher, besitzt der ConnectionPolicy-Parameter für den DocumentClient-Konstruktor folgende Eigenschaft: 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. Diese Eigenschaft weist den Typ „Collection <string> “ auf und sollte eine Liste mit Regionsnamen enthalten.This property is of type Collection <string> and should contain a list of region names. Die Zeichenfolgenwerte sind gemäß der Spalte mit den Regionsnamen auf der Seite Azure-Regionen formatiert und enthalten keine Leerzeichen vor und nach dem ersten und letzten Zeichen.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.

Die aktuellen Schreib- und Leseendpunkte sind in DocumentClient.WriteEndpoint bzw. DocumentClient.ReadEndpoint verfügbar.The current write and read endpoints are available in DocumentClient.WriteEndpoint and DocumentClient.ReadEndpoint respectively.

Hinweis

Die URLs für die Endpunkte sollten nicht als langfristige Konstanten betrachtet werden.The URLs for the endpoints should not be considered as long-lived constants. Sie können jederzeit vom Dienst aktualisiert werden.The service may update these at any point. Das SDK verarbeitet diese Änderung automatisch.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

Hinweis

Die URLs für die Endpunkte sollten nicht als langfristige Konstanten betrachtet werden.The URLs for the endpoints should not be considered as long-lived constants. Sie können jederzeit vom Dienst aktualisiert werden.The service may update these at any point. Das SDK verarbeitet diese Änderung automatisch.The SDK will handle this change automatically.

Im Folgenden finden Sie ein Codebeispiel für Node.js/Javascript.Below is a code example for 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 SDKPython SDK

Der folgende Code zeigt, wie Sie mit dem Python SDK bevorzugte Standorte festlegen: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

Der folgende Code zeigt, wie Sie mit dem Java SDK bevorzugte Standorte festlegen: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

Sobald ein Datenbankkonto in mehreren Regionen zur Verfügung gestellt wurde, können Clients mithilfe einer GET-Anforderung über den folgenden URI die Verfügbarkeit des Kontos abfragen.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/

Der Dienst gibt eine Liste der Regionen und der zugehörigen Azure Cosmos DB-Endpunkt-URIs für die Replikate zurück.The service will return a list of regions and their corresponding Azure Cosmos DB endpoint URIs for the replicas. Die aktuelle Schreibregion wird in der Antwort angegeben.The current write region will be indicated in the response. Der Client kann dann wie folgt den geeigneten Endpunkt für alle weiteren REST-API-Anforderungen auswählen.The client can then select the appropriate endpoint for all further REST API requests as follows.

BeispielantwortExample 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
}
  • Alle PUT-, POST- und DELETE-Anforderungen müssen an den angegebenen Schreib-URI gesendet werden.All PUT, POST and DELETE requests must go to the indicated write URI
  • Alle GET-Anforderungen sowie weitere Anforderungen ohne Schreibzugriff (z.B. Abfragen) können an einen beliebigen vom Client ausgewählten Endpunkt gesendet werden.All GETs and other read-only requests (for example queries) may go to any endpoint of the client’s choice

Bei Schreibanforderungen an schreibgeschützte Regionen tritt der HTTP-Fehler 403 („Verboten“) auf.Write requests to read-only regions will fail with HTTP error code 403 ("Forbidden").

Wenn sich nach der anfänglichen Ermittlungsphase des Clients die Schreibregion ändert, tritt bei nachfolgenden Schreibanforderungen an die vorherige Schreibregion der HTTP-Fehler 403 („Verboten“) auf.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"). Der Client sollte dann erneut eine GET-Anforderung senden, um die Liste der Regionen erneut abzurufen und die aktualisierte Schreibregion zu empfangen.The client should then GET the list of regions again to get the updated write region.

Das ist alles, und dieses Tutorial ist abgeschlossen.That's it, that completes this tutorial. Informationen dazu, wie Sie die Konsistenz Ihres global replizierten Kontos verwalten, finden Sie unter Konsistenzebenen in Azure Cosmos DB.You can learn how to manage the consistency of your globally replicated account by reading Consistency levels in Azure Cosmos DB. Weitere Informationen zur Funktionsweise der globalen Datenbankreplikation in Azure Cosmos DB finden Sie unter Globale Verteilung von Daten mit 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.

Nächste SchritteNext steps

In diesem Tutorial haben Sie die folgenden Aufgaben ausgeführt:In this tutorial, you've done the following:

  • Konfigurieren der globalen Verteilung mit dem Azure-PortalConfigure global distribution using the Azure portal
  • Konfigurieren der globalen Verteilung mit den SQL-APIsConfigure global distribution using the SQL APIs

Sie können jetzt mit dem nächsten Tutorial fortfahren, um zu erfahren, wie Sie mit dem lokalen Azure Cosmos DB-Emulator lokal entwickeln können.You can now proceed to the next tutorial to learn how to develop locally using the Azure Cosmos DB local emulator.