Esercitazione: Configurare la distribuzione globale in Azure Cosmos DB usando l'API SQLTutorial: Set up Azure Cosmos DB global distribution using the SQL API

In questo articolo viene illustrato come usare il portale di Azure per configurare la distribuzione globale di Azure Cosmos DB e quindi connettersi tramite l'API SQL.In this article, we show how to use the Azure portal to set up Azure Cosmos DB global distribution and then connect using the SQL API.

Questo articolo illustra le attività seguenti:This article covers the following tasks:

  • Configurare la distribuzione globale tramite il portale di AzureConfigure global distribution using the Azure portal
  • Configurare la distribuzione globale tramite le API SQLConfigure global distribution using the SQL APIs

Aggiungere aree di database globali tramite il portale di AzureAdd global database regions using the Azure portal

Azure Cosmos DB è disponibile in tutte le aree di Azure a livello mondiale.Azure Cosmos DB is available in all Azure regions worldwide. 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.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. Nella barra a sinistra del portale di Azure fare clic su Azure Cosmos DB.In the Azure portal, in the left bar, click Azure Cosmos DB.

  2. Nella pagina Azure Cosmos DB selezionare l'account di database da modificare.In the Azure Cosmos DB page, select the database account to modify.

  3. Nella pagina dell'account fare clic su Replica i dati a livello globale dal menu.In the account page, click Replicate data globally from the 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.In the Replicate data globally page, select the regions to add or remove by clicking regions in the map, and then click Save. 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.There is a cost to adding regions, see the pricing page or the Distribute data globally with Azure Cosmos DB article for more information.

    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.Once you add a second region, the Manual Failover option is enabled on the Replicate data globally page in the portal. È possibile usare questa opzione per testare il processo di failover o per modificare l'area di scrittura primaria.You can use this option to test the failover process or change the primary write region. 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.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.

Selezionare aree di database globaliSelecting global database regions

