使用 Python 實作重試原則

在雲端中執行或與遠端服務和資源通訊的任何應用程式都必須能夠處理暫時性錯誤。 這些應用程式通常會因為網路連線短暫中斷、服務或資源忙碌時的要求逾時，或其他因素而遇到錯誤。 開發人員應該建置應用程式，以透明方式處理暫時性錯誤，進而改善穩定性和復原能力。

在本文中，您將瞭解如何使用適用於 Python 的 Azure 儲存體 客戶端連結庫，為聯機到 Azure Blob 儲存體 的應用程式設定重試原則。 重試原則會定義應用程式如何處理失敗的要求，而且應該一律進行調整，以符合應用程式的商務需求和失敗的性質。

設定重試選項

Blob 儲存體的重試原則是以程式設計方式設定，可控制如何將重試選項套用至各種服務要求和案例。 例如，根據使用者互動發出要求的 Web 應用程式，可能會實作具有較少重試和較短延遲的原則，以增加回應性並在發生錯誤時通知使用者。 或者，在背景中執行批次要求的應用程式或元件可能會增加重試次數，並使用指數輪詢策略來允許要求時間順利完成。

若要設定用戶端要求的重試原則，您可以從下列方法中選擇：

• 使用預設值：適用於 Python Azure 儲存體 用戶端連結庫的預設重試原則是具有預設值的 ExponentialRetry 實例。 如果您未指定重試原則，則會使用預設的重試原則。
• 將值當做關鍵詞傳遞至用戶端建構函式：當您建立服務的客戶端物件時，可以將重試原則屬性的值當做關鍵詞自變數傳遞。 這個方法可讓您自定義用戶端的重試原則，而且只有在您只需要設定幾個選項時才有用。
• 建立重試原則類別的實例：您可以建立 ExponentialRetry 或 LinearRetry 類別的實例，並設定屬性來設定重試原則。 然後，您可以將 實例傳遞至用戶端建構函式，以將重試原則套用至所有服務要求。

下表顯示可用來設定重試原則的所有屬性。 這些屬性中的任何屬性都可以當做關鍵詞傳遞至用戶端建構函式，但有些屬性只能與 或 LinearRetry 實例搭配ExponentialRetry使用。 數據表中會記下這些限制，如果您未進行任何變更，則會加上每個屬性的預設值。 您應該主動調整這些屬性的值，以符合應用程式的需求。

屬性	類型​	描述	預設值	ExponentialRetry	LinearRetry
retry_total	int	重試次數上限。	3	Yes	Yes
retry_connect	int	線上重試次數上限	3	Yes	Yes
retry_read	int	讀取重試次數上限	3	Yes	Yes
retry_status	int	狀態重試次數上限	3	Yes	Yes
retry_to_secondary	bool	如果能夠，是否應將要求重試至次要端點。 只針對已啟用異地備援複寫的記憶體帳戶使用此選項，例如RA-GRS或RA-GZRS。 您也應該確保應用程式可以處理可能過時的數據。	False	Yes	Yes
initial_backoff	int	第一次重試的初始輪詢間隔（以秒為單位）。 僅適用於指數輪詢策略。	15 秒	是	No
increment_base	int	第一次重試之後，要遞增initial_backoff的基底 （以秒為單位）。 僅適用於指數輪詢策略。	3 秒	是	No
backoff	int	每次重試之間的輪詢間隔（以秒為單位）。 僅適用於線性輪詢策略。	15 秒	No	Yes
random_jitter_range	int	數位（以秒為單位），表示輪詢間隔的抖動/隨機化範圍。 例如，將 設定 random_jitter_range 為 3 表示 x 的輪詢間隔可能會因 x+3 和 x-3 而有所不同。	3 秒	Yes	是

注意

屬性 retry_connect、 retry_read和 retry_status 是用來計算不同類型的錯誤。 剩餘的重試計數會計算為 下列值的最小值 ： retry_total、 retry_connect、 retry_read和 retry_status。 因此，除非您也設定其他屬性，否則設定可能不會產生 retry_total 作用。 在大部分情況下，您可以將這四個屬性全部設定為相同的值，以強制執行重試次數上限。 不過，您應該根據應用程式的特定需求來調整這些屬性。

下列各節說明如何使用不同的方法來設定重試原則：

• 使用預設重試原則
• 建立 ExponentialRetry 原則
• 建立LinearRetry原則

使用預設重試原則

適用於 Python Azure 儲存體 客戶端連結庫的預設重試原則是具有預設值的 ExponentialRetry 實例。 如果您未指定重試原則，則會使用預設的重試原則。 您也可以在建立服務的客戶端物件時，將任何組態屬性當做關鍵詞自變數傳遞。

下列程式代碼範例示範如何在建立 Blob 服務的客戶端物件時，將屬性的值 retry_total 當做關鍵詞自變數傳遞。 在此範例中，客戶端物件會使用預設重試原則，並將 retry_total 屬性和其他重試計數屬性設定為 5：

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

# Create the BlobServiceClient object with retry options
blob_service_client = BlobServiceClient(account_url, credential, retry_total=5,
                                        retry_connect=5, retry_read=5, retry_status=5)

建立 ExponentialRetry 原則

您可以建立 ExponentialRetry 的實例，並使用 關鍵詞自變數將實例傳遞至用戶端建構retry_policy函式，以設定重試原則。 如果您需要為不同的客戶端設定多個屬性或多個原則，這個方法就很有用。

下列程式代碼範例示範如何使用 的 ExponentialRetry實例來設定重試選項。 在此範例中，我們設定 initial_backoff 為 10 秒、 increment_base 4 秒，以及 retry_total 3 次重試：

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

# Specify retry policy parameters
retry = ExponentialRetry(initial_backoff=10, increment_base=4, retry_total=3)

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential, retry_policy=retry)

建立LinearRetry原則

您可以建立LinearRetry的實例，並使用 關鍵詞自變數將實例傳遞至用戶端建構retry_policy函式，以設定重試原則。 如果您需要為不同的客戶端設定多個屬性或多個原則，這個方法就很有用。

下列程式代碼範例示範如何使用 的 LinearRetry實例來設定重試選項。 在這裡範例中，我們設定為 10 秒、 retry_total 3 次重試，以及 retry_to_secondary 設定backoff為 True：

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

# Specify retry policy parameters
retry = LinearRetry(backoff=10, retry_total=3, retry_to_secondary=True)

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential, retry_policy=retry)

下一步

• 本文是適用於 Python 的 Blob 記憶體開發人員指南的一部分。 請參閱建置應用程式的完整開發人員指南文章清單。
• 如需重試原則的架構指引和一般最佳做法，請參閱暫時性錯誤處理。
• 如需針對暫時性失敗實作重試模式的指引，請參閱重試模式。