在使用 Azure Cosmos DB 的应用程序配置多区域写入

适用于: SQL API

创建启用了多个写入区域的帐户后,必须在应用程序中对 Cosmos 客户端的 ConnectionPolicy 进行两处更改,以启用 Azure Cosmos DB 中的多区域写入功能。 在 ConnectionPolicy 中,将 UseMultipleWriteLocations 设置为 true,并将部署应用程序的区域的名称传递给 ApplicationRegion。 这将根据传入位置的地理接近性填充 PreferredLocations 属性。 如果稍后将新区域添加到帐户中,则无需更新或重新部署应用程序,它将自动检测距离较近的区域,并在发生区域事件时自动定位到该区域。

备注

最初配置有单个写入区域的 Cosmos 帐户可以配置为多个写入区域且停机时间为零。 若要了解详细信息,请参阅配置多个写入区域

Azure 门户

若要从 Azure 门户启用多区域写入,请执行以下步骤:

  1. 登录到 Azure 门户

  2. 导航到 Azure Cosmos 帐户,然后从菜单中打开“多区域复制数据”窗格。

  3. 在“多区域写入”选项下,选择“启用”。 它会自动将现有区域添加到读取和写入区域。

  4. 可以通过选择地图上的图标或选择“添加区域”按钮来添加其他区域。 你添加的所有区域都会启用读取和写入功能。

  5. 更新区域列表后,请选择“保存”以应用所做的更改。

    使用 Azure 门户启用多区域写入的屏幕截图

.NET SDK v2

若要在应用程序中启用多区域写入,请将 UseMultipleWriteLocations 设置为 true。 此外,将 SetCurrentLocation 设置为在其中部署应用程序并复制 Azure Cosmos DB 的区域:

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

.NET SDK v3

若要在应用程序中启用多区域写入,请将 ApplicationRegion 设置为在其中部署应用程序并复制 Cosmos DB 的区域:

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

(可选)可以使用 CosmosClientBuilderWithApplicationRegion 来获得相同的结果:

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

Java V4 SDK

若要在应用程序中启用多区域写入,请在客户端生成器中调用 .multipleWriteRegionsEnabled(true).preferredRegions(preferredRegions),其中 preferredRegions 是包含一个元素的 List,即正在部署应用程序和复制 Cosmos DB 的区域:

Java SDK V4 (Maven com.azure::azure-cosmos) 异步 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

Java V2 SDK 使用 Maven com.microsoft.azure::azure-cosmosdb。 若要在应用程序中启用多区域写入,请设置 policy.setUsingMultipleWriteLocations(true),并将 policy.setPreferredLocations 设置为在其中部署应用程序并复制 Cosmos DB 的区域:

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 和 TypeScript SDK

若要在应用程序中启用多区域写入,请将 connectionPolicy.UseMultipleWriteLocations 设置为 true。 此外,将 connectionPolicy.PreferredLocations 设置为在其中部署应用程序并复制 Cosmos DB 的区域:

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

若要在应用程序中启用多区域写入,请将 connection_policy.UseMultipleWriteLocations 设置为 true。 此外,将 connection_policy.PreferredLocations 设置为在其中部署应用程序并复制 Cosmos DB 的区域。

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)

后续步骤

请阅读以下文章: