기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# AWS CRT 기반 HTTP 클라이언트 구성
AWS CRT 기반 HTTP 클라이언트에는 동기 [AwsCrtHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.html)와 비동기 [AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html)가 포함됩니다. AWS CRT 기반 HTTP 클라이언트는 다음과 같은 HTTP 클라이언트 이점을 제공합니다.
+ 더 빠른 SDK 시작 시간
+ 더 작은 메모리 공간
+ 대기 시간 단축
+ 연결 상태 관리
+ DNS 로드 밸런싱
**AWS SDK의 CRT 기반 구성 요소**
이 주제에 설명된 AWS CRT 기반* HTTP* 클라이언트와 AWS CRT 기반 *S3* 클라이언트는 SDK의 서로 다른 구성 요소입니다.
동기식 및 비동기식 **AWS CRT 기반 HTTP 클라이언트**는 SDK HTTP 클라이언트 인터페이스를 구현한 것으로, 일반적인 HTTP 통신에 사용됩니다. SDK의 다른 동기 또는 비동기 HTTP 클라이언트에 대한 대안으로 추가적인 이점이 있습니다.
**[AWS CRT 기반 S3 클라이언트](crt-based-s3-client.md)**는 [S3AsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3AsyncClient.html) 인터페이스를 구현한 것으로, Amazon S3 서비스를 사용하는 데 사용됩니다. 이는 `S3AsyncClient` 인터페이스의 Java 기반 구현의 대안이며 여러 가지 이점을 제공합니다.
두 구성 요소 모두 [AWS 공통 런타임](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html)의 라이브러리를 사용하지만 AWS CRT 기반 HTTP 클라이언트는 [aws-c-s3 라이브러리](https://github.com/awslabs/aws-c-s3)를 사용하지 않으며 [S3 멀티파트 업로드 API](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html) 기능을 지원하지 않습니다. 반면 AWS CRT 기반 S3 클라이언트는 S3 멀티파트 업로드 API 기능을 지원하도록 특별히 구축되었습니다.
## AWS CRT 기반 HTTP 클라이언트에 액세스
AWS CRT 기반 HTTP 클라이언트를 사용하려면 먼저 최소 버전이 2.22.0인 `aws-crt-client` 아티팩트를 프로젝트의 종속성에 추가합니다.
다음 옵션 중 하나를 사용하여 Maven `pom.xml` 파일을 설정합니다.
**참고**
예를 들어 애플리케이션이 AWS Lambda 함수에서 실행되는 경우 런타임 종속성의 크기를 더 작게 유지해야 하는 경우 *플랫폼별 jar 옵션을* 사용하도록 선택할 수 있습니다.
------
#### [ Uber-jar option ]
기본적으로는 Linux, Windows 및 macOS를 비롯한 여러 플랫폼의 바이너리가 포함된 AWS CRT 아티팩트의 uber-jar를 `aws-crt-client` 사용합니다.
```
2.29.10*
software.amazon.awssdk
bom
${aws.sdk.version}
pom
import
software.amazon.awssdk
aws-crt-client
```
\$1빨간색으로 표시된 버전을 사용하려는 Java SDK 버전으로 바꿉니다. [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)에서 최신 정보를 찾습니다.
------
#### [ Platform-specific jar option ]
Java 런타임을 AWS CRT 라이브러리의 플랫폼별 버전으로 제한하려면 *Uber-jar 옵션을* 다음과 같이 변경합니다.
+ SDK의 `aws-crt-client` 아티팩트에 `exclusions` 요소를 추가합니다. 이 제외는 SDK가 AWS CRT uber-jar를 전이적으로 사용하는 것을 방지합니다.
+ 필요한 특정 AWS CRT 플랫폼 버전에 대한 종속성 요소를 추가합니다. 올바른 **버전을 결정하는 방법은 아래 AWS CRT 아티팩트 버전을 결정하는 단계를** 참조하세요.
```
2.29.101
software.amazon.awssdk
bom
${aws.sdk.java.version}
pom
import
software.amazon.awssdk
aws-crt-client
software.amazon.awssdk.crt
aws-crt
software.amazon.awssdk.crt
aws-crt
0.31.32
linux-x86_643
```
1빨간색으로 표시된 버전을 사용하려는 Java SDK 버전으로 바꿉니다. [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)에서 최신 정보를 찾습니다.
2*Uber-jar 옵션*에서 제공하는 `software.amazon.awssdk.crt:aws-crt`의 버전을 바꿉니다. ** AWS CRT 아티팩트 버전을 확인하려면 다음 단계를 참조하세요**.
3`classifier` 값을 플랫폼의 값으로 바꿉니다. [사용 가능한 값 목록은](https://github.com/awslabs/aws-crt-java?tab=readme-ov-file#platform-specific-jars) Java GitHub용 AWS CRT 페이지를 참조하세요.
**AWS CRT 아티팩트 버전을 확인하는 단계**
다음 단계를 사용하여 사용 중인 Java용 SDK 버전과 호환되는 AWS CRT 아티팩트 버전을 확인합니다.
1. *Uber-jar 옵션*에 표시된 대로 `pom.xml` 파일을 설정합니다. 이 설정을 통해 SDK가 기본적으로 제공하는 `software.amazon.awssdk.crt:aws-crt`의 버전을 확인할 수 있습니다.
1. 프로젝트의 루트(`pom.xml` 파일과 동일한 디렉터리)에서 다음 Maven 명령을 실행합니다.
```
mvn dependency:tree -Dincludes=software.amazon.awssdk.crt:aws-crt
```
Maven은 다른 작업을 수행할 수 있지만, 결국 SDK가 전이적으로 사용하는 `software.amazon.awssdk.crt:aws-crt` 종속성의 콘솔 출력이 표시되어야 합니다. 다음 코드 조각은 `2.29.10`의 SDK 버전을 기반으로 한 샘플 출력을 보여줍니다.
```
[INFO] org.example:yourProject:jar:1.0-SNAPSHOT
[INFO] \- software.amazon.awssdk:aws-crt-client:jar:2.29.10:compile
[INFO] \- software.amazon.awssdk.crt:aws-crt:jar:0.31.3:compile
```
1. 콘솔에 `software.amazon.awssdk.crt:aws-crt` 아티팩트에 대해 표시되는 버전을 사용합니다. 이 경우 `pom.xml` 파일에 `0.31.3`을 추가합니다.
------
## AWS CRT 기반 HTTP 클라이언트 사용 및 구성
서비스 클라이언트 빌드와 함께 AWS CRT 기반 HTTP 클라이언트를 구성하거나 여러 서비스 클라이언트에서 공유하도록 단일 인스턴스를 구성할 수 있습니다.
어느 접근 방식이든 빌더를 사용하여 AWS CRT 기반 HTTP 클라이언트 인스턴스[의 속성을 구성합니다](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.Builder.html).
### 모범 사례: 서비스 클라이언트 전용 인스턴스 지정
AWS CRT 기반 HTTP 클라이언트의 인스턴스를 구성해야 하는 경우 서비스 클라이언트와 함께 빌드하여 인스턴스를 전용으로 사용하는 것이 좋습니다. 서비스 클라이언트 빌더의 `httpClientBuilder` 메서드를 사용하면 됩니다. 이렇게 하면 HTTP 클라이언트의 수명 주기가 SDK에 의해 관리되므로 AWS CRT 기반 HTTP 클라이언트 인스턴스가 더 이상 필요하지 않을 때 닫히지 않을 경우 잠재적인 메모리 누수를 방지할 수 있습니다.
다음 예제에서는 S3 서비스 클라이언트를 생성하고 `connectionTimeout` 및 `maxConcurrency` 값으로 AWS CRT 기반 HTTP 클라이언트를 구성합니다.
------
#### [ Synchronous client ]
**가져오기**
```
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```
**코드**
```
// Singleton: Use s3Client for all requests.
S3Client s3Client = S3Client.builder()
.httpClientBuilder(AwsCrtHttpClient
.builder()
.connectionTimeout(Duration.ofSeconds(3))
.maxConcurrency(100))
.build();
// Perform work with the s3Client.
// Requests completed: Close the s3Client.
s3Client.close();
```
------
#### [ Asynchronous client ]
**가져오기**
```
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import java.time.Duration;
```
**코드**
```
// Singleton: Use s3AsyncClient for all requests.
S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
.httpClientBuilder(AwsCrtAsyncHttpClient
.builder()
.connectionTimeout(Duration.ofSeconds(3))
.maxConcurrency(100))
.build();
// Perform work with the s3AsyncClient.
// Requests completed: Close the s3AsyncClient.
s3AsyncClient.close();
```
------
### 대안 접근 방식: 인스턴스 공유
애플리케이션의 리소스 및 메모리 사용량을 낮게 유지하기 위해 AWS CRT 기반 HTTP 클라이언트를 구성하고 여러 서비스 클라이언트에서 공유할 수 있습니다. HTTP 연결 풀이 공유되므로 리소스 사용량이 줄어듭니다.
**참고**
AWS CRT 기반 HTTP 클라이언트 인스턴스가 공유되면 폐기할 준비가 되면 인스턴스를 닫아야 합니다. SDK는 서비스 클라이언트가 닫힐 때 인스턴스를 닫지 않습니다.
다음 예제에서는 `connectionTimeout` 및 `maxConcurrency` 값을 사용하여 AWS CRT 기반 HTTP 클라이언트 인스턴스를 구성합니다. 구성된 인스턴스는 각 서비스 클라이언트 빌더의 `httpClient` 메서드로 전달됩니다. 서비스 클라이언트와 HTTP 클라이언트가 더 이상 필요하지 않으면 명시적으로 닫힙니다. HTTP 클라이언트가 마지막으로 닫힙니다.
------
#### [ Synchronous client ]
**가져오기**
```
import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```
**코드**
```
// Create an AwsCrtHttpClient shared instance.
SdkHttpClient crtHttpClient = AwsCrtHttpClient.builder()
.connectionTimeout(Duration.ofSeconds(3))
.maxConcurrency(100)
.build();
// Singletons: Use the s3Client and dynamoDbClient for all requests.
S3Client s3Client = S3Client.builder()
.httpClient(crtHttpClient)
.credentialsProvider(EnvironmentVariableCredentialsProvider.crea
.defaultsMode(DefaultsMode.IN_REGION)
.region(Region.US_EAST_1)
.build();
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.httpClient(crtHttpClient)
.credentialsProvider(EnvironmentVariableCredentialsProvider.crea
.defaultsMode(DefaultsMode.IN_REGION)
.region(Region.US_EAST_1)
.build();
// Requests completed: Close all service clients.
s3Client.close();
dynamoDbClient.close();
crtHttpClient.close(); // Explicitly close crtHttpClient.
```
------
#### [ Asynchronous client ]
**가져오기**
```
import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;
import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import java.time.Duration;
```
**코드**
```
// Create an AwsCrtAsyncHttpClient shared instance.
SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder()
.connectionTimeout(Duration.ofSeconds(3))
.maxConcurrency(100)
.build();
// Singletons: Use the s3AsyncClient and dynamoDbAsyncClient for all requests.
S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
.httpClient(crtAsyncHttpClient)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.defaultsMode(DefaultsMode.IN_REGION)
.region(Region.US_EAST_1)
.build();
DynamoDbAsyncClient dynamoDbAsyncClient = DynamoDbAsyncClient.builder()
.httpClient(crtAsyncHttpClient)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.defaultsMode(DefaultsMode.IN_REGION)
.region(Region.US_EAST_1)
.build();
// Requests completed: Close all service clients.
s3AsyncClient.close();
dynamoDbAsyncClient.close();
crtAsyncHttpClient.close(); // Explicitly close crtAsyncHttpClient.
```
------
## AWS CRT 기반 HTTP 클라이언트를 기본값으로 설정
SDK가 AWS CRT 기반 HTTP 클라이언트를 서비스 클라이언트의 기본 HTTP 클라이언트로 사용하도록 Maven 빌드 파일을 설정할 수 있습니다.
이렇게 하려면 각 서비스 클라이언트 아티팩트에 기본 HTTP 클라이언트 종속성이 있는 `exclusions` 요소를 추가하면 됩니다.
다음 `pom.xml` 예제에서 SDK는 S3 서비스에 AWS CRT 기반 HTTP 클라이언트를 사용합니다. 코드의 서비스 클라이언트가 `S3AsyncClient`인 경우, SDK는 `AwsCrtAsyncHttpClient`를 사용합니다. 서비스 클라이언트가 S3Client인 경우 SDK는 `AwsCrtHttpClient`를 사용합니다. 이 설정에서는 기본 Netty 기반 비동기 HTTP 클라이언트와 기본 Apache 기반 동기 HTTP를 사용할 수 없습니다.
```
VERSION
software.amazon.awssdk
s3
${aws.sdk.version}
software.amazon.awssdk
netty-nio-client
software.amazon.awssdk
apache-client
software.amazon.awssdk
aws-crt-client
```
최신 [https://central.sonatype.com/artifact/software.amazon.awssdk/bom](https://central.sonatype.com/artifact/software.amazon.awssdk/bom) 값을 보려면 Maven 중앙 리포지토리를 방문하세요.
**참고**
여러 서비스 클라이언트가 `pom.xml` 파일에 선언되어 있는 경우 모두 `exclusions` XML 요소가 필요합니다.
### Java 시스템 속성 사용
AWS CRT 기반 HTTP 클라이언트를 애플리케이션의 기본 HTTP로 사용하려면 Java 시스템 속성을 `software.amazon.awssdk.http.async.service.impl` 값으로 설정할 수 있습니다`software.amazon.awssdk.http.crt.AwsCrtSdkHttpService`.
애플리케이션 시작 중에 설정하려면 다음과 유사한 명령을 실행하세요.
```
java app.jar -Dsoftware.amazon.awssdk.http.async.service.impl=\
software.amazon.awssdk.http.crt.AwsCrtSdkHttpService
```
다음 코드 조각을 사용하여 애플리케이션 코드에서 시스템 속성을 설정합니다.
```
System.setProperty("software.amazon.awssdk.http.async.service.impl",
"software.amazon.awssdk.http.crt.AwsCrtSdkHttpService");
```
**참고**
시스템 속성을 사용하여 AWS CRT 기반 HTTP 클라이언트 사용을 구성할 때 `poml.xml` 파일의 `aws-crt-client` 아티팩트에 대한 종속성을 추가해야 합니다.
## AWS CRT 기반 HTTP 클라이언트의 고급 구성
연결 상태 구성 및 최대 유휴 시간을 포함하여 AWS CRT 기반 HTTP 클라이언트의 다양한 구성 설정을 사용할 수 있습니다. `AwsCrtAsyncHttpClient`에서 [사용할 수 있는 구성 옵션](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.Builder.html)을 검토할 수 있습니다. `AwsCrtHttpClient`에 사용할 수 있는 구성 옵션을 검토할 수 있습니다.
### 연결 상태 구성
HTTP 클라이언트 빌더의 `connectionHealthConfiguration` 메서드를 사용하여 AWS CRT 기반 HTTP 클라이언트에 대한 연결 상태 구성을 구성할 수 있습니다.
다음 예제에서는 연결 상태 구성과 최대 연결 유휴 시간으로 구성된 AWS CRT 기반 HTTP 클라이언트 인스턴스를 사용하는 S3 서비스 클라이언트를 생성합니다.
------
#### [ Synchronous client ]
**가져오기**
```
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```
**코드**
```
// Singleton: Use the s3Client for all requests.
S3Client s3Client = S3Client.builder()
.httpClientBuilder(AwsCrtHttpClient
.builder()
.connectionHealthConfiguration(builder -> builder
.minimumThroughputInBps(32000L)
.minimumThroughputTimeout(Duration.ofSeconds(3)))
.connectionMaxIdleTime(Duration.ofSeconds(5)))
.build();
// Perform work with s3Client.
// Requests complete: Close the service client.
s3Client.close();
```
------
#### [ Asynchronous client ]
**가져오기**
```
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import java.time.Duration;
```
**코드**
```
// Singleton: Use the s3AsyncClient for all requests.
S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
.httpClientBuilder(AwsCrtAsyncHttpClient
.builder()
.connectionHealthConfiguration(builder -> builder
.minimumThroughputInBps(32000L)
.minimumThroughputTimeout(Duration.ofSeconds(3)))
.connectionMaxIdleTime(Duration.ofSeconds(5)))
.build();
// Perform work with s3AsyncClient.
// Requests complete: Close the service client.
s3AsyncClient.close();
```
------
## HTTP/2 지원
HTTP/2 프로토콜은 아직 AWS CRT 기반 HTTP 클라이언트에서 지원되지 않지만 향후 릴리스에 계획되어 있습니다.
그동안 [KinesisAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kinesis/KinesisAsyncClient.html) 또는 [TranscribeStreamingAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/transcribestreaming/TranscribeStreamingAsyncClient.html)와 같이 HTTP/2 지원이 필요한 서비스 클라이언트를 사용하는 경우 [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)를 대신 사용하는 것이 좋습니다.
## 프록시 구성 예제
다음 코드 조각은 코드에서 프록시 설정을 구성하는 데 사용하는 [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/ProxyConfiguration.Builder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/ProxyConfiguration.Builder.html)의 사용법을 보여줍니다.
------
#### [ Synchronous client ]
**가져오기**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.http.crt.ProxyConfiguration;
```
**코드**
```
SdkHttpClient crtHttpClient = AwsCrtHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.scheme("https")
.host("myproxy")
.port(1234)
.username("username")
.password("password")
.nonProxyHosts(Set.of("localhost", "host.example.com"))
.build())
.build();
```
------
#### [ Asynchronous client ]
**가져오기**
```
import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.http.crt.ProxyConfiguration;
```
**코드**
```
SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.scheme("https")
.host("myproxy")
.port(1234)
.username("username")
.password("password")
.nonProxyHosts(Set.of("localhost", "host.example.com"))
.build())
.build();
```
------
프록시 구성에 해당하는 Java 시스템 속성은 다음 명령줄 코드 조각에 나와 있습니다.
```
$ java -Dhttps.proxyHost=myproxy -Dhttps.proxyPort=1234 -Dhttps.proxyUser=username \
-Dhttps.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App
```
**중요**
HTTPS 프록시 시스템 속성을 사용하려면 코드에서 `scheme` 속성을 `https`로 설정해야 합니다. 스키마 속성이 코드에 설정되지 않은 경우 스키마는 HTTP로 기본 설정되며 SDK는 `http.*` 시스템 속성만 찾습니다.
환경 변수를 사용하는 것과 동등한 설정은 다음과 같습니다.
```
// Set the following environment variables.
// $ export HTTPS_PROXY="https://username:password@myproxy:1234"
// $ export NO_PROXY="localhost|host.example.com"
// Set the 'useSystemPropertyValues' to false on the proxy configuration.
SdkAsyncHttpClient crtAsyncHttpClient = AwsCrtAsyncHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.scheme("https")
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build();
// Run the application.
// $ java -cp ... App
```