Tutorial: Einrichten der globalen Verteilung von Azure Cosmos DB mithilfe der API für NoSQL

  • Artikel

GILT FÜR: NoSQL

In diesem Artikel wird beschrieben, wie Sie mit dem Azure-Portal die globale Verteilung von Azure Cosmos DB einrichten und dann mithilfe der API für NoSQL eine Verbindung herstellen.

In diesem Artikel werden die folgenden Aufgaben behandelt:

  • Konfigurieren der globalen Verteilung mit dem Azure-Portal
  • Konfigurieren der globalen Verteilung mit der API für NoSQL

Hinzufügen globaler Datenbankregionen über das Azure-Portal

Azure Cosmos DB ist in allen Azure-Regionen weltweit verfügbar. 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).

  1. Klicken Sie im Azure-Portal auf der linken Leiste auf Azure Cosmos DB.

  2. Wählen Sie auf der Seite Azure Cosmos DB das zu ändernde Datenbankkonto aus.

  3. Klicken Sie auf der Kontoseite im Menü auf Daten global replizieren.

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

    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. Sie können diese Option verwenden, um den Failovervorgang, zu testen oder die primäre Schreibregion zu ändern. 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.

Auswählen von globalen Datenbankregionen

Es gibt zwei gängige Szenarios zum Konfigurieren von mindestens zwei oder mehr Regionen:

  1. Übermitteln von niedriger Latenz beim Zugriff auf Daten für Endbenutzer, unabhängig davon, wo sie sich befinden
  2. Hinzufügen von regionaler Resilienz für Geschäftskontinuität und Notfallwiederherstellung (Business Continuity & 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.

Für BCDR empfiehlt es sich, die Regionen basierend auf den Regionspaaren hinzuzufügen, die im Artikel Regionsübergreifende Replikation in Azure: Business Continuity & Disaster Recovery beschrieben sind.

Herstellen einer Verbindung mit einer bevorzugten Region mithilfe der API für NoSQL

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

Diese Liste wird beim Initialisieren einer Verbindung mithilfe der SQL SDKs angegeben. Die SDKs akzeptieren einen optionalen Parameter PreferredLocations, bei dem es sich um eine sortierte Liste von Azure-Regionen handelt.

Das SDK sendet automatisch alle Schreibvorgänge an die aktuell für solche Vorgänge ausgewählte Region. Alle Lesevorgänge werden an die erste verfügbare Region in der Liste der bevorzugten Regionen gesendet. Wenn bei der Anforderung ein Fehler auftritt, führt der Client ein Failover zur nächsten Region auf der Liste durch.

Das SDK versucht nur in den Regionen, die als bevorzugte Regionen angegeben wurden, Lesevorgänge auszuführen. Wenn beispielsweise ein Azure Cosmos DB-Konto in vier Regionen verfügbar ist, der Client aber nur zwei Leseregionen (non-write) in PreferredLocations angibt, werden keine Lesevorgänge aus einer Leseregion verarbeitet, die nicht in PreferredLocations angegeben ist. Wenn die in der Liste PreferredLocations angegebenen Leseregionen nicht verfügbar sind, werden Lesevorgänge aus der Schreibregion verarbeitet.

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. Wenn die Eigenschaft PreferredLocations nicht festgelegt ist, werden alle Anforderungen von der aktuellen Schreibregion verarbeitet.

Wenn Sie die bevorzugten Regionen nicht angeben, aber die setCurrentLocation-Methode verwendet haben, füllt das SDK die bevorzugten Regionen automatisch basierend auf der aktuellen Region auf, in der der Client ausgeführt wird. Das SDK ordnet die Regionen auf Grundlage der Nähe einer Region zur aktuellen Region an.

.NET SDK

Das SDK kann ohne Codeänderungen verwendet werden. In diesem Fall sendet das SDK automatisch sowohl Lese- als auch Schreibvorgänge an die aktuelle Schreibregion.

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. Diese Eigenschaft weist den Typ „Collection <string> “ auf und sollte eine Liste mit Regionsnamen enthalten. 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.

Die aktuellen Schreib- und Leseendpunkte sind in DocumentClient.WriteEndpoint bzw. DocumentClient.ReadEndpoint verfügbar.

Hinweis

Die URLs für die Endpunkte sollten nicht als langfristige Konstanten betrachtet werden. Sie können jederzeit vom Dienst aktualisiert werden. Das SDK verarbeitet diese Änderung automatisch.

Wenn Sie das .NET V2 SDK verwenden, legen Sie die bevorzugte Region mithilfe der Eigenschaft PreferredLocations fest.

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

Sie können auch die Eigenschaft SetCurrentLocation verwenden und dem SDK erlauben, die bevorzugte Region basierend auf der Nähe auszuwählen.

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

Hinweis

Die URLs für die Endpunkte sollten nicht als langfristige Konstanten betrachtet werden. Sie können jederzeit vom Dienst aktualisiert werden. Das SDK verarbeitet diese Änderung automatisch.

Im Folgenden finden Sie ein Codebeispiel für 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

Der folgende Code zeigt, wie Sie mit dem Python SDK bevorzugte Standorte festlegen:

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

Java V4 SDK

Der folgende Code zeigt, wie Sie mit dem Java SDK bevorzugte Standorte festlegen:

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

Spark 3-Connector

Sie können die bevorzugte regionale Liste mithilfe der spark.cosmos.preferredRegionsList-Konfiguration definieren, z. B.:

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

REST

Sobald ein Datenbankkonto in mehreren Regionen zur Verfügung gestellt wurde, können Clients mithilfe einer GET-Anforderung über diesen URI https://{databaseaccount}.documents.azure.com/ die Verfügbarkeit des Kontos abfragen.

Der Dienst gibt eine Liste der Regionen und der zugehörigen Azure Cosmos DB-Endpunkt-URIs für die Replikate zurück. Die aktuelle Schreibregion wird in der Antwort angegeben. Der Client kann dann wie folgt den geeigneten Endpunkt für alle weiteren REST-API-Anforderungen auswählen.

Beispielantwort

{
    "_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.
  • Alle GET-Anforderungen sowie weitere Anforderungen ohne Schreibzugriff (z. B. Abfragen) können an einen beliebigen vom Client ausgewählten Endpunkt gesendet werden.

Bei Schreibanforderungen an schreibgeschützte Regionen tritt der HTTP-Fehler 403 („Verboten“) auf.

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. Der Client sollte dann erneut eine GET-Anforderung senden, um die Liste der Regionen erneut abzurufen und die aktualisierte Schreibregion zu empfangen.

Das ist alles, und dieses Tutorial ist abgeschlossen. Informationen dazu, wie Sie die Konsistenz Ihres global replizierten Kontos verwalten, finden Sie unter Konsistenzebenen 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.

Nächste Schritte

In diesem Tutorial haben Sie die folgenden Aufgaben ausgeführt:

  • Konfigurieren der globalen Verteilung mit dem Azure-Portal
  • Konfigurieren der globalen Verteilung mit der API für NoSQL

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.

Lokales Entwickeln mit dem Emulator

Versuchen Sie, die Kapazitätsplanung für eine Migration zu Azure Cosmos DB durchzuführen? Sie können Informationen zu Ihrem vorhandenen Datenbankcluster für die Kapazitätsplanung verwenden.