Configurare le scritture in più aree nelle applicazioni che usano Azure Cosmos DB

2025-04-21

SI APPLICA A: NoSQL

Negli scenari di scrittura in più aree, si ottiene un vantaggio in termini di prestazioni scrivendo solo nell'area vicina all'istanza dell'applicazione. Azure Cosmos DB gestisce automaticamente la replica in background.

Dopo aver abilitato l'account per più aree di scrittura, è necessario apportare due modifiche all'oggetto ConnectionPolicy nell'applicazione. In ConnectionPolicy impostare UseMultipleWriteLocations su true e passare il nome dell'area in cui è distribuita l'applicazione in ApplicationRegion. Questo popolerà la proprietà PreferredLocations in base alla prossimità geografica della località passata. Se successivamente viene aggiunta una nuova area all'account, non è necessario aggiornare o ridistribuire l'applicazione. Rileva automaticamente la regione più vicina e si aggancia automaticamente ad essa qualora si verifichi un evento regionale.

Nota

Gli account Azure Cosmos DB inizialmente configurati con una singola area di scrittura possono essere configurati per più aree di scrittura senza tempi di inattività. Per altre informazioni, consultare Configurare più aree di scrittura.

Azure portal

Per usare le scritture in più aree, abilitare l'account Azure Cosmos DB per più aree nel portale di Azure. Specificare le aree in cui l'applicazione può eseguire le scritture.

Per abilitare le scritture in più aree, seguire questa procedura:

Accedere al portale di Azure.
Passare all'account Azure Cosmos DB e dal menu aprire il riquadro Replica i dati a livello globale.
Nell'opzione Scritture in più aree scegliere Abilita. Le aree esistenti verranno automaticamente aggiunte alle aree di lettura e scrittura.
È possibile aggiungere altre aree selezionando le icone sulla mappa o selezionando il pulsante Aggiungi area. Le regioni che aggiungi sono abilitate sia per la lettura che per la scrittura.
Dopo aver aggiornato l'elenco delle aree, selezionare Salva per applicare le modifiche.

.NET SDK v2

Per abilitare le scritture in più aree nell'applicazione, impostare UseMultipleWriteLocations su true. Inoltre, impostare SetCurrentLocation sull'area in cui viene distribuita l'applicazione e in cui viene replicato Azure Cosmos DB:

ConnectionPolicy policy = new ConnectionPolicy
    {
        ConnectionMode = ConnectionMode.Direct,
        ConnectionProtocol = Protocol.Tcp,
        UseMultipleWriteLocations = true
    };
policy.SetCurrentLocation("West US 2");

.NET SDK v3

Per abilitare le scritture in più aree nelle applicazioni, impostare ApplicationRegion sull'area in cui viene distribuita l'applicazione e in cui viene replicato Azure Cosmos DB:

CosmosClient cosmosClient = new CosmosClient(
    "<connection-string-from-portal>", 
    new CosmosClientOptions()
    {
        ApplicationRegion = Regions.WestUS2,
    });

Facoltativamente, è possibile usare CosmosClientBuilder e WithApplicationRegion per ottenere lo stesso risultato:

CosmosClientBuilder cosmosClientBuilder = new CosmosClientBuilder("<connection-string-from-portal>")
            .WithApplicationRegion(Regions.WestUS2);
CosmosClient client = cosmosClientBuilder.Build();

Java v4 SDK

Per abilitare le scritture in più aree nell'applicazione, chiamare .multipleWriteRegionsEnabled(true) e .preferredRegions(preferredRegions) nel generatore client, dove preferredRegions è un oggetto List delle aree in cui i dati vengono replicati in ordine di preferenza, ovvero prima le aree con distanza più breve/latenza migliore:

Async
Sincronizza

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


ArrayList<String> preferredRegions = new ArrayList<String>();
preferredRegions.add(region);

CosmosAsyncClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .key(MASTER_KEY)
                .multipleWriteRegionsEnabled(true)
                .preferredRegions(preferredRegions)
                .buildAsyncClient();

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


ArrayList<String> preferredRegions = new ArrayList<String>();
preferredRegions.add(region);

CosmosClient client =
        new CosmosClientBuilder()
                .endpoint(HOST)
                .key(MASTER_KEY)
                .multipleWriteRegionsEnabled(true)
                .preferredRegions(preferredRegions)
                .buildClient();

Java V2 SDK asincrono

Java V2 SDK usa Maven com.microsoft.azure::azure-cosmosdb. Per abilitare le scritture in più aree nell'applicazione, impostare policy.setUsingMultipleWriteLocations(true) e impostare policy.setPreferredLocations sull'elenco List delle aree in cui i dati vengono replicati in ordine di preferenza, idealmente prima le aree con la distanza più breve o la latenza migliore.

ConnectionPolicy policy = new ConnectionPolicy();
policy.setUsingMultipleWriteLocations(true);
policy.setPreferredLocations(Collections.singletonList(region));

AsyncDocumentClient client =
    new AsyncDocumentClient.Builder()
        .withMasterKeyOrResourceToken(this.accountKey)
        .withServiceEndpoint(this.accountEndpoint)
        .withConsistencyLevel(ConsistencyLevel.Eventual)
        .withConnectionPolicy(policy).build();

Node.js, JavaScript e TypeScript SDK

Per attivare la funzionalità di scrittura in più aree nella tua applicazione, imposta connectionPolicy.UseMultipleWriteLocations su true. Impostare anche connectionPolicy.PreferredLocations sulle aree in cui i dati vengono replicati in ordine di preferenza, ovvero prima le aree con distanza più breve/latenza migliore:

const connectionPolicy: ConnectionPolicy = new ConnectionPolicy();
connectionPolicy.UseMultipleWriteLocations = true;
connectionPolicy.PreferredLocations = [region];

const client = new CosmosClient({
  endpoint: config.endpoint,
  auth: { masterKey: config.key },
  connectionPolicy,
  consistencyLevel: ConsistencyLevel.Eventual
});

Python SDK

Per abilitare le scritture in più aree nell'applicazione, impostare connection_policy.UseMultipleWriteLocations su true. Impostare anche connection_policy.PreferredLocations sulle aree in cui i dati vengono replicati in ordine di preferenza, ovvero prima le aree con distanza più breve/latenza migliore.

connection_policy = documents.ConnectionPolicy()
connection_policy.UseMultipleWriteLocations = True
connection_policy.PreferredLocations = [region]

client = cosmos_client.CosmosClient(self.account_endpoint, {
                                    'masterKey': self.account_key}, connection_policy, documents.ConsistencyLevel.Session)

Condividi tramite