Esercitazione: Configurare la distribuzione globale di Azure Cosmos DB usando l'API per NoSQL

  • Articolo

SI APPLICA A: NoSQL

In questo articolo viene illustrato come usare il portale di Azure per configurare la distribuzione globale di Azure Cosmos DB e quindi connettersi usando l'API per NoSQL.

Questo articolo illustra le attività seguenti:

  • Configurare la distribuzione globale tramite il portale di Azure
  • Configurare la distribuzione globale usando l'API per NoSQLs

Aggiungere aree di database globali tramite il portale di Azure

Azure Cosmos DB è disponibile in tutte le aree di Azure a livello mondiale. Dopo aver selezionato il livello di coerenza predefinito per l'account di database, è possibile associare una o più aree, a seconda del livello di coerenza predefinito e delle esigenze di distribuzione globale scelti.

  1. Nella barra a sinistra del portale di Azure fare clic su Azure Cosmos DB.

  2. Nella pagina Azure Cosmos DB selezionare l'account di database da modificare.

  3. Nella pagina dell'account fare clic su Replica i dati a livello globale dal menu.

  4. Nella pagina Replica i dati a livello globale selezionare le aree da aggiungere o rimuovere facendo clic su di esse nella mappa e quindi scegliere Salva. L'aggiunta di aree ha un costo. Per altre informazioni, vedere la pagina relativa ai prezzi o l'articolo Distribuire i dati a livello globale con Azure Cosmos DB.

    Fare clic sulle aree nella mappa per aggiungerle o rimuoverle

Dopo l'aggiunta di una seconda area, viene abilitata l'opzione Failover manuale nella pagina Replica i dati a livello globale del portale. È possibile usare questa opzione per testare il processo di failover o per modificare l'area di scrittura primaria. Dopo avere aggiunto una terza area, l'opzione Priorità di failover viene abilitata nella stessa pagina per poter modificare l'ordine di failover per le operazioni di lettura.

Selezionare aree di database globali

Esistono due scenari comuni per la configurazione di due o più aree:

  1. Offerta di accesso con bassa latenza ai dati indipendentemente dalla posizione del mondo in cui si trovano gli utenti finali
  2. Aggiunta di resilienza a livello di area per garantire continuità aziendale e ripristino di emergenza (BCDR)

Per offrire l'accesso con bassa latenza agli utenti finali, è consigliabile distribuire l'applicazione e Azure Cosmos DB nelle aree corrispondenti alla località in cui si trovano gli utenti dell'applicazione.

Per BCDR, è consigliabile aggiungere aree in base alle coppie di aree descritte nell'articolo Replica tra aree in Azure: Continuità aziendale e ripristino di emergenza .

Connessione a un'area preferita tramite l'API per NoSQL

Per sfruttare la distribuzione globale, le applicazioni client possono specificare un elenco di aree, nell'ordine preferito, da usare per eseguire operazioni sui documenti. A seconda della configurazione dell'account Azure Cosmos DB, della disponibilità corrente delle aree e dell'elenco delle preferenze specificato, l'SDK SQL sceglierà l'endpoint ottimale per eseguire le operazioni di scrittura e lettura.

L'elenco delle preferenze viene specificato nella fase di inizializzazione di una connessione usando gli SDK SQL. Gli SDK accettano un parametro opzionale PreferredLocations, ovvero un elenco ordinato di aree di Azure.

L'SDK invia automaticamente tutte le scritture all'area di scrittura corrente. Tutte le letture verranno inviate alla prima area disponibile nell'elenco delle località preferite. Se la richiesta ha esito negativo, il client passerà all'area dell'elenco successiva.

L'SDK tenterà la lettura solo dalle aree specificate nelle località preferite. Ad esempio, se l'account Azure Cosmos DB è disponibile in quattro aree, ma il client specifica solo due aree di lettura (non scrittura) all'interno PreferredLocationsdi , non verranno gestite letture dall'area di lettura non specificata in PreferredLocations. Se le aree di letture specificate nell'elenco PreferredLocations non sono disponibili, le letture verranno distribuite dall'area di scrittura.

L'applicazione è in grado di verificare l'endpoint di scrittura e l'endpoint di lettura correnti scelti dall'SDK controllando due proprietà, WriteEndpoint e ReadEndpoint, disponibili nell'SDK versione 1.8 e versioni successive. Se la proprietà PreferredLocations non è impostata, tutte le richieste verranno distribuite dall'area di scrittura corrente.

