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

# 在 中設定逾時 AWS SDK for Java 2.x
<a name="timeouts"></a>

 AWS SDK for Java 2.x 提供多層逾時組態，協助您建置彈性應用程式。開發套件提供不同類型的逾時，可共同最佳化應用程式的效能和可靠性。

開發套件中有兩種主要的逾時類別：
+ **服務用戶端逾時** - 控制 API 操作的高階逾時
+ **HTTP 用戶端逾時** - 控制網路通訊的低階逾時

## 服務用戶端逾時
<a name="service-client-timeouts"></a>

服務用戶端逾時會在 API 層級運作，並控制服務操作的整體行為，包括重試和多次嘗試。

### API 呼叫逾時
<a name="api-call-timeout"></a>

API 呼叫逾時會設定整個 API 操作的時間上限，包括所有重試嘗試。此逾時對應用程式等待完成操作的時間提供硬性限制。

```
S3Client s3Client = S3Client.builder()
    .overrideConfiguration(ClientOverrideConfiguration.builder()
        .apiCallTimeout(Duration.ofMinutes(2))  // Total time for entire operation, such as when you call the getObject method.
        .build())
    .build();
```

關鍵特性：
+ 包含所有重試嘗試。
+ 包括重試之間等待所花費的時間。
+ 提供絕對最長等待時間。
+ 防止操作無限期執行。

### API 呼叫嘗試逾時
<a name="api-call-attempt-timeout"></a>

API 呼叫嘗試逾時會設定 API 操作的單一嘗試時間上限。如果超過此逾時，開發套件會重試 操作 （如果已設定重試），而不是整個呼叫失敗。

```
S3Client s3Client = S3Client.builder()
    .overrideConfiguration(ClientOverrideConfiguration.builder()
        .apiCallAttemptTimeout(Duration.ofSeconds(30))  // Time for single attempt.
        .build())
    .build();
```

關鍵特性：
+ 僅適用於個別嘗試。
+ 啟用快速失敗並重試慢速請求。
+ 必須短於 API 呼叫逾時。
+ 協助識別暫時性問題並從中復原。

### 設定服務用戶端逾時
<a name="service-timeout-configuration"></a>

您可以針對所有操作或每個請求，全域設定服務用戶端逾時：

**全域組態：**

```
S3Client s3Client = S3Client.builder()
    .overrideConfiguration(b -> b
        .apiCallTimeout(Duration.ofSeconds(105L))
        .apiCallAttemptTimeout(Duration.ofSeconds(25L)))
    .build();
// When you use the s3Client for an API operation, the SDK uses the configured timeout values.
```

**每個請求組態：**

```
S3Client basicS3Client = S3Client.create();

// The following configuration uses the same settings as shown before, but these settings
// apply to only the `putObject` call. When you use `basicS3Client` in another API call without
// supplying the override configuration, there are no API timeout limits. No timeout limits is the default for the SDK.
AwsRequestOverrideConfiguration overrideConfiguration = AwsRequestOverrideConfiguration.builder()
    .apiCallTimeout(Duration.ofSeconds(105L))
    .apiCallAttemptTimeout(Duration.ofSeconds(25L))
    .build();

basicS3Client.putObject(b -> b
        .bucket("amzn-s3-demo-bucket")
        .key("example-key")
        .overrideConfiguration(overrideConfiguration),
    RequestBody.fromString("test"));
```

### API 逾時的最佳實務
<a name="timeout-best-practice"></a>

適用於 Java 的 SDK 2.x 預設不會設定 API 呼叫逾時或個別 API 呼叫嘗試逾時。設定個別嘗試和整個請求的逾時。這有助於您的應用程式在暫時性問題導致請求嘗試需要更長的時間或發生嚴重網路問題時快速失敗。

## HTTP 用戶端逾時
<a name="http-client-timeouts"></a>

HTTP 用戶端逾時會在網路層級運作，並控制 HTTP 通訊的各個層面。這些逾時會根據您使用的 HTTP 用戶端實作而有所不同。

### 連線逾時
<a name="connection-timeout"></a>

連線逾時控制在建立與 AWS 服務 端點的新連線時要等待的時間。

```
// Available with all HTTP clients.
ApacheHttpClient.builder()
    .connectionTimeout(Duration.ofSeconds(5L))
    .build();
```

目的：
+ 防止懸置在網路連線問題上。
+ 當服務無法連線時， 會快速失敗。
+ 對於需要回應式錯誤處理的應用程式至關重要。

### 通訊端逾時 (Apache 和 URLConnection 用戶端）
<a name="socket-timeout"></a>

通訊端逾時會控制在已建立的連線上等待資料的時間長度。

