翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# AWS SDK for Java 2.x でタイムアウトを設定する
<a name="timeouts"></a>

AWS SDK for Java 2.x には、回復力に優れたアプリケーションの構築に役立つ複数のタイムアウト設定レイヤーが用意されています。SDK には、アプリケーションのパフォーマンスと信頼性を最適化するために連携するさまざまなタイプのタイムアウトが用意されています。

SDK のタイムアウトには主に 2 つのカテゴリがあります。
+ **サービスクライアントのタイムアウト** - 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 オペレーションの 1 回の試行の最大時間を設定します。このタイムアウトを超えると、SDK は呼び出し全体を失敗させるのではなく、オペレーションを再試行します (再試行が設定されている場合）。

```
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>

SDK for Java 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) には、AWS SDK for Java 2.x の HTTP クライアントに関する詳細情報が含まれています。

## タイムアウトの相互作用と階層
<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 ネゴシエーションタイムアウト値。
+ その他のクライアント設定。

## 概要
<a name="timeout-summary"></a>

AWS SDK for Java 2.x での効果的なタイムアウト設定には、サービスクライアントのタイムアウトと HTTP クライアントのタイムアウト間の相互作用を理解する必要があります。

1. **サービスクライアントのタイムアウトは**、高レベルの API 動作を制御します。

1. **HTTP クライアントのタイムアウトは**、低レベルのネットワーク動作を制御します。

1. **適切な階層**により、タイムアウトが効果的に連携します。

1. **スマートデフォルト**は、ほとんどのアプリケーションに適した出発点です。

ユースケースに合わせてタイムアウトを適切に設定することで、ネットワークの問題に対する回復力とユーザーに対する応答性の両方を備えたアプリケーションを構築できます。