Esistono due scenari comuni per la configurazione di due o più aree:There are two common scenarios for configuring two or more regions:

  1. Offerta di accesso con bassa latenza ai dati indipendentemente dalla posizione del mondo in cui si trovano gli utenti finaliDelivering low-latency access to data to end users no matter where they are located around the globe
  2. Aggiunta di resilienza a livello di area per garantire continuità aziendale e ripristino di emergenza (BCDR)Adding regional resiliency for business continuity and disaster recovery (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.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.

Per finalità di continuità aziendale e ripristino di emergenza (BCDR), è consigliabile aggiungere le aree in base alle coppie di aree descritte nell'articolo Continuità aziendale e ripristino di emergenza aree di Azure abbinate.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.

Connessione a un'area preferita tramite l'API SQLConnecting to a preferred region using the SQL API

Per sfruttare la distribuzione globale, le applicazioni client possono specificare un elenco di aree, nell'ordine preferito, da usare per eseguire operazioni sui documenti.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. 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.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.

L'elenco delle preferenze viene specificato nella fase di inizializzazione di una connessione usando gli SDK SQL.This preference list is specified when initializing a connection using the SQL SDKs. Gli SDK accettano un parametro opzionale PreferredLocations, ovvero un elenco ordinato di aree di Azure.The SDKs accept an optional parameter PreferredLocations that is an ordered list of Azure regions.

L'SDK invia automaticamente tutte le scritture all'area di scrittura corrente.The SDK will automatically send all writes to the current write region. Tutte le letture verranno inviate alla prima area disponibile nell'elenco delle località preferite.All reads will be sent to the first available region in the preferred locations list. Se la richiesta ha esito negativo, il client passerà all'area dell'elenco successiva.If the request fails, the client will fail down the list to the next region.

L'SDK tenterà la lettura solo dalle aree specificate nelle località preferite.The SDK will only attempt to read from the regions specified in preferred locations. Si supponga ad esempio che l'account Azure Cosmos sia disponibile in quattro aree, ma il client specifichi solo due aree di lettura (non di scrittura) nell'elenco PreferredLocations.In questo caso, dall'area di lettura non specificata nell'elenco PreferredLocations non verrà distribuita alcuna lettura.So, for example, if the Azure Cosmos account is available in four regions, but the client only specifies two read(non-write) regions within the PreferredLocations, then no reads will be served out of the read region that is not specified in PreferredLocations. Se le aree di letture specificate nell'elenco PreferredLocations non sono disponibili, le letture verranno distribuite dall'area di scrittura.If the read regions specified in the PreferredLocations list are not available, reads will be served out of write region.

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.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. Se la proprietà PreferredLocations non è impostata, tutte le richieste verranno distribuite dall'area di scrittura corrente.If the PreferredLocations property is not set, all requests will be served from the current write region.

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.If you don't specify the preferred locations but used the setCurrentLocation method, the SDK automatically populates the preferred locations based on the current region that the client is running in. L'SDK ordina le aree in base alla prossimità di un'area a quella corrente.The SDK orders the regions based on the proximity of a region to the current region.

.NET SDK.NET SDK

L'SDK può essere usato senza alcuna modifica del codice.The SDK can be used without any code changes. In questo caso l'SDK reindirizza automaticamente sia le operazioni di lettura che di scrittura all'area di scrittura corrente.In this case, the SDK automatically directs both reads and writes to the current write region.

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.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. Questa proprietà è di tipo raccolta <string> e deve contenere un elenco di nomi di aree.This property is of type Collection <string> and should contain a list of region names. 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.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.

Gli endpoint di lettura e scrittura correnti sono disponibili rispettivamente in DocumentClient.WriteEndpoint e DocumentClient.ReadEndpoint.The current write and read endpoints are available in DocumentClient.WriteEndpoint and DocumentClient.ReadEndpoint respectively.

Nota

Gli URL per gli endpoint non devono essere considerati come costanti di lunga durata.The URLs for the endpoints should not be considered as long-lived constants. Il servizio può aggiornare gli URL in qualsiasi momento.The service may update these at any point. L'SDK gestisce la modifica in modo automatico.The SDK handles this change automatically.

Se si usa .NET v2 SDK, impostare l'area preferita tramite la proprietà PreferredLocations.If you are using the .NET V2 SDK, use the PreferredLocations property to set the preferred region.

// 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à.Alternatively, you can use the SetCurrentLocation property and let the SDK choose the preferred location based on proximity.

// 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/JavaScriptNode.js/JavaScript

Nota

Gli URL per gli endpoint non devono essere considerati come costanti di lunga durata.The URLs for the endpoints should not be considered as long-lived constants. Il servizio può aggiornare gli URL in qualsiasi momento.The service may update these at any point. L'SDK gestirà questa modifica in automatico.The SDK will handle this change automatically.

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

Il codice seguente illustra come impostare le località preferite usando Python SDK: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 V4 SDKJava V4 SDK

Il codice seguente illustra come impostare le località preferite usando Java SDK:The following code shows how to set preferred locations by using the Java SDK:

API asincrona Java SDK V4 (Maven com.azure::azure-cosmos)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();

RESTREST

Dopo aver reso disponibile un account di database in più aree, i client possono eseguire query sulla relativa disponibilità tramite una richiesta GET all'URI seguente https://{databaseaccount}.documents.azure.com/Once a database account has been made available in multiple regions, clients can query its availability by performing a GET request on this 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.The service will return a list of regions and their corresponding Azure Cosmos DB endpoint URIs for the replicas. L'area di scrittura corrente verrà indicata nella risposta.The current write region will be indicated in the response. Il client può quindi selezionare l'endpoint appropriato per tutte le altre richieste dell'API REST come indicato di seguito.The client can then select the appropriate endpoint for all further REST API requests as follows.

Risposta di esempioExample 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
}
  • Tutte le richieste PUT, POST e DELETE devono passare all'URI di scrittura indicato.All PUT, POST and DELETE requests must go to the indicated write URI
  • Tutte le richieste di sola lettura e GET, ad esempio le query, possono essere indirizzate a qualsiasi endpoint scelto dal clientAll GETs and other read-only requests (for example queries) may go to any endpoint of the client's choice

Le richieste di scrittura per le aree di sola lettura avranno esito negativo con codice di errore HTTP 403 ("Non consentito").Write requests to read-only regions will fail with HTTP error code 403 ("Forbidden").

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").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"). Il client deve quindi OTTENERE nuovamente l'elenco delle aree per aggiornare l'area di scrittura.The client should then GET the list of regions again to get the updated write region.

L'esercitazione è terminata.That's it, that completes this tutorial. Per informazioni su come gestire la coerenza dell'account con replica globale, vedere Livelli di coerenza 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. Per informazioni sul funzionamento della replica di database globale in Azure Cosmos DB, vedere Distribuire i dati a livello globale con 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.

Passaggi successiviNext steps

In questa esercitazione sono state eseguite le operazioni seguenti:In this tutorial, you've done the following:

  • Configurare la distribuzione globale tramite il portale di AzureConfigure global distribution using the Azure portal
  • Configurare la distribuzione globale tramite le API SQLConfigure global distribution using the SQL APIs

È ora possibile passare all'esercitazione successiva per imparare a sviluppare in locale usando l'emulatore locale di Azure Cosmos DB.You can now proceed to the next tutorial to learn how to develop locally using the Azure Cosmos DB local emulator.