使用 SQL API 设置 Azure Cosmos DB 多区域分发

本文介绍如何使用 Azure 门户设置 Azure Cosmos DB 多区域分发,然后使用 SQL API 进行连接。

本文涵盖以下任务:

  • 使用 Azure 门户配置多区域分发
  • 使用 SQL API 配置多区域分发

有关 Azure Cosmos DB 中多区域数据库复制工作原理的详细信息,请参阅使用 Cosmos DB 全局分发数据

使用 Azure 门户添加全局数据库区域

在中国的所有 Azure 区域中都可使用 Azure Cosmos DB。 为数据库帐户选择默认的一致性级别后,可以关联一个或多个区域(具体取决于所选的默认一致性级别和多区域分发需求)。

  1. Azure 门户的左侧栏中,单击“Azure Cosmos DB”。
  2. 在“Azure Cosmos DB”页中,选择要修改的数据库帐户。
  3. 在“帐户”页上的菜单中单击“全局复制数据”。
  4. 在“全局复制数据”页中,通过单击地图中的区域选择要添加或删除的区域,并单击“保存”。 添加区域会产生费用,有关详细信息,请参阅定价页使用 Azure Cosmos DB 全局分发数据

    单击图中的区域可以添加或删除区域

添加第二个区域后,门户中的“全局复制数据”页上会启用“手动故障转移”选项。 可以使用此选项测试故障转移过程或更改主写入区域。 添加第三个区域后,会在同一页上启用“故障转移优先级”选项,以便更改读取的故障转移顺序。

选择全局数据库区域

配置两个或更多区域有两个常见方案:

  1. 向最终用户提供对数据的低延迟访问,而无论用户位于全球范围内的何位置
  2. 添加区域复原以实现业务连续性和灾难恢复 (BCDR)

若要向最终用户提供低延迟,建议在与应用程序用户所在位置对应的区域中同时部署应用程序和 Azure Cosmos DB。

使用 SQL API 连接到首选区域

为了利用多区域分发,客户端应用程序可以指定要用于执行文档操作的区域优先顺序列表。 可通过设置连接策略来实现此目的。 SQL SDK 根据 Azure Cosmos DB 帐户配置、当前区域可用性和指定的优先顺序列表,选择最佳的终结点来执行写入和读取操作。

此优先顺序列表是在使用 SQL SDK 初始化连接时指定的。 SDK 接受可选参数“PreferredLocations”,这是 Azure 区域的顺序列表。

SDK 会自动将所有写入请求发送到当前写入区域。

所有读取请求将发送到 PreferredLocations 列表中的第一个可用区域。 如果请求失败,客户端会将请求转发到列表中的下一个区域,依此类推。

SDK 只会尝试读取 PreferredLocations 中指定的区域。 因此,例如,如果数据库帐户在四个区域中可用,但客户端只为 PreferredLocations 指定了两个读取(非写入)区域,那么将不会从 PreferredLocations 中未指定的读取区域为读取提供服务。 如果 PreferredLocations 中指定的读取区域不可用,将从写入区域为读取提供服务。

应用程序可以通过检查 SDK 1.8 和更高版本中提供的两个属性 - WriteEndpoint 和 ReadEndpoint - 来验证 SDK 选择的当前写入终结点和读取终结点。

如果未设置 PreferredLocations 属性,则会从当前写入区域为所有请求提供服务。

.NET SDK

无需进行任何代码更改即可使用该 SDK。 在此情况下,SDK 会自动将读取和写入请求定向到当前写入区域。

在 .NET SDK 1.8 和更高版本中,DocumentClient 构造函数的 ConnectionPolicy 参数有一个名为 Microsoft.Azure.Documents.ConnectionPolicy.PreferredLocations 的属性。 此属性的类型为 Collection <string> ,应包含区域名称的列表。 字符串值已根据 Azure 区域 页上的“区域名称”列设置格式,其第一个字符的前面和最后一个字符的后面均没有空格。

当前写入终结点和读取终结点分别在 DocumentClient.WriteEndpoint 和 DocumentClient.ReadEndpoint 中提供。

Note

不应将终结点 URL 视为长期不变的常量。 服务随时会更新这些 URL。 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();

//Setting read region selection preference
connectionPolicy.PreferredLocations.Add(LocationNames.ChinaNorth); // first preference
connectionPolicy.PreferredLocations.Add(LocationNames.ChinaEast); // second preference
connectionPolicy.PreferredLocations.Add(LocationNames.ChinaEast2); // third preference

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

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

NodeJS、JavaScript 和 Python SDK

无需进行任何代码更改即可使用该 SDK。 在此情况下,SDK 会自动将读取和写入请求定向到当前写入区域。

在每个 SDK 的 1.8 和更高版本中,DocumentClient 构造函数的 ConnectionPolicy 参数有一个名为 DocumentClient.ConnectionPolicy.PreferredLocations 的新属性。 此参数是采用区域名称列表的字符串数组。 名称已根据 Azure 区域 页中的“区域名称”列设置格式。 也可以在便捷对象 AzureDocuments.Regions 中使用预定义的常量

当前写入终结点和读取终结点分别在 DocumentClient.getWriteEndpoint 和 DocumentClient.getReadEndpoint 中提供。

Note

不应将终结点 URL 视为长期不变的常量。 服务随时会更新这些 URL。 SDK 会自动处理这种更改。

下面是 NodeJS/Javascript 的代码示例。 Python 和 Java 将遵循相同的模式。

// Creating a ConnectionPolicy object
var connectionPolicy = new DocumentBase.ConnectionPolicy();

// Setting read region selection preference, in the following order -
// 1 - China North
// 2 - China East
// 3 - China East 2
connectionPolicy.PreferredLocations = ['China North', 'China East','China East 2'];

// initialize the connection
var client = new DocumentDBClient(host, { masterKey: masterKey }, connectionPolicy);

REST

数据库帐户在多个区域中可用后,客户端可以通过对以下 URI 执行 GET 请求来查询该帐户的可用性。

https://{databaseaccount}.documents.azure.cn/

服务返回副本的区域及其对应 Azure Cosmos DB 终结点 URI 的列表。 当前写入区域会在响应中指示。 然后,客户端可为所有其他 REST API 请求选择适当的终结点,如下所示。

示例响应

{
    "_dbs": "//dbs/",
    "media": "//media/",
    "writableLocations": [
        {
            "Name": "China North",
            "DatabaseAccountEndpoint": "https://globaldbexample-chinanorth.documents.azure.cn:443/"
        }
    ],
    "readableLocations": [
        {
            "Name": "China East",
            "DatabaseAccountEndpoint": "https://globaldbexample-chinaeast.documents.azure.cn:443/"
        }
    ],
    "MaxMediaStorageUsageInMB": 2048,
    "MediaStorageUsageInMB": 0,
    "ConsistencyPolicy": {
        "defaultConsistencyLevel": "Session",
        "maxStalenessPrefix": 100,
        "maxIntervalInSeconds": 5
    },
    "addresses": "//addresses/",
    "id": "globaldbexample",
    "_rid": "globaldbexample.documents.azure.cn",
    "_self": "",
    "_ts": 0,
    "_etag": null
}
  • 所有 PUT、POST 和 DELETE 请求必须转到指示的写入 URI
  • 所有 GET 和其他只读请求(例如查询)都可以转到客户端选择的任何终结点

向只读区域发出的写入请求会失败并出现 HTTP 错误代码 403(“禁止”)。

如果在客户端初始发现阶段过后写入区域发生更改,则向先前写入区域进行的后续写入会失败并出现 HTTP 错误代码 403(“禁止”)。 然后,客户端应再次对区域列表执行 GET 以获取更新的写入区域。

本教程到此结束。 阅读 Azure Cosmos DB 中的一致性级别,了解如何管理全局复制帐户的一致性。 有关 Azure Cosmos DB 中多区域数据库复制工作原理的详细信息,请参阅使用 Cosmos DB 多区域分配数据

后续步骤

在本教程中已完成以下操作:

  • 使用 Azure 门户配置多区域分发
  • 使用 SQL API 配置多区域分发

现可继续学习下一个教程,了解如何使用 Azure Cosmos DB 本地模拟器在本地开发。