教學課程：使用 API for NoSQL 來設定 Azure Cosmos DB 全域散發

發行項
06/01/2023

適用於：NoSQL

在此文章中，我們會說明如何使用 Azure 入口網站來設定 Azure Cosmos DB 全域散發，然後使用 API for NoSQL 來進行連線。

本文涵蓋下列工作：

使用 Azure 入口網站來設定全域散發
使用 API for NoSQL 來設定全域散發

使用 Azure 入口網站新增全域資料庫區域

全球所有 Azure 區域都有提供 Azure Cosmos DB。選取資料庫帳戶的預設一致性層級之後，您可以關聯一或多個區域 (取決於您對於預設一致性層級和全球發佈需求的選擇)。

在 Azure 入口網站的左列中，按一下 [Azure Cosmos DB]。
在 [Azure Cosmos DB] 頁面中，選取要修改的資料庫帳戶。
在帳戶頁面中，從功能表中按一下 [全域複寫資料]。
在 [全域複寫資料] 頁面中，按一下地圖中的區域以選取要新增或移除的區域，然後按一下 [儲存]。新增區域需要費用，如需詳細資訊，請參閱價格頁面或使用 Azure Cosmos DB 全球散發資料一文。

在您新增第二個區域後，就會在入口網站中的 [全域複寫資料] 頁面上啟用 [手動容錯移轉] 選項。您可以使用此選項來測試容錯移轉程序，或變更主要寫入區域。在您新增第三個區域後，將會在相同的頁面上啟用 [容錯移轉優先順序] 選項，讓您能夠變更讀取的容錯移轉順序。

選取全球資料庫區域

設定兩個或更多區域有兩個常見案例︰

為使用者提供低延遲的資料存取 (無論使用者位於世界何處)
新增區域性復原能力來提供商務持續性和災害復原 (BCDR)

若要為使用者提供低延遲，建議您在應用程式使用者所在位置的對應區域中部署應用程式和 Azure Cosmos DB。

對於 BCDR，建議根據 Azure 中的跨區域複寫：商務持續性和災害復原文章中所述的區域配對來新增區域。

使用 API for NoSQL 來連線至慣用的區域

為了充分運用全球發佈，用戶端應用程式可以指定已排序的區域喜好設定清單，以用來執行文件作業。 SQL SDK 將會根據 Azure Cosmos DB 帳戶組態、目前的區域可用性及所指定的喜好設定清單，選擇最適合的端點來執行寫入和讀取作業。

這份喜好設定清單是在使用 SQL SDK 將連線初始化時即已指定。 SDK 會接受選擇性參數 PreferredLocations，也就是已排序的 Azure 區域清單。

SDK 會自動將所有寫入傳送至目前的寫入區域。所有讀取都將傳送至慣用位置清單中的第一個可用區域。如果要求失敗，用戶端將無法往下到清單中的下一個區域。

SDK 只會嘗試從慣用位置中指定的區域讀取。因此，比方說，如果 Azure Cosmos DB 帳戶可供四個區域使用，但用戶端只針對 PreferredLocations 指定其中兩個讀取 (非寫入) 區域，則將不會在 PreferredLocations 中未指定的讀取區域以外地方提供讀取服務。如果 PreferredLocations 清單中指定的讀取區域無法使用，就會在寫入區域以外地方提供讀取服務。

應用程式可以藉由檢查兩個屬性 (WriteEndpoint 和 ReadEndpoint，適用於 SDK 1.8 版和以上版本) 來確認 SDK 目前所選擇的寫入端點和讀取端點。如果未設定 PreferredLocations 屬性，將會從目前的寫入區域為所有要求提供服務。

如果您未指定慣用位置但使用 setCurrentLocation 方法，SDK 會根據目前正在執行用戶端的區域，自動填入慣用的位置。 SDK 會根據區域與目前區域的鄰近性來排序區域。

.NET SDK

您不需變更任何程式碼即可使用 SDK。在此情況下，SDK 會自動將讀取和寫入導向至目前寫入區域。

在 .NET SDK 的 1.8 版和更新版本中，適用於 DocumentClient 建構函式的 ConnectionPolicy 參數會有一個名為 Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations 的屬性。這個屬性的類型是 Collection <string> ，而且應包含區域名稱的清單。字串值會按照 Azure 區域頁面的 [區域名稱] 資料行格式化，且在第一個字元之前和最後一個字元之後沒有空格。

目前的寫入和讀取端點分別適用於 DocumentClient.WriteEndpoint 和 DocumentClient.ReadEndpoint。

注意

不應將端點的 URI 視為長時間執行的常數。服務可能會隨時更新這些項目。 SDK 會自動處理此變更。

.NET SDK V2
.NET SDK V3

如果您使用 .NET V2 SDK，請使用 PreferredLocations 屬性來設定慣用的區域。

// Getting endpoints from application settings or other configuration location
Uri accountEndPoint = new Uri(Properties.Settings.Default.GlobalDatabaseUri);
string accountKey = Properties.Settings.Default.GlobalDatabaseKey;
  
ConnectionPolicy connectionPolicy = new ConnectionPolicy();

//Setting read region selection preference
connectionPolicy.PreferredLocations.Add(LocationNames.WestUS); // first preference
connectionPolicy.PreferredLocations.Add(LocationNames.EastUS); // second preference
connectionPolicy.PreferredLocations.Add(LocationNames.NorthEurope); // third preference

// initialize connection
DocumentClient docClient = new DocumentClient(
    accountEndPoint,
    accountKey,
    connectionPolicy);

// connect to DocDB
await docClient.OpenAsync().ConfigureAwait(false);

或者，您可以使用 SetCurrentLocation 屬性，並讓 SDK 根據鄰近性選擇慣用的位置。

// Getting endpoints from application settings or other configuration location
Uri accountEndPoint = new Uri(Properties.Settings.Default.GlobalDatabaseUri);
string accountKey = Properties.Settings.Default.GlobalDatabaseKey;
  
ConnectionPolicy connectionPolicy = new ConnectionPolicy();

connectionPolicy.SetCurrentLocation("West US 2"); /

// initialize connection
DocumentClient docClient = new DocumentClient(
    accountEndPoint,
    accountKey,
    connectionPolicy);

// connect to DocDB
await docClient.OpenAsync().ConfigureAwait(false);

如果您使用 .NET V3 SDK，請使用 ApplicationPreferredRegions 屬性來設定慣用的區域。


CosmosClientOptions options = new CosmosClientOptions();
options.ApplicationName = "MyApp";
options.ApplicationPreferredRegions = new List<string> {Regions.WestUS, Regions.WestUS2};

CosmosClient client = new CosmosClient(connectionString, options);

或者，您可以使用 ApplicationRegion 屬性，並讓 SDK 根據鄰近性選擇慣用的位置。

CosmosClientOptions options = new CosmosClientOptions();
options.ApplicationName = "MyApp";
// If the application is running in West US
options.ApplicationRegion = Regions.WestUS;

CosmosClient client = new CosmosClient(connectionString, options);

Node.js/JavaScript

注意

不應將端點的 URI 視為長時間執行的常數。服務可能會隨時更新這些項目。 SDK 將會自動處理此變更。

以下是 Node.js/JavaScript 的程式碼範例。

// Setting read region selection preference, in the following order -
// 1 - West US
// 2 - East US
// 3 - North Europe
const preferredLocations = ['West US', 'East US', 'North Europe'];

// initialize the connection
const client = new CosmosClient{ endpoint, key, connectionPolicy: { preferredLocations } });

Python SDK

下列程式碼說明如何使用 Python SDK 來設定慣用位置：

connectionPolicy = documents.ConnectionPolicy()
connectionPolicy.PreferredLocations = ['West US', 'East US', 'North Europe']
client = cosmos_client.CosmosClient(ENDPOINT, {'masterKey': MASTER_KEY}, connectionPolicy)

Java V4 SDK

下列程式碼說明如何使用 Java SDK 來設定慣用位置：

非同步
Sync

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


ArrayList<String> preferredRegions = new ArrayList<String>();
preferredRegions.add("East US");
preferredRegions.add( "West US");
preferredRegions.add("Canada Central");

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

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


ArrayList<String> preferredRegions = new ArrayList<String>();
preferredRegions.add("East US");
preferredRegions.add( "West US");
preferredRegions.add("Canada Central");

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

Spark 3 連接器

您可以使用spark.cosmos.preferredRegionsList設定來定義慣用的區域清單，例如：

val sparkConnectorConfig = Map(
  "spark.cosmos.accountEndpoint" -> cosmosEndpoint,
  "spark.cosmos.accountKey" -> cosmosMasterKey,
  "spark.cosmos.preferredRegionsList" -> "[West US, East US, North Europe]"
  // other settings
)

REST

一旦資料庫帳戶可供多個區域使用之後，用戶端就可藉由在此 URI https://{databaseaccount}.documents.azure.com/ 上執行 GET 要求來查詢其可用性

服務將會針對複本傳回區域清單及其對應的 Azure Cosmos DB 端點 URI。回應中將會指出目前的寫入區域。用戶端接著可針對所有未來的 REST API 要求選取適當的端點，如下所示。

範例回應

{
    "_dbs": "//dbs/",
    "media": "//media/",
    "writableLocations": [
        {
            "Name": "West US",
            "DatabaseAccountEndpoint": "https://globaldbexample-westus.documents.azure.com:443/"
        }
    ],
    "readableLocations": [
        {
            "Name": "East US",
            "DatabaseAccountEndpoint": "https://globaldbexample-eastus.documents.azure.com:443/"
        }
    ],
    "MaxMediaStorageUsageInMB": 2048,
    "MediaStorageUsageInMB": 0,
    "ConsistencyPolicy": {
        "defaultConsistencyLevel": "Session",
        "maxStalenessPrefix": 100,
        "maxIntervalInSeconds": 5
    },
    "addresses": "//addresses/",
    "id": "globaldbexample",
    "_rid": "globaldbexample.documents.azure.com",
    "_self": "",
    "_ts": 0,
    "_etag": null
}

所有的 PUT、POST 和 DELETE 要求都必須移至指定的寫入 URI
所有的 GET 和其他唯讀要求 (例如查詢) 可能會移至用戶端選擇的任何端點

將要求寫入至唯讀區域將會失敗，並產生 HTTP 錯誤碼 403 (「禁止」)。

如果寫入區域在用戶端初始探索階段之後變更，則寫入至上一個寫入區域的後續作業將會失敗，並產生 HTTP 錯誤碼 403 (「禁止」)。用戶端接著應再次 GET 區域清單，以取得更新的寫入區域。

就這麼簡單，這樣便已完成本教學課程。您可以透過閱讀 Azure Cosmos DB 中的一致性層級，來了解如何管理全域複寫帳戶的一致性。如需有關 Azure Cosmos DB 中全域資料庫複寫運作方式的詳細資訊，請參閱使用 Azure Cosmos DB 來全域散發資料。

下一步

在本教學課程中，您已完成下列操作：

使用 Azure 入口網站來設定全域散發
使用 API for NoSQL 來設定全域散發

您現在可以繼續進行到下一個教學課程，以了解如何使用 Azure Cosmos DB 本機模擬器在本機進行開發。

使用模擬器在本機進行開發

正在嘗試為遷移至 Azure Cosmos DB 進行容量規劃嗎？您可以使用現有資料庫叢集的相關資訊進行容量規劃。

如果您知道現有資料庫叢集中的虛擬核心和伺服器數目，請參閱使用虛擬核心或 vCPU 來估計要求單位
如果您知道目前資料庫工作負載的一般要求率，請參閱使用 Azure Cosmos DB 容量規劃工具來估計要求單位