기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 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 작업의 단일 시도에 대한 최대 시간을 설정합니다. 이 제한 시간을 초과하면 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. **스마트 기본값**은 대부분의 애플리케이션에 적합한 시작점을 제공합니다.

사용 사례에 맞게 제한 시간을 적절하게 구성하여 네트워크 문제에 복원력이 뛰어나고 사용자에게 응답하는 애플리케이션을 구축합니다.