Se non si specificano le località preferite, ma si usa il metodo setCurrentLocation, l'SDK specificherà automaticamente le località preferite in base all'area corrente in cui è in esecuzione il client. L'SDK ordina le aree in base alla prossimità di un'area a quella corrente.

.NET SDK

L'SDK può essere usato senza alcuna modifica del codice. In questo caso l'SDK reindirizza automaticamente sia le operazioni di lettura che di scrittura all'area di scrittura corrente.

Nella versione 1.8 e nelle versioni successive di .NET SDK, il parametro ConnectionPolicy per il costruttore DocumentClient dispone di una proprietà denominata Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations. Questa proprietà è di tipo raccolta <string> e deve contenere un elenco di nomi di aree. I valori stringa vengono formattati in base alla colonna dei nomi delle aree disponibile nella pagina Aree di Azure. Prima del primo carattere e dopo l'ultimo carattere non viene immesso alcuno spazio.

Gli endpoint di lettura e scrittura correnti sono disponibili rispettivamente in DocumentClient.WriteEndpoint e DocumentClient.ReadEndpoint.

Nota

Gli URL per gli endpoint non devono essere considerati come costanti di lunga durata. Il servizio può aggiornare gli URL in qualsiasi momento. L'SDK gestisce la modifica in modo automatico.

Se si usa .NET v2 SDK, impostare l'area preferita tramite la proprietà PreferredLocations.

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

In alternativa, è possibile usare la proprietà SetCurrentLocation e consentire all'SDK di scegliere la località preferita in base alla prossimità.

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

Nota

Gli URL per gli endpoint non devono essere considerati come costanti di lunga durata. Il servizio può aggiornare gli URL in qualsiasi momento. L'SDK gestirà questa modifica in automatico.

Di seguito è riportato un esempio di codice per 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

Il codice seguente illustra come impostare le località preferite usando Python SDK:

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

Java v4 SDK

Il codice seguente illustra come impostare le località preferite usando Java SDK:

API asincrona Java SDK V4 (Maven com.azure::azure-cosmos)


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

Connettore Spark 3

È possibile definire l'elenco di aree preferite usando la spark.cosmos.preferredRegionsListconfigurazione, ad esempio:

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

REST

Dopo aver reso disponibile un account di database in più aree, i client possono eseguire query sulla disponibilità eseguendo una richiesta GET su questo URI https://{databaseaccount}.documents.azure.com/

Il servizio restituirà un elenco delle aree e i relativi URI dell'endpoint Azure Cosmos DB per le repliche. L'area di scrittura corrente verrà indicata nella risposta. Il client può quindi selezionare l'endpoint appropriato per tutte le altre richieste dell'API REST come indicato di seguito.

Risposta di esempio

{
    "_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
}
  • Tutte le richieste PUT, POST e DELETE devono passare all'URI di scrittura indicato.
  • Tutte le richieste di sola lettura e GET, ad esempio le query, possono essere indirizzate a qualsiasi endpoint scelto dal client

Le richieste di scrittura per le aree di sola lettura avranno esito negativo con codice di errore HTTP 403 ("Non consentito").

Se l'area di scrittura viene modificata dopo la fase di individuazione iniziale del client, le scritture successive sull'area di scrittura precedente avranno esito negativo con codice errore HTTP 403 ("Non consentito"). Il client deve quindi OTTENERE nuovamente l'elenco delle aree per aggiornare l'area di scrittura.

L'esercitazione è terminata. Per informazioni su come gestire la coerenza dell'account con replica globale, vedere Livelli di coerenza in Azure Cosmos DB. Per informazioni sul funzionamento della replica di database globale in Azure Cosmos DB, vedere Distribuire i dati a livello globale con Azure Cosmos DB.

Passaggi successivi

In questa esercitazione sono state eseguite le operazioni seguenti:

  • Configurare la distribuzione globale tramite il portale di Azure
  • Configurare la distribuzione globale usando l'API per NoSQLs

È ora possibile passare all'esercitazione successiva per imparare a sviluppare in locale usando l'emulatore locale di Azure Cosmos DB.

Sviluppare in locale con l'emulatore

Si sta tentando di pianificare la capacità per una migrazione ad Azure Cosmos DB? È possibile usare le informazioni del cluster di database esistente per la pianificazione della capacità.