```
ApacheHttpClient.builder()
    .socketTimeout(Duration.ofSeconds(30L))  // Time to wait for response data.
    .build();
```

### 讀取和寫入逾時 (Netty 用戶端）
<a name="read-write-timeouts"></a>

Netty 用戶端為讀取和寫入操作提供單獨的逾時：

```
NettyNioAsyncHttpClient.builder()
    .readTimeout(Duration.ofSeconds(30L))   // Reading response data.
    .writeTimeout(Duration.ofSeconds(30L))  // Writing request data.
    .build();
```

### TLS 交涉逾時 (Netty 用戶端）
<a name="tls-negotiation-timeout"></a>

控制允許 TLS/SSL 交握的時間：

```
NettyNioAsyncHttpClient.builder()
    .tlsNegotiationTimeout(Duration.ofSeconds(3L))
    .build();
```

### 連線集區逾時
<a name="connection-pool-timeouts"></a>

有些 HTTP 用戶端提供連線集區操作的逾時：

```
ApacheHttpClient.builder()
    .connectionAcquisitionTimeout(Duration.ofSeconds(10L))  // Wait for pool connection.
    .connectionTimeToLive(Duration.ofMinutes(5L))           // Maximum connection age.
    .connectionMaxIdleTime(Duration.ofSeconds(60L))         // Maximum idle time.
    .build()
```

[設定 HTTP 用戶端](http-configuration.md) 包含 中 HTTP 用戶端的詳細資訊 AWS SDK for Java 2.x

## 逾時互動和階層
<a name="timeout-interactions"></a>

了解不同的逾時如何互動對於適當的組態至關重要：

### 逾時階層
<a name="timeout-hierarchy"></a>

```
API Call Timeout (2 minutes)
├── Retry Attempt 1
│   ├── API Call Attempt Timeout (45 seconds)
│   └── HTTP Client Timeouts
│       ├── Connection Timeout (5 seconds)
│       ├── TLS Negotiation Timeout (3 seconds)
│       └── Read/Write Timeout (30 seconds)
├── Retry Attempt 2
│   └── [Same structure as Attempt 1]
└── Retry Attempt 3
    └── [Same structure as Attempt 1]
```

### 組態規則
<a name="configuration-rules"></a>

API 呼叫逾時 ≥ API 呼叫嘗試逾時  

```
// Correct configuration.
.apiCallTimeout(Duration.ofMinutes(2))         // 120 seconds.
.apiCallAttemptTimeout(Duration.ofSeconds(30)) // 30 seconds.
```

API 呼叫嘗試逾時 ≥ HTTP 用戶端逾時  

```
// HTTP client timeouts must be less than attempt timeout.
.apiCallAttemptTimeout(Duration.ofSeconds(30L))   // 30 seconds.
// HTTP client configuration.
.connectionTimeout(Duration.ofSeconds(5L))        // 5 seconds.
.readTimeout(Duration.ofSeconds(25L))             // 25 seconds (< 30).
```

考慮多次嘗試  

```
// If you have 3 retry attempts, each taking up to 30 seconds
// API call timeout must be at least 90 seconds plus overhead.
.apiCallTimeout(Duration.ofMinutes(2L))          // 120 seconds.
.apiCallAttemptTimeout(Duration.ofSeconds(30))   // 30 seconds per attempt.
```

## 使用智慧組態預設值
<a name="smart-configuration-defaults"></a>

SDK 提供智慧型預設值，可自動設定適當的逾時值：

```
// Enable smart defaults.
S3Client client = S3Client.builder()
    .defaultsMode(DefaultsMode.AUTO)  // Automatically choose appropriate defaults.
    .build();

// Available modes:
// - STANDARD: Balanced defaults
// - IN_REGION: Optimized for same-region calls
// - CROSS_REGION: Optimized for cross-region calls  
// - MOBILE: Optimized for mobile applications
// - AUTO: Automatically detect and choose appropriate mode
// - LEGACY: Provides settings that were used before smart defaults existed.
```

智慧型預設值會自動設定：
+ 連線逾時值。
+ TLS 交涉逾時值。
+ 其他用戶端設定。

## Summary
<a name="timeout-summary"></a>

中的有效逾時組態 AWS SDK for Java 2.x 需要了解服務用戶端逾時與 HTTP 用戶端逾時之間的互動：

1. **服務用戶端逾時**控制高階 API 行為。

1. **HTTP 用戶端逾時**控制低階網路行為。

1. **適當的階層**可確保逾時有效地協同運作。

1. **智慧預設值**可為大多數應用程式提供良好的起點。

為您的使用案例適當設定逾時，以建置可應對網路問題並回應使用者的應用程式。