在使用 Azure Cosmos DB 的應用程式中設定多重區域寫入

發行項
08/15/2024

適用於：NoSQL

在多區域寫入情節中，您可以只寫入靠近應用程式執行個體的區域，以取得效能優勢。 Azure Cosmos DB 會在幕後為您處理複寫。

針對多個寫入區域啟用您的帳戶之後，您必須在應用程式中對 ConnectionPolicy 進行兩項變更。在 ConnectionPolicy 內，將 UseMultipleWriteLocations 設定為 true，並將應用程式部署所在的區域名稱傳遞至 ApplicationRegion。此動作會根據所傳入位置的地理鄰近性來填入 PreferredLocations 屬性。如果稍後將新的區域新增至帳戶，則不需要更新或重新部署應用程式。其會自動偵測較近的區域，並在發生區域事件時自動返回該區域。

注意

最初設定為單一寫入區域的 Azure Cosmos DB 帳戶可以設定為多重寫入區域，不需要停機。若要深入了解，請參閱設定多寫入區域。

Azure 入口網站

若要使用多區域寫入，請使用 Azure 入口網站針對多個區域啟用您的 Azure Cosmos DB 帳戶。指定應用程式可以寫入的區域。

若要啟用多區域寫入，請使用下列步驟：

登入 Azure 入口網站。
巡覽至 Azure Cosmos DB 帳戶，然後從功能表中開啟 [全域複寫資料] 窗格。
在 [多重區域寫入] 選項下，選擇 [啟用]。這樣會自動將現有的區域新增至讀取和寫入區域。
您可以選取地圖上的圖示，或選取 [新增區域] 按鈕，來新增其他區域。您新增的所有區域都會同時啟用讀取和寫入。
在您更新區域清單之後，請選取 [儲存] 以套用變更。

.NET SDK v2

若要在應用程式中啟用多重區域寫入，請將 UseMultipleWriteLocations 設定為 true。此外，將 SetCurrentLocation 設定為要在其中部署應用程式的區域，以及複寫 Azure Cosmos DB 的所在區域：

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

.NET SDK v3

若要在應用程式中啟用多重區域寫入，請將 ApplicationRegion 設定為要部署應用程式和複寫 Azure Cosmos DB 的區域：

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

或者，您可以使用 CosmosClientBuilder 和 WithApplicationRegion 來達成相同的結果：

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

Java V4 SDK

若要在應用程式中啟用多區域寫入，請在用戶端建立器中呼叫 .multipleWriteRegionsEnabled(true) 和 .preferredRegions(preferredRegions)，其中 preferredRegions 是將依喜好設定排序的資料複寫至其中的區域 List - 理想上會先列出具有最短距離/最佳延遲的區域：

非同步
Sync

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();

Java SDK V4 (Maven com.azure::azure-cosmos) 同步 API：


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

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

Async JAVA V2 SDK

JAVA V2 SDK 使用 Maven com.microsoft.azure::azure-cosmosdb。若要在應用程式中啟用多區域寫入，設定 policy.setUsingMultipleWriteLocations(true)，並將 policy.setPreferredLocations 設定為將依喜好設定排序的資料複寫至其中的區域 List - 理想上會先列出具有最短距離/最佳延遲的區域：

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 設定為將依喜好設定排序的資料複寫至其中的區域 - 理想上會先列出具有最短距離/最佳延遲的區域：

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 設定為將依喜好設定排序的資料複寫至其中的區域 - 理想上會先列出具有最短距離/最佳延遲的區域。

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)

共用方式為