Azure Cosmos DB Graph 帐户的区域终结点Regional endpoints for Azure Cosmos DB Graph account

适用于: Gremlin API

Azure Cosmos DB Graph 数据库是多区域分布的,因此应用程序可以使用多个读取终结点。Azure Cosmos DB Graph database is multiple-regionally distributed so applications can use multiple read endpoints. 需要在多个位置具有写入访问权限的应用程序应启用多区域写入功能。Applications that need write access in multiple locations should enable multi-region writes capability.

选择多个区域的原因:Reasons to choose more than one region:

  1. 水平读取可伸缩性 - 随着应用程序负载的增加,将读取流量路由到不同的 Azure 区域可能是明智的做法。Horizontal read scalability - as application load increases it may be prudent to route read traffic to different Azure regions.
  2. 延迟较低 - 可以将读取和写入流量路由到最近的 Azure 区域,从而减少每个遍历的网络延迟开销。Lower latency - you can reduce network latency overhead of each traversal by routing read and write traffic to the nearest Azure region.

数据驻留 要求通过在 Cosmos DB 帐户上设置 Azure 资源管理器策略来实现。Data residency requirement is achieved by setting Azure Resource Manager policy on Cosmos DB account. 客户可限制 Cosmos DB 将数据复制到其中的区域。Customer can limit regions into which Cosmos DB replicates data.

流量路由Traffic routing

Cosmos DB Graph 数据库引擎正在多个区域中运行,其中每个区域都包含多个群集。Cosmos DB Graph database engine is running in multiple regions, each of which contains multiple clusters. 每个群集都有数百台计算机。Each cluster has hundreds of machines. Cosmos DB Graph 帐户 DNS CNAME 解析为群集的 DNS A 记录。Cosmos DB Graph account DNS CNAME resolves to DNS A record of a cluster. 负载平衡器的单个 IP 地址将隐藏内部群集拓扑。A single IP address of a load-balancer hides internal cluster topology.

将为 Cosmos DB Graph 帐户的每个区域创建一个区域 DNS CNAME 记录。A regional DNS CNAME record is created for every region of Cosmos DB Graph account. 区域终结点的格式是 。Format of regional endpoint is 通过删除 Azure 区域名称中的所有空格获取区域终结点的区域段。Region segment of regional endpoint is obtained by removing all spaces from Azure region name. 例如,"China East 2" 多区域数据库帐户的 "contoso" 区域将具有 DNS CNAME For example, "China East 2" region for "contoso" multiple-region database account would have a DNS CNAME

TinkerPop Gremlin 客户端设计用于单台服务器。TinkerPop Gremlin client is designed to work with a single server. 应用程序可将多区域可写入 DNS CNAME 用于读取和写入流量。Application can use multiple-regional writable DNS CNAME for read and write traffic. 可识别区域的应用程序应使用区域终结点来读取流量。Region-aware applications should use regional endpoint for read traffic. 仅在特定区域配置为接受写入时,才将区域终结点用于写入流量。Use regional endpoint for write traffic only if specific region is configured to accept writes.


Cosmos DB Graph 引擎可以通过将流量代理到写入区域来接受读取区域中的写入操作。Cosmos DB Graph engine can accept write operation in read region by proxying traffic to write region. 建议不要将写入发送到只读区域,因为这会增加遍历延迟,并且会在将来受到限制。It is not recommended to send writes into read-only region as it increases traversal latency and is subject to restrictions in the future.

多区域数据库帐户 CNAME 始终指向有效的写入区域。Multiple-region database account CNAME always points to a valid write region. 在写入区域的服务器端故障转移过程中,Cosmos DB 将多区域数据库帐户 CNAME 更新为指向新区域。During server-side failover of write region, Cosmos DB updates multiple-region database account CNAME to point to new region. 如果应用程序在故障转移后无法处理流量重新路由,则应使用多区域数据库帐户 DNS CNAME。If application can't handle traffic rerouting after failover, it should use multiple-region database account DNS CNAME.


Cosmos DB 不会根据调用方的地理位置来路由流量。Cosmos DB does not route traffic based on geographic proximity of the caller. 根据独特的应用程序需求,将由每个应用程序选择适当的区域。It is up to each application to select the right region according to unique application needs.

门户终结点发现Portal endpoint discovery

获取 Azure Cosmos DB Graph 帐户区域列表的最简单的方法是 Azure 门户中的“概述”边栏选项卡。The easiest way to get the list of regions for Azure Cosmos DB Graph account is overview blade in Azure portal. 它适用于不经常更改区域的应用程序,或者可以通过应用程序配置来更新列表。It will work for applications that do not change regions often, or have a way to update the list via application configuration.

从门户检索 Cosmos DB Graph 帐户的区域

下面的示例演示了访问区域 Gremlin 终结点的一般原则。Example below demonstrates general principles of accessing regional Gremlin endpoint. 应用程序应考虑将流量发送到的区域数量,以及要实例化的相应 Gremlin 客户端的数量。Application should consider number of regions to send the traffic to and number of corresponding Gremlin clients to instantiate.

// Example value: China East, China North and China East 2 . This can be found in the overview blade of you Azure Cosmos DB Gremlin Account. 
// Look for Write Locations in the overview blade. You can click to copy and paste.
string[] gremlinAccountRegions = new string[] {"China East", "China North" ,"China East 2"};
string gremlinAccountName = "PUT-COSMOSDB-ACCOUNT-NAME-HERE";
string gremlinAccountKey = "PUT-ACCOUNT-KEY-HERE";
string databaseName = "PUT-DATABASE-NAME-HERE";
string graphName = "PUT-GRAPH-NAME-HERE";

foreach (string gremlinAccountRegion in gremlinAccountRegions)
  // Convert preferred read location to the form "[acountname]-[region]".
  string regionalGremlinEndPoint = $"{gremlinAccountName}-{gremlinAccountRegion.ToLowerInvariant().Replace(" ", string.Empty)}";

  GremlinServer regionalGremlinServer = new GremlinServer(
    hostname: regionalGremlinEndPoint, 
    port: 443,
    enableSsl: true,
    username: "/dbs/" + databaseName + "/colls/" + graphName,
    password: gremlinAccountKey);

  GremlinClient regionalGremlinClient = new GremlinClient(
    gremlinServer: regionalGremlinServer,
    graphSONReader: new GraphSON2Reader(),
    graphSONWriter: new GraphSON2Writer(),
    mimeType: GremlinClient.GraphSON2MimeType);

SDK 终结点发现SDK endpoint discovery

应用程序可以使用 Azure Cosmos DB SDK 来发现 Graph 帐户的读取和写入位置。Application can use Azure Cosmos DB SDK to discover read and write locations for Graph account. 这些位置可以通过在服务器端进行手动重新配置或通过自动故障转移随时进行更改。These locations can change at any time through manual reconfiguration on the server side or automatic failover.

TinkerPop Gremlin SDK 没有 API 来发现 Cosmos DB Graph 数据库帐户区域。TinkerPop Gremlin SDK doesn't have an API to discover Cosmos DB Graph database account regions. 需要运行时终结点发现的应用程序需要在进程空间中托管 2 个单独的 SDK。Applications that need runtime endpoint discovery need to host 2 separate SDKs in the process space.

// Depending on the version and the language of the SDK (.NET vs Java vs Python)
// the API to get readLocations and writeLocations may vary.
IDocumentClient documentClient = new DocumentClient(
    new Uri(cosmosUrl),

DatabaseAccount databaseAccount = await cosmosClient.GetDatabaseAccountAsync();

IEnumerable<DatabaseAccountLocation> writeLocations = databaseAccount.WritableLocations;
IEnumerable<DatabaseAccountLocation> readLocations = databaseAccount.ReadableLocations;

// Pick write or read locations to construct regional endpoints for.
foreach (string location in readLocations)
  // Convert preferred read location to the form "[acountname]-[region]".
  string regionalGremlinEndPoint = location
    .Replace("http:\/\/", string.Empty)
    .Replace("", "");

  // Use code from the previous sample to instantiate Gremlin client.

后续步骤Next steps