針對 Azure Cosmos DB SDK 在多重區域環境下的可用性，進行診斷及疑難排解
適用於：
NoSQL
本文說明當看到特定區域出現連線問題，或發生區域容錯移轉時，最新版本的 Azure Cosmos DB SDK 會有何行為。
所有 Azure Cosmos DB SDK 都可供自訂區域喜好設定。 下列屬性可用於不同的 SDK：
- .NET 第 2 版 SDK 中的 ConnectionPolicy.PreferredLocations 屬性。
- .NET 第 3 版 SDK 中的 CosmosClientOptions.ApplicationRegion 或 CosmosClientOptions.ApplicationPreferredRegions 屬性。
- JAVA 第 4 版 SDK 中的 CosmosClientBuilder.preferredRegions 方法。
- Python SDK 中的 CosmosClient.preferred_locations 參數。
- JS SDK 中的 CosmosClientOptions.ConnectionPolicy.preferredLocations 參數。
當 SDK 使用指定區域喜好設定的設定來初始化時，其會先取得帳戶資訊，包括全域端點中的可用區域。 然後，其會套用已設定區域喜好設定和帳戶可用區域的交集，並使用地區喜好設定的順序來排定結果的優先順序。
如果區域喜好設定包含帳戶中不是可用區域的區域，則會忽略這些值。 如果稍後將這些無效區域新增至帳戶，則 SDK 會在喜好設定中較高時使用這些區域。
| 帳戶類型 | Reads | Writes |
|---|---|---|
| 單一寫入區域 | 具有最高順序的慣用區域 | 主要區域 |
| 多重寫入區域 | 具有最高順序的慣用區域 | 具有最高順序的慣用區域 |
若未設定慣用區域，SDK 用戶端會預設為主要區域：
| 帳戶類型 | Reads | Writes |
|---|---|---|
| 單一寫入區域 | 主要區域 | 主要區域 |
| 多重寫入區域 | 主要區域 | 主要區域 |
注意
主要區域指的是 Azure Cosmos DB 帳戶區域清單上的第一個區域。 在區域喜好設定中所指定的值，若不符合任何現有的 Azure 區域，則會遭到忽略。 若該值與現有區域相符，但帳號並未複製到該區域，則用戶端會連線到下一個符合的慣用區域，或是連線到主要區域。
警告
本文所述的容錯移轉和可用性邏輯，可在用戶端設定中停用。但除非使用者應用程式將會自行處理可用性錯誤，否則不建議這樣做。 執行方式如下：
- 將 .NET 第 2 版 SDK 中的 ConnectionPolicy.EnableEndpointDiscovery 屬性設為 False。
- 將 .NET 第 3 版 SDK 中的 CosmosClientOptions.LimitToEndpoint 屬性設為 True。
- 將 Java 第 4 版 SDK 中的 CosmosClientBuilder.endpointDiscoveryEnabled 方法設為 False。
- 將 Python SDK 中的 CosmosClient.enable_endpoint_discovery 參數設定為 False。
- 將 JS SDK 中的 CosmosClientOptions.ConnectionPolicy.enableEndpointDiscovery 參數設為 False。
正常情況下，除非發生以下任一情形，否則 SDK 用戶端會連線到慣用區域 (若已設定區域喜好設定) 或主要區域 (若未設定喜好設定)，且會將作業限制在該區域。
在這些案例中，使用 Azure Cosmos DB SDK 的用戶端公開記錄，且將重試資訊納入作業診斷資訊之中：
- .NET 第 2 版 SDK 中回應上的 RequestDiagnosticsString 屬性。
- .NET 第 3 版 SDK 中回應和例外狀況上的 Diagnostics 屬性。
- 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