Procedura di configurazione della distribuzione globale in Azure Cosmos DB mediante l'API GraphHow to setup Azure Cosmos DB global distribution using the Graph API

Questo articolo illustra come usare il portale di Azure per configurare la distribuzione globale in Azure Cosmos DB e quindi connettersi tramite l'API Graph (anteprima).In this article, we show how to use the Azure portal to setup Azure Cosmos DB global distribution and then connect using the Graph API (preview).

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 Graph (anteprima)Configure global distribution using the Graph APIs (preview)

In questo video di Azure Friday, con Scott Hanselman e Karthik Raman, Principal Engineering Manager, sono disponibili altre informazioni sulla distribuzione globale in Azure Cosmos DB.You can learn about Azure Cosmos DB global distribution in this Azure Friday video with Scott Hanselman and Principal Engineering Manager Karthik Raman.

Per informazioni sul funzionamento della replica di database globale in Azure Cosmos DB, vedere Distribuire i dati a livello globale con Azure Cosmos DB.For more information about how global database replication works in Azure Cosmos DB, see Distribute data globally with Cosmos DB.

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 del mondo.Azure Cosmos DB is available in all Azure regions world-wide. 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. Nel pannello Azure Cosmos DB selezionare l'account di database da modificare.In the Azure Cosmos DB blade, select the database account to modify.
  3. Nel pannello dell'account fare clic su Replica i dati a livello globale dal menu.In the account blade, click Replicate data globally from the menu.
  4. Nel pannello 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 blade, 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, nel pannello Replica i dati a livello globale del portale viene abilitata l'opzione Failover manuale.Once you add a second region, the Manual Failover option is enabled on the Replicate data globally blade 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 nello stesso pannello 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 blade 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 aggiungere 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 to deploy both the application and add Azure Cosmos DB in the regions thats correspond to where the application's users are located.

Per finalità BCDR, è consigliabile aggiungere le aree in base alle coppie di aree descritte nell'articolo Continuità aziendale e ripristino di emergenza nelle aree geografiche abbinate di Azure.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 Graph con .NET SDKConnecting to a preferred region using the Graph API using the .NET SDK

L'API Graph viene esposta come libreria di estensione oltre al DocumentDB SDK.The Graph API is exposed as an extension library on top of the DocumentDB SDK.

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. Questa operazione può essere eseguita impostando il criterio di connessione.This can be done by setting the connection policy. A seconda della configurazione dell'account Azure Cosmos DB, della disponibilità corrente delle aree e dell'elenco delle preferenze specificato, l'SDK 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 SDK to perform write and read operations.

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

  • Scritture: l'SDK invia automaticamente tutte le scritture all'area di scrittura corrente.Writes: The SDK will automatically send all writes to the current write region.
  • Letture: tutte le letture verranno inviate alla prima area disponibile nell'elenco PreferredLocations.Reads: All reads will be sent to the first available region in the PreferredLocations list. Se la richiesta ha esito negativo, il client trasferisce l'elenco all'area successiva e così via.If the request fails, the client will fail down the list to the next region, and so on. Gli SDK tenteranno di leggere solo dalle aree specificate nell'elenco PreferredLocations.The SDKs will only attempt to read from the regions specified in PreferredLocations. Quindi se l'account Cosmos DB è disponibile ad esempio in tre aree, ma il client specifica solo due delle aree di non scrittura per PreferredLocations, le letture non verranno distribuite fuori dall'area di scrittura, anche in caso di failover.So, for example, if the Cosmos DB account is available in three regions, but the client only specifies two of the non-write regions for PreferredLocations, then no reads will be served out of the write region, even in the case of failover.

L'applicazione può verificare l'endpoint di scrittura e lettura corrente scelto dall'SDK controllando due proprietà, WriteEndpoint e ReadEndpoint, disponibili nella versione dell'SDK 1.8 e nelle 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.

Uso dell'SDKUsing the SDK

Ad esempio, in .NET SDK il parametro ConnectionPolicy per il costruttore DocumentClient dispone di una proprietà denominata PreferredLocations.For example, in the .NET SDK, the ConnectionPolicy parameter for the DocumentClient constructor has a property called PreferredLocations. È possibile impostare questa proprietà su un elenco di nomi di aree.This property can be set to a list of region names. I nomi visualizzati per le aree di Azure possono essere specificati come parte di PreferredLocations.The display names for Azure Regions can be specified as part of PreferredLocations.

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.

// 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 Azure Cosmos DB
await docClient.OpenAsync().ConfigureAwait(false);

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 di DocumentDBConfigure global distribution using the DocumentDB 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.