本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

中的重試次數 適用於 Kotlin 的 AWS SDK

呼叫 AWS 服務 偶爾會傳回未預期的例外狀況。如果重試呼叫，某些類型的錯誤可能會成功，例如限流或暫時性錯誤。

此頁面說明如何自動 適用於 Kotlin 的 AWS SDK 處理重試，以及如何為您的應用程式自訂重試行為。

了解重試行為

下列各節說明 SDK 如何決定何時重試請求，以及哪些例外狀況被視為可重試。

預設重試組態

根據預設，每個服務用戶端都會自動設定標準重試策略。預設組態會嘗試最多失敗三次的呼叫 （初始嘗試加上兩次重試）。每個呼叫之間的介入延遲會設定為指數退避和隨機抖動，以避免重試風暴。此組態適用於大多數使用案例，但在某些情況下可能不適合，例如高輸送量系統。

開發套件只會在可重試的錯誤上重試。可重試錯誤的範例包括通訊端逾時、服務端調節、並行或樂觀鎖定失敗，以及暫時性服務錯誤。遺失或無效的參數、身分驗證/安全錯誤，以及設定錯誤的例外狀況都視為無法重試。

您可以設定最大嘗試次數、延遲和退避，以及字符儲存貯體組態，來自訂標準重試策略。

哪些例外狀況可以重試？

適用於 Kotlin 的 AWS SDK 使用預先設定的重試政策，決定哪些例外狀況可以重試。服務用戶端組態具有retryPolicy屬性，可指定套用至重試的政策。如果未指定自訂值，則預設值為 AwsRetryPolicy。

下列例外狀況由 判斷為可重試AwsRetryPolicy：

依錯誤碼重試

任何ServiceException具有 sdkErrorMetadata.errorCode的 ：

可透過 HTTP 狀態碼重試

任何ServiceException具有 sdkErrorMetadata.statusCode的 ：

依錯誤類型重試

任何ServiceException具有 sdkErrorMetadata.errorType的 ：

可由 SDK 中繼資料重試

下列任何SdkBaseException位置：

如需每個服務用戶端可能擲回之例外狀況的完整清單，請參閱服務特定的 API 參考文件。

檢查例外狀況是否可重試

若要判斷 SDK 是否將例外狀況視為可重試，請檢查抓取例外狀況的 isRetryable 屬性：

try {
    dynamoDbClient.putItem {
        tableName = "MyTable"
        item = mapOf("id" to AttributeValue.S("123"))
    }
} catch (e: SdkBaseException) {
    println("Exception occurred: ${e.message}")
    
    if (e.sdkErrorMetadata.isRetryable) {
        println("This exception is retryable - SDK will automatically retry")
        println("If you're seeing this, retries may have been exhausted")
    } else {
        println("This exception is not retryable - fix the underlying issue")
        
        // Common non-retryable scenarios.
        when {
            e.message?.contains("ValidationException") == true -> 
                println("Check your request parameters")
            e.message?.contains("AccessDenied") == true -> 
                println("Check your IAM permissions")
            e.message?.contains("ResourceNotFound") == true -> 
                println("Verify the resource exists")
        }
    }
}

當重試失敗時，哪些例外狀況會到達您的程式碼

當開發套件的重試機制無法解決問題時，您的應用程式程式碼會擲回例外狀況。了解這些例外狀況類型可協助您實作適當的錯誤處理。這些不是觸發重試的例外狀況 - 這些例外狀況是由 SDK 在內部處理。

當重試用盡或停用時，您的程式碼會擷取以下類型的例外狀況：

使用下列模式來處理應用程式中的這些例外狀況：

try {
    s3Client.getObject { 
        bucket = "amzn-s3-demo-bucket"
        key = "my-key" 
    }
} catch (e: AwsServiceException) {
    // Service-side errors that persisted through all retries.
    println("Service error after retries: ${e.errorDetails?.errorCode} - ${e.message}")
    
    // Handle specific service errors that couldn't be resolved.
    if (e.errorDetails?.errorCode == "ServiceQuotaExceededException" || 
        e.errorDetails?.errorCode == "ThrottlingException") {
        println("Rate limiting persisted - consider longer delays or quota increase")
    }
} catch (e: ClientException) {
    // Client-side errors (persistent network issues, DNS resolution failures, etc.)
    println("Client error after retries: ${e.message}")
}

自訂重試行為

下列各節說明如何針對特定使用案例自訂 SDK 的重試行為。

設定最大嘗試次數

您可以在用戶端建構期間自訂 retryStrategy DSL 區塊中的預設最大嘗試次數 (3)。

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy {
        maxAttempts = 5
    }
}

使用上一個程式碼片段中顯示的 DynamoDB 服務用戶端，軟體開發套件會嘗試失敗最多五次的 API 呼叫 （初次嘗試加上四次重試）。

您可以將最大嘗試次數設定為一個，完全停用自動重試，如下列程式碼片段所示。

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy {
        maxAttempts = 1  // The SDK makes no retries.
    }
}

設定延遲和退避

如果需要重試，預設重試策略會先等待，再進行後續嘗試。第一次重試的延遲很小，但之後重試會呈指數增長。延遲的最大數量會受到限制，使其不會太大。

最後，隨機抖動會套用至所有嘗試之間的延遲。抖動有助於減輕可能導致重試風暴的大型機群的影響。（如需指數退避和抖動的深入討論，請參閱此AWS 架構部落格文章。)

延遲參數可在 delayProvider DSL 區塊中設定。

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy {
        delayProvider {
            initialDelay = 100.milliseconds
            maxBackoff = 5.seconds
        }
    }
}

使用上一個程式碼片段中顯示的組態，用戶端會將第一次重試嘗試延遲最多 100 毫秒。任何重試嘗試之間的時間上限為 5 秒。

下列參數可用於調校延遲和退避。

設定重試權杖儲存貯體

您可以調整預設字符儲存貯體組態，進一步修改標準重試策略的行為。重試字符儲存貯體有助於減少不太可能成功或可能需要更多時間才能解決的重試，例如逾時和限流失敗。

每次重試嘗試 （選擇性地包含初始嘗試） 都會從字符儲存貯體減少一些容量。減少的數量取決於嘗試的類型。例如，重試暫時性錯誤可能很便宜，但重試逾時或限流錯誤可能更昂貴。

成功嘗試會將容量傳回至儲存貯體。儲存貯體不可增加到超過其最大容量，也不會減少到零以下。

根據useCircuitBreakerMode設定的值， 嘗試將容量減少到零以下會導致下列其中一個結果：

權杖儲存貯體參數可在 tokenBucket DSL 區塊中設定：

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy {
        tokenBucket {
            maxCapacity = 100
            refillUnitsPerSecond = 2
        }
    }
}

下列參數可用於調校重試字符儲存貯體：

如需重試案例期間擲回的例外狀況類型詳細資訊，包括斷路器例外狀況，請參閱 當重試失敗時，哪些例外狀況會到達您的程式碼。

設定適應性重試

作為標準重試策略的替代方案，自適應重試策略是一種進階方法，可尋求理想的請求率，以將限流錯誤降至最低。

自適應重試包含標準重試的所有功能。它會新增用戶端速率限制器，測量節流請求相較於非節流請求的速率。它也會限制流量以嘗試保持在安全頻寬內，理想情況下會導致零限流錯誤。

速率會即時適應不斷變化的服務條件和流量模式，並可能相應地增加或減少流量速率。最重要的是，速率限制器可能會延遲高流量案例中的初始嘗試。

您可以為 retryStrategy方法提供額外的參數，以選取自適應重試策略。速率限制器參數可在 rateLimiter DSL 區塊中設定。

val dynamoDb = DynamoDbClient.fromEnvironment {
    retryStrategy(AdaptiveRetryStrategy) {
        maxAttempts = 10
        rateLimiter {
            minFillRate = 1.0
            smoothing = 0.75
        }
    }
}