Oktatóanyag: Az Azure Cosmos DB globális terjesztésének beállítása a NoSQL API használatával

  • Cikk

A KÖVETKEZŐKRE VONATKOZIK: NoSQL

Ebből a cikkből megtudhatja, hogyan állíthatja be az Azure Cosmos DB globális terjesztését a Azure Portal, majd hogyan csatlakozhat a NoSQL API-val.

Ez a cikk a következő feladatokat mutatja be:

  • Globális terjesztés konfigurálása az Azure Portallal
  • Globális terjesztés konfigurálása a NoSQLs API-val

Globális adatbázis-régiók hozzáadása az Azure Portal használatával

Az Azure Cosmos DB világszerte minden Azure-régióban elérhető. Miután kiválasztotta az adatbázisfiók alapértelmezett konzisztenciaszintjét, egy vagy több régiót társíthat hozzá (a választott alapértelmezett konzisztenciaszinttől és a globális terjesztés szükségleteitől függően).

  1. Az Azure Portalon a bal oldali sávon kattintson az Azure Cosmos DB lehetőségre.

  2. Az Azure Cosmos DB oldalon válassza ki a módosítandó adatbázis-fiókot.

  3. A fiók lapon kattintson az Adatok globális replikálása lehetőségre a menüben.

  4. A térkép régióira, majd a Mentés gombra kattintva választhatja ki a hozzáadni vagy eltávolítani kívánt régiókat az Adatok globális replikálása lapon. A régiók hozzáadásának költsége van, további információkat az árképzést ismertető oldalon vagy a Globális adatterjesztés az Azure Cosmos DB-vel című cikkben talál.

    Kattintson a térkép régióira azok hozzáadásához vagy eltávolításához

Ha hozzáadta a második régiót, elérhetővé válik a Manuális feladatátvétel funkció a Portal Adatok globális replikálása oldalán. Ezzel a funkcióval tesztelhető a feladatátvételi folyamat vagy módosítható az elsődleges írási régió. Miután hozzáadta a harmadik régiót, ugyanazon az oldalon elérhetővé válik a Feladatátvételi prioritások funkció, így módosíthatja az olvasások feladatátvételi sorrendjét.

Globális adatbázis-régiók kiválasztása

Két vagy több régió konfigurálására két gyakori forgatókönyv áll rendelkezésre:

  1. Kis késleltetésű adathozzáférés biztosítása a végfelhasználóknak, legyenek bárhol a világon
  2. Regionális rugalmasság hozzáadása az üzletmenet-folytonosság és a vészhelyreállítás (BCDR) érdekében

Ha kis késleltetést szeretne biztosítani a végfelhasználók számára, javasolt, hogy az alkalmazást és az Azure Cosmos DB-t is abban a régióban való helyezze üzembe, amelyben az alkalmazások felhasználói találhatók.

A BCDR esetében ajánlott régiókat hozzáadni az Azure régiók közötti replikációja: Üzletmenet-folytonosság és vészhelyreállítás című cikkben ismertetett régiópárok alapján.

Csatlakozás egy előnyben részesített régióhoz a NoSQL API használatával

A globális terjesztés kihasználása érdekében az ügyfélalkalmazások megadhatják a preferált régiók sorrendbe rendezett listáját a dokumentumokkal kapcsolatos műveletek elvégzéséhez. Az SQL SDK az Azure Cosmos DB-fiók konfigurációja, az aktuális régiónkénti rendelkezésre állás és a megadott preferencialista alapján fogja kiválasztani az optimális végpontot az írási és olvasási műveletek végrehajtásához.

A preferencialista meghatározására akkor kerül sor, amikor kapcsolatot inicializál az SQL SDK-k használatával. Az SDK-k elfogadnak egy választható paramétert PreferredLocations , amely az Azure-régiók rendezett listája.

Az SDK automatikusan elküldi az írásokat az aktuális írási régióba. A rendszer minden olvasást az előnyben részesített helyek listájában szereplő első elérhető régióba küld. Ha a kérés sikertelen, az ügyfél a következő régióba küldi a listát.

Az SDK csak az előnyben részesített helyeken megadott régiókból kísérli meg az olvasást. Így például, ha az Azure Cosmos DB-fiók négy régióban érhető el, de az ügyfél csak két olvasási (nem írási) régiót határoz meg a PreferredLocationsterületen belül, akkor nem lesznek olvasások kiszolgálva az olvasási régióból, amely nincs megadva a -ben PreferredLocations. Ha a listában megadott olvasási PreferredLocations régiók nem érhetők el, az olvasások az írási régión kívül lesznek kiszolgálva.

Az alkalmazás két tulajdonság ellenőrzésével ellenőrizheti az SDK által kiválasztott aktuális írási végpontot és olvasási végpontot, WriteEndpoint valamint ReadEndpointaz 1.8-es és újabb SDK-verzióban elérhető tulajdonságokat. Ha a PreferredLocations tulajdonság nincs beállítva, az összes kérés az aktuális írási régióból lesz kiszolgálva.

Ha nem adja meg az előnyben részesített helyeket, hanem a metódust setCurrentLocation használta, az SDK automatikusan feltölti az előnyben részesített helyeket az ügyfél által futtatott aktuális régió alapján. Az SDK a régiókat az aktuális régióhoz való közelség alapján rendeli meg.

.NET SDK

Az SDK a kód módosítása nélkül használható. Ebben az esetben az SDK automatikusan átirányítja az olvasásokat és az írásokat az aktuális írási régióba.

A .NET SDK 1.8-as és újabb verzióiban a DocumentClient konstruktor ConnectionPolicy paramétere rendelkezik egy Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations nevű tulajdonsággal. Ez a tulajdonság egy <string> típusú gyűjtemény, amelynek egy listát kell tartalmaznia a régiónevekkel. A sztringértékek az Azure Regions (Azure-régiók ) oldal Régiónév oszlopában vannak formázva, az első és az utolsó karakter előtt és után szóközök nélkül.

Az aktuális írási és olvasási végpontokat a DocumentClient.WriteEndpoint és a DocumentClient.ReadEndpoint tulajdonság tartalmazza.

Megjegyzés

A végpontok URL-címei nem tekinthetők hosszú élettartamú állandóknak. A szolgáltatás bármikor frissítheti őket. Az SDK automatikusan kezeli ezt a módosítást.

Ha a .NET V2 SDK-t használja, a PreferredLocations tulajdonság használatával állítsa be az előnyben részesített régiót.

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

Másik lehetőségként használhatja a SetCurrentLocation tulajdonságot, és hagyhatja, hogy az SDK a közelség alapján válassza ki az előnyben részesített helyet.

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

Megjegyzés

A végpontok URL-címei nem tekinthetők hosszú élettartamú állandóknak. A szolgáltatás bármikor frissítheti őket. Az SDK automatikusan kezeli ezt a módosítást.

Az alábbiakban egy példakód látható a /JavaScript Node.js.

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

Az alábbi kód bemutatja, hogyan állíthatja be az előnyben részesített helyeket a Python SDK használatával:

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

Java V4 SDK

Az alábbi kód bemutatja, hogyan állíthatja be az előnyben részesített helyeket a Java SDK használatával:

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-összekötő

Az előnyben részesített regionális listát a konfigurációvalspark.cosmos.preferredRegionsList határozhatja meg, például:

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

REST

Ha egy adatbázisfiók több régióban is elérhetővé vált, az ügyfelek lekérdezhetik a rendelkezésre állását egy GET kérés végrehajtásával ezen az URI-n https://{databaseaccount}.documents.azure.com/

A szolgáltatás visszaadja a régiók listáját és a replikák régiókhoz tartozó Azure Cosmos-DB végpont URI-jait. A válasz az aktuális írási régiót is tartalmazni fogja. Az ügyfél ezután a következő módon választhatja ki a megfelelő végpontot a további REST API-kérésekhez.

Példaválasz

{
    "_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
}
  • Az összes PUT, POST és DELETE kérelemnek a megadott írási URI-ra kell érkeznie
  • Az összes GET és más írásvédett kérés (például lekérdezések) az ügyfél tetszőleges végpontjára kerülhetnek

A csak olvasási régiókba érkező írási kérelmek a 403-as HTTP-hibakóddal („Tiltott”) hiúsulnak meg.

Ha az írási régió az ügyfél kezdeti felderítési fázisa után változik, az előző írási régióba történő későbbi írások meghiúsulnak a 403-at tartalmazó HTTP-hibakóddal ("Tiltott"). Az ügyfélnek ilyenkor ismét le kell kérnie a régiók listáját a GET metódussal a frissített írási régió beszerzéséhez.

Ezzel el is végezte az oktatóanyagot. Ha meg szeretné ismerni, hogyan kezelheti a globálisan replikált fiók konzisztenciáját, olvassa el a Konzisztenciaszintek az Azure Cosmos DB-ben című cikket. További információ a globális adatbázis-replikáció működéséről az Azure Cosmos DB szolgáltatásban: Globális adatterjesztés az Azure Cosmos DB-vel.

Következő lépések

Ebben az oktatóanyagban a következőket hajtotta végre:

  • Globális terjesztés konfigurálása az Azure Portallal
  • Globális terjesztés konfigurálása a NoSQLs API-val

Továbbléphet a következő oktatóanyagra, amelyből megtudhatja, hogyan fejleszthet helyileg az Azure Cosmos DB helyi emulátorával.

Helyi fejlesztés az emulátorral

Kapacitástervezést szeretne végezni az Azure Cosmos DB-be való migráláshoz? A kapacitástervezéshez használhatja a meglévő adatbázisfürtre vonatkozó információkat.