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

  • 發行項

適用於：NoSQL

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

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

注意

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

Azure 入口網站

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

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

  1. 登入 Azure 入口網站。

  2. 巡覽至 Azure Cosmos DB 帳戶，然後從功能表中開啟 [全域複寫資料] 窗格。

  3. 在 [多重區域寫入] 選項下，選擇 [啟用]。 這樣會自動將現有的區域新增至讀取和寫入區域。

  4. 您可以選取地圖上的圖示，或選取 [新增區域] 按鈕，來新增其他區域。 您新增的所有區域都會同時啟用讀取和寫入。

  5. 在您更新區域清單之後，請選取 [儲存] 以套用變更。

    Screenshot to enable multi-region writes using Azure portal.

.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 - 理想上會先列出具有最短距離/最佳延遲的區域：

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 設定為將依喜好設定排序的資料複寫至其中的區域 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)

下一步