共用方式為


在使用 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. 在您更新區域清單之後,請選取 [儲存] 以套用變更。

    使用 Azure 入口網站 啟用多重區域寫入的螢幕快照。

.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,
    });

或者,您可以使用 CosmosClientBuilderWithApplicationRegion 來達成相同的結果:

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)

下一步