本文描述了当您遇到与特定区域的连接问题或发生区域故障转移时，最新版本的 Azure Cosmos DB SDK 的行为。
所有 Azure Cosmos DB SDK 都提供自定义区域首选项的选项。 不同 SDK 中使用以下属性：
- .NET V2 SDK 中的 ConnectionPolicy.PreferredLocations 属性。
- .NET V3 SDK 中的 CosmosClientOptions.ApplicationRegion或 CosmosClientOptions.ApplicationPreferredRegions 属性。
- Java V4 SDK 中的 CosmosClientBuilder.preferredRegions 方法。
- Python SDK 中的 CosmosClient.preferred_locations 参数。
- JS SDK 中的 CosmosClientOptions.ConnectionPolicy.preferredLocations 参数。
当 SDK 使用指定区域首选项的配置进行初始化时，它将首先从多区域终结点获取帐户信息，包括可用区域。 然后，它将应用配置的区域首选项与账户的可用区域的交集，并按区域首选项中的顺序对结果进行优先级排序。
如果区域首选项配置包含帐户中没有可用区域的区域，将忽略这些值。 如果这些无效区域稍后添加到帐户，并且它们在首选项配置中具有更高的优先级，SDK 会使用它们。
| 科目类型 | 读取数 | Writes |
|---|---|---|
| 单个写入区域 | 具有最高顺序的首选区域 | 主要区域 |
| 多个写入区域 | 具有最高顺序的首选区域 | 具有最高顺序的首选区域 |
如果未 设置首选区域，SDK 客户端默认为主要区域：
| 科目类型 | 读取数 | Writes |
|---|---|---|
| 单个写入区域 | 主要区域 | 主要区域 |
| 多个写入区域 | 主要区域 | 主要区域 |
注释
主要区域是指 Azure Cosmos DB 帐户区域列表中的第一个区域。 如果指定为区域首选项的值与任何现有 Azure 区域不匹配，将忽略它们。 如果它们与现有区域匹配，但帐户未复制到该区域，则客户端将连接到下一个符合条件的首选区域或主要区域。
警告
本文档中所述的故障转移和可用性逻辑可以在客户端配置上禁用，除非用户应用程序将自行处理可用性错误，否则不建议这样做。 可以通过以下方式来实现此目的：
- 将 .NET V2 SDK 中的 ConnectionPolicy.EnableEndpointDiscovery 属性设置为 false。
- 将 .NET V3 SDK 中的 CosmosClientOptions.LimitToEndpoint 属性设置为 true。
- 将 Java V4 SDK 中的 CosmosClientBuilder.endpointDiscoveryEnabled 方法设置为 false。
- 将 Python SDK 中的 CosmosClient.enable_endpoint_discovery 参数设置为 false。
- 将 JS SDK 中的 CosmosClientOptions.ConnectionPolicy.enableEndpointDiscovery 参数设置为 false。
在正常情况下，SDK 客户端将连接到首选区域（如果设置了区域首选项）或主要区域（如果未设置首选项），除非出现以下任一情况，否则作将限制为该区域。
在这些情况下，使用 Azure Cosmos DB SDK 的客户端公开日志，并在 作诊断信息中包含重试信息：
- .NET V2 SDK 中响应的 RequestDiagnosticsString 属性。
- .NET V3 SDK 中响应和异常的 诊断 属性。
- Java V4 SDK 中响应和异常的 getDiagnostics（） 方法。
根据首选项顺序确定下一个区域时，SDK 客户端将使用帐户区域列表，将首选区域（如果有） 作为优先级。
有关这些事件期间 SLA 保证的全面详细信息，请参阅 SLA 的可用性。
从帐户中删除区域
从 Azure Cosmos DB 帐户中删除区域时，主动使用该帐户的任何 SDK 客户端都将通过后端响应代码检测区域删除。 然后，客户端将区域终结点标记为不可用。 客户端重试当前操作，所有未来的操作将按首选顺序永久路由到下一个区域。 如果首选项列表只有一个条目（或为空），但该帐户具有其他可用区域，它将路由到帐户列表中的下一个区域。
将区域添加到帐户
Azure Cosmos DB SDK 客户端每隔 5 分钟读取一次帐户配置并刷新其感知的区域。
如果删除某个区域，然后将其添加回帐户，如果 SDK 配置中的区域首选项顺序高于当前连接区域，则 SDK 将切换回此区域以永久使用此区域。 检测到添加的区域后，所有将来的请求都会定向到该区域。
如果将客户端配置为最好连接到 Azure Cosmos DB 帐户没有的区域，则会忽略首选区域。 如果稍后添加该区域，客户端将检测到它，并将永久切换到该区域。
在单个写入区域帐户中故障转移写入区域
如果启动当前写入区域的故障转移，则下一个写入请求将失败并显示已知的后端响应。 检测到此响应后，客户端将查询帐户以了解新的写入区域，并继续重试当前作，并将所有将来的写入作永久路由到新区域。
区域中断
如果帐户是单个写入区域，并且在写入操作期间发生区域性中断，则行为类似于 手动故障转移。 对于读取请求或多个写入区域帐户，行为类似于 删除区域。
会话一致性保证
使用 会话一致性时，客户端需要保证它可以读取自己的写入。 在仅有一个写入区域且读取区域偏好与写入区域不同的帐户中，用户可能会执行写入操作，然后再从本地读取数据。在这种情况下，由于光速限制，本地区域可能尚未接收到数据复制。 在这种情况下，SDK 在读取操作时从服务收到特定的失败，并在主要区域重试，以确保会话一致性。
TCP 协议上的暂时性连接问题
在将 Azure Cosmos DB SDK 客户端配置为使用 TCP 协议的给定请求的情况下，可能存在网络条件暂时影响与特定终结点的通信的情况。 这些临时网络条件可以显示为 TCP 超时和服务不可用（HTTP 503）错误。 如果可能，客户端将在本地同一终结点上 重试请求 一些秒。
如果用户配置了具有多个区域的首选区域列表，并且客户端用尽了所有本地重试次数，则可以尝试在首选项列表中的下一个区域中重试该操作。 仅当 Azure Cosmos DB 帐户启用了多个写入区域时，才能在其他区域中重试写入作，同时可以在任何可用区域中重试读取作。
后续步骤
- 查看 可用性SLA。
- 使用最新的 .NET SDK
- 使用最新的 Java SDK
- 使用最新的 Python SDK
- 使用最新的 Node SDK