Povratne informacije Uredi

Configure multi-region writes in your applications that use Azure Cosmos DB

  • Članak
  • 3 min. za čitanje

APPLIES TO: SQL API

Once an account has been created with multiple write regions enabled, you must make two changes in your application to the ConnectionPolicy for the Cosmos client to enable the multi-region writes in Azure Cosmos DB. Within the ConnectionPolicy, set UseMultipleWriteLocations to true and pass the name of the region where the application is deployed to ApplicationRegion. This will populate the PreferredLocations property based on the geo-proximity from location passed in. If a new region is later added to the account, the application does not have to be updated or redeployed, it will automatically detect the closer region and will auto-home on to it should a regional event occur.

Note

Cosmos accounts initially configured with single write region can be configured to multiple write regions with zero down time. To learn more see, Configure multiple-write regions

Azure portal

To enable multi-region writes from Azure portal, use the following steps:

  1. Sign-in to the Azure portal.

  2. Navigate to your Azure Cosmos account and from the menu, open the Replicate data globally pane.

  3. Under the Multi-region writes option, choose enable. It automatically adds the existing regions to read and write regions.

  4. You can add additional regions by selecting the icons on the map or by selecting the Add region button. All the regions you add will have both read and writes enabled.

  5. After you update the region list, select save to apply the changes.

    Screenshot to enable multi-region writes using Azure portal

.NET SDK v2

To enable multi-region writes in your application, set UseMultipleWriteLocations to true. Also, set SetCurrentLocation to the region in which the application is being deployed and where Azure Cosmos DB is replicated:

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

.NET SDK v3

To enable multi-region writes in your application, set ApplicationRegion to the region in which the application is being deployed and where Cosmos DB is replicated:

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

Optionally, you can use the CosmosClientBuilder and WithApplicationRegion to achieve the same result:

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

Java V4 SDK

To enable multi-region writes in your application, call .multipleWriteRegionsEnabled(true) and .preferredRegions(preferredRegions) in the client builder, where preferredRegions is a List containing one element - that is the region in which the application is being deployed and where Cosmos DB is replicated:

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


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

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

Async Java V2 SDK

The Java V2 SDK used the Maven com.microsoft.azure::azure-cosmosdb. To enable multi-region writes in your application, set policy.setUsingMultipleWriteLocations(true) and set policy.setPreferredLocations to the region in which the application is being deployed and where Cosmos DB is replicated:

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, and TypeScript SDKs

To enable multi-region writes in your application, set connectionPolicy.UseMultipleWriteLocations to true. Also, set connectionPolicy.PreferredLocations to the region in which the application is being deployed and where Cosmos DB is replicated:

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

To enable multi-region writes in your application, set connection_policy.UseMultipleWriteLocations to true. Also, set connection_policy.PreferredLocations to the region in which the application is being deployed and where Cosmos DB is replicated.

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)

Next steps

Read the following articles: