기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# AWS SDK for Rust에서 서비스 클라이언트 구성
프로그래밍 방식으로 AWS 서비스에 액세스하기 위해 AWS SDK for Rust는 각 AWS 서비스에 클라이언트 구조를 사용합니다. 예를 들어, 애플리케이션이 Amazon EC2에 액세스해야 하는 경우, 애플리케이션은 Amazon EC2 클라이언트 구조를 생성하여 해당 서비스와 인터페이스합니다. 그런 다음 서비스 클라이언트를 사용하여 요청을 AWS 서비스에 보내면 됩니다.
AWS 서비스에 요청하려면 먼저 서비스 클라이언트를 생성해야 합니다. 코드가 사용하는 각 AWS 서비스에는 고유한 크레이트와 상호 작용을 위한 전용 유형이 있습니다. 클라이언트는 서비스에서 노출되는 각 API 작업에 대해 하나의 메서드를 노출합니다.
SDK 동작을 구성하는 방법은 다양하지만, 궁극적으로 모든 것은 서비스 클라이언트의 동작과 관련이 있습니다. 구성에서 생성된 서비스 클라이언트가 사용될 때까지 해당 구성은 적용되지 않습니다.
AWS 서비스로 개발할 때는 코드가 AWS에서 인증되는 방법을 설정해야 합니다. 사용하려는 AWS 리전도 설정해야 합니다.
[AWS SDK 및 도구 참조 안내서](https://docs.aws.amazon.com/sdkref/latest/guide/)에는 많은 AWS SDK에 공통적인 설정, 기능 및 기타 기본 개념도 포함되어 있습니다.
**Topics**
+ [외부에서 클라이언트 구성](config-external.md)
+ [코드 내 클라이언트 구성](config-code.md)
+ [AWS 리전](region.md)
+ [보안 인증 공급자](credproviders.md)
+ [동작 버전](behavior-versions.md)
+ [재시도](retries.md)
+ [시간 초과](timeouts.md)
+ [관찰성](observability.md)
+ [클라이언트 엔드포인트](endpoints.md)
+ [작업 구성 재정의](peroperation.md)
+ [HTTP](http.md)
+ [인터셉터](interceptors.md)
# 외부에서 AWS SDK for Rust 서비스 클라이언트 구성
코드 외부에서 많은 구성 설정을 처리할 수 있습니다. 구성이 외부에서 처리되면 모든 애플리케이션에 구성이 적용됩니다. 대부분의 구성 설정은 환경 변수로 설정하거나 별도의 공유 AWS `config` 파일로 설정할 수 있습니다. 공유 `config` 파일은 프로파일이라는 별도의 설정 세트를 유지하여 다양한 환경 또는 테스트에서 다양한 구성을 제공할 수 있습니다.
환경 변수와 공유 `config` 파일 설정은 표준화되어 있으며 다양한 프로그래밍 언어와 애플리케이션에서 일관된 기능을 지원하기 위해 AWS SDK 및 도구 전반에 걸쳐 공유됩니다.
이러한 메서드를 통해 애플리케이션을 구성하는 방법과 교차 SDK 설정에 대한 자세한 정보를 알아보려면 *AWS SDK 및 도구 참조 가이드*를 참조하세요. 환경 변수 또는 구성 파일에서 SDK가 확인할 수 있는 모든 설정을 보려면 *AWS SDK 및 도구 참조 가이드*에 나와 있는 [설정 참조](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html)를 참조하세요.
AWS 서비스에 요청하려면 먼저 해당 서비스의 클라이언트를 인스턴스화합니다. 제한 시간, HTTP 클라이언트 및 재시도 구성을 비롯하여 서비스 클라이언트에 대한 공통 설정을 구성할 수 있습니다.
각 서비스 클라이언트에는 AWS 리전 및 자격 증명 공급자가 필요합니다. SDK는 이러한 값을 사용하여 리소스의 올바른 리전으로 요청을 보내고 올바른 자격 증명으로 요청에 서명합니다. 이러한 값은 코드에서 프로그래밍 방식으로 지정하거나 환경에서 자동으로 로드할 수 있습니다.
SDK에는 구성 설정 값을 찾기 위해 확인하는 일련의 위치(또는 소스)가 있습니다.
1. 코드나 서비스 클라이언트 자체에 설정된 모든 명시적 설정은 다른 모든 설정보다 우선합니다.
1. 환경 변수
+ 환경 변수를 설정하는 방법에 대한 자세한 내용은 *AWS SDK 및 도구 참조 가이드*에 나와 있는 [환경 변수](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html) 섹션을 참조하세요.
+ 쉘 환경 변수는 시스템 전체, 사용자 전체, 특정 터미널 세션 등 다양한 수준에서 구성할 수 있습니다.
1. 공유 `config` 및 `credentials` 파일
+ 이 파일 설정에 관한 자세한 정보를 알아보려면 *AWS SDK 및 도구 참조 가이드*에 나와 있는 [공유 `config` 및 `credentials` 파일](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) 섹션을 참조하세요.
1. SDK 소스 코드 자체에서 제공하는 모든 기본값이 마지막에 사용됩니다.
+ 리전과 같은 일부 속성에는 기본값이 없습니다. 코드, 환경 설정 또는 공유 `config` 파일에서 이를 명시적으로 지정해야 합니다. SDK가 필요한 구성을 확인할 수 없는 경우 API 요청이 런타임에 실패할 수 있습니다.
# 코드에서 AWS SDK for Rust 서비스 클라이언트 구성
구성을 코드 내에서 직접 처리할 경우 구성 범위는 해당 코드를 사용하는 애플리케이션으로 제한됩니다. 해당 애플리케이션 내에는 모든 서비스 클라이언트의 글로벌 구성, 특정 AWS 서비스 유형의 모든 클라이언트에 대한 구성 또는 특정 서비스 클라이언트 인스턴스에 대한 구성 옵션이 있습니다.
에 요청하려면 먼저 해당 서비스의 클라이언트를 인스턴스화 AWS 서비스합니다. 제한 시간, HTTP 클라이언트 및 재시도 구성을 비롯하여 서비스 클라이언트에 대한 공통 설정을 구성할 수 있습니다.
각 서비스 클라이언트에는 AWS 리전 및 자격 증명 공급자가 필요합니다. SDK는 이러한 값을 사용하여 리소스의 올바른 리전으로 요청을 보내고 올바른 자격 증명으로 요청에 서명합니다. 이러한 값은 코드에서 프로그래밍 방식으로 지정하거나 환경에서 자동으로 로드할 수 있습니다.
**참고**
서비스 클라이언트는 구성 비용이 많이 들 수 있으며 일반적으로 공유됩니다. 이를 용이하게 하기 위해 모든 `Client` 구문은 `Clone`을 구현합니다.
## 환경에서 클라이언트 구성
환경 기반 구성으로 클라이언트를 생성하려면 `aws-config` 크레이트의 정적 메서드를 사용합니다.
```
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
```
이러한 방식으로 클라이언트를 생성하면 Amazon Elastic Compute Cloud AWS Lambda또는 서비스 클라이언트의 구성을 환경에서 직접 사용할 수 있는 기타 컨텍스트에서 실행할 때 유용합니다. 이렇게 하면 코드를 실행 중인 환경에서 분리하여 코드를 변경 AWS 리전 하지 않고도 애플리케이션을 여러에 더 쉽게 배포할 수 있습니다.
특정 속성을 명시적으로 재정의할 수 있습니다. 명시적 구성은 실행 환경에서 확인된 구성보다 우선합니다. 다음 예제에서는 환경에서 구성을 로드하지만 AWS 리전을 명시적으로 재정의합니다.
```
let config = aws_config::defaults(BehaviorVersion::latest())
.region("us-east-1")
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
```
**참고**
모든 구성 값이 생성 시 클라이언트에 의해 가져오는 것은 아닙니다. 임시 액세스 키 및 IAM Identity Center 구성과 같은 자격 증명 관련 설정은 클라이언트를 사용하여 요청할 때 자격 증명 공급자 계층에 의해 액세스됩니다.
이전 예제에 표시된 `BehaviorVersion::latest()` 코드는 기본값에 사용할 SDK 버전을 나타냅니다. `BehaviorVersion::latest()`는 대부분의 경우에 적합합니다. 자세한 내용은 [에서 동작 버전 사용 AWS SDK for Rust](behavior-versions.md)을 참조하세요.
## 서비스별 설정에 빌더 패턴 사용
특정 서비스 클라이언트 유형에서만 구성할 수 있는 몇 가지 옵션이 있습니다. 그러나 대부분의 경우, 환경에서 대부분의 구성을 로드한 다음 추가 옵션을 구체적으로 추가하는 것이 좋습니다. 빌더 패턴은 AWS SDK for Rust 상자 내의 일반적인 패턴입니다. 먼저 `aws_config::defaults`를 사용하여 일반 구성을 로드한 다음 `from` 메서드를 사용하여 작업 중인 서비스의 빌더에 해당 구성을 로드합니다. 그런 다음 해당 서비스에 대한 고유한 구성 값을 설정하고 `build`를 직접 호출할 수 있습니다. 마지막으로 클라이언트가 이 수정된 구성에서 생성됩니다.
```
// Call a static method on aws-config that sources default config values.
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
// Use the Builder for S3 to create service-specific config from the default config.
let s3_config = aws_sdk_s3::config::Builder::from(&config)
.accelerate(true) // Set an S3-only configuration option
.build();
// Create the client.
let s3 = aws_sdk_s3::Client::from_conf(s3_config);
```
특정 유형의 서비스 클라이언트에 사용할 수 있는 추가 메서드를 검색하는 한 가지 방법은 [https://docs.rs/aws-sdk-s3/latest/aws_sdk_s3/config/struct.Builder.html](https://docs.rs/aws-sdk-s3/latest/aws_sdk_s3/config/struct.Builder.html)와 같은 API 설명서를 활용하는 것입니다.
## 고급 명시적 클라이언트 구성
환경에서 구성을 로드하는 대신 특정 값으로 서비스 클라이언트를 구성하려면 다음과 같이 클라이언트 `Config` 빌더에서 해당 값을 지정할 수 있습니다.
```
let conf = aws_sdk_s3::Config::builder()
.region("us-east-1")
.endpoint_resolver(my_endpoint_resolver)
.build();
let s3 = aws_sdk_s3::Client::from_conf(conf);
```
`aws_sdk_s3::Config::builder()`를 사용하여 서비스 구성을 생성하면 *기본 구성이 로드되지 않습니다*. 기본값은 `aws_config::defaults`를 기반으로 구성을 생성할 때만 로드됩니다.
특정 서비스 클라이언트 유형에서만 구성할 수 있는 몇 가지 옵션이 있습니다. 이전 예제에서는 Amazon S3 클라이언트의 `endpoint_resolver` 함수를 사용하여 이 예제를 보여줍니다.
# 에 AWS 리전 대한 설정 AWS SDK for Rust
를 사용하여 특정 지리적 영역에서 AWS 서비스 작동하는에 액세스할 수 있습니다 AWS 리전. 이는 중복성은 물론, 데이터와 애플리케이션을 고객과 고객의 사용자가 액세스할 위치에 가까운 곳에서 실행 상태로 유지하는 데도 유용할 수 있습니다. 리전을 사용하는 방법에 대한 자세한 내용은 *AWS SDK 및 도구 참조 가이드*의 [AWS 리전](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html)을 참조하세요.
**중요**
대부분의 리소스는 특정에 상주 AWS 리전 하며 SDK를 사용할 때 리소스에 대한 올바른 리전을 제공해야 합니다.
AWS 요청에 AWS 리전 사용할 SDK for Rust의 기본값을 설정해야 합니다. 이 기본값은 리전이 지정되지 않은 모든 SDK 서비스 메서드 직접 호출에 사용됩니다.
공유 AWS `config` 파일 또는 환경 변수를 통해 기본 리전을 설정하는 방법에 대한 예제는 SDK 및 도구 참조 안내서[AWS 리전](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html)의 섹션을 참조하세요. *AWS SDKs *
## AWS 리전 공급자 체인
다음 조회 프로세스는 실행 환경에서 서비스 클라이언트의 구성을 로드할 때 사용됩니다. SDK가 설정되어 있는 첫 번째 값은 클라이언트 구성에 사용됩니다. 서비스 클라이언트 생성에 대한 자세한 내용은 [환경에서 클라이언트 구성](config-code.md#configure-a-client-from-the-environment) 섹션을 참조하세요.
1. 프로그래밍 방식으로 설정된 모든 명시적 리전입니다.
1. `AWS_REGION` 환경 변수를 확인합니다.
+ AWS Lambda 서비스를 사용하는 경우이 환경 변수는 AWS Lambda 컨테이너에 의해 자동으로 설정됩니다.
1. 공유 AWS `config` 파일의 `region` 속성이 확인됩니다.
+ `AWS_CONFIG_FILE` 환경 변수는 공유 `config` 파일의 위치를 변경하는 데 사용할 수 있습니다. 이 파일이 보관되는 위치에 대한 자세한 내용은 *AWS SDK 및 도구 참조 안내서*의 [공유 `config` 및 `credentials` 파일 위치](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html)를 참조하세요.
+ `AWS_PROFILE` 환경 변수를 사용하여 기본값 대신 명명된 프로파일을 선택할 수 있습니다. 여로 프로필 구성에 대한 자세한 내용은 *AWS SDK 및 도구 참조 가이드*의 [공유 `config` 및 `credentials` 파일](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)을 참조하세요.
1. SDK는 Amazon EC2 인스턴스 메타데이터 서비스를 사용하여 현재 실행 중인 Amazon EC2 인스턴스의 리전을 결정합니다.
+ 는 IMDSv2 AWS SDK for Rust 만 지원합니다.
`RegionProviderChain`은 서비스 클라이언트와 함께 사용할 기본 구성을 생성할 때 추가 코드 없이 자동으로 사용됩니다.
```
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
```
## 코드 AWS 리전 에서 설정
### 코드에 명시적으로 리전 설정
리전을 명시적으로 설정하려는 경우 구성에서 직접 `Region::new()`를 사용합니다.
리전 공급자 체인은 사용되지 않습니다. 환경, 공유 `config` 파일 또는 Amazon EC2 인스턴스 메타데이터 서비스를 확인하지 않습니다.
```
use aws_config::{defaults, BehaviorVersion};
use aws_sdk_s3::config::Region;
#[tokio::main]
async fn main() {
let config = defaults(BehaviorVersion::latest())
.region(Region::new("us-west-2"))
.load()
.await;
println!("Using Region: {}", config.region().unwrap());
}
```
에 유효한 문자열을 입력해야 합니다. 제공된 AWS 리전값은 검증되지 않습니다.
### `RegionProviderChain` 사용자 지정
리전을 조건부로 주입하거나, 재정의하거나, 해결 체인을 사용자 지정하려는 경우 [AWS 리전 공급자 체인](#region-provider-chain)을 사용합니다.
```
use aws_config::{defaults, BehaviorVersion};
use aws_config::meta::region::RegionProviderChain;
use aws_sdk_s3::config::Region;
use std::env;
#[tokio::main]
async fn main() {
let region_provider = RegionProviderChain::first_try(env::var("CUSTOM_REGION").ok().map(Region::new))
.or_default_provider()
.or_else(Region::new("us-east-2"));
let config = aws_config::defaults(BehaviorVersion::latest())
.region(region_provider)
.load()
.await;
println!("Using Region: {}", config.region().unwrap());
}
```
이전 구성은 다음과 같습니다.
1. 먼저 `CUSTOM_REGION` 환경 변수에 문자열 세트가 있는지 확인합니다.
1. 사용할 수 없는 경우 기본 리전 공급자 체인으로 돌아갑니다.
1. 실패할 경우 ‘us-east-2’를 최종 폴백으로 사용합니다.
# AWS SDK for Rust 자격 증명 공급자 사용
에 대한 모든 요청은에서 발급한 자격 증명을 사용하여 암호화 방식으로 서명해야 AWS 합니다 AWS. 런타임 시 SDK는 여러 위치를 확인하여 자격 증명의 구성 값을 검색합니다.
검색된 구성에 [AWS IAM Identity Center Single Sign-On 액세스 설정](credentials.md)이 포함된 경우 SDK는 IAM Identity Center와 협력하여 AWS 서비스에 요청하는 데 사용하는 임시 자격 증명을 검색합니다.
검색된 구성에 [임시 자격 증명](https://docs.aws.amazon.com/sdkref/latest/guide/access-temp-idc.html)이 포함된 경우 SDK는 이를 사용하여 AWS 서비스 호출합니다. 임시 자격 증명은 액세스 키와 세션 토큰으로 구성됩니다.
를 사용한 인증은 코드베이스 외부에서 처리할 AWS 수 있습니다. SDK는 자격 증명 공급자 체인을 사용하여 많은 인증 방법을 자동으로 감지하고 사용하며 새로 고칠 수 있습니다.
프로젝트의 AWS 인증을 시작하기 위한 안내 옵션은 *AWS SDKs 및 도구 참조 안내서*의 [인증 및 액세스를](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) 참조하세요.
## 자격 증명 공급자 체인
클라이언트를 구성할 때 자격 증명 공급자를 명시적으로 지정하지 않으면 SDK for Rust가 자격 증명을 제공할 수 있는 일련의 위치를 확인하는 자격 증명 공급자 체인을 사용합니다. SDK가 이러한 위치 중 하나에서 자격 증명을 찾으면 검색이 중지됩니다. 클라이언트 구성에 대한 자세한 내용은 [코드에서 AWS SDK for Rust 서비스 클라이언트 구성](config-code.md) 섹션을 참조하세요.
다음 예제에서는 코드에 자격 증명 공급자를 지정하지 않습니다. SDK는 자격 증명 공급자 체인을 사용하여 호스팅 환경에 설정된 인증을 감지하고 AWS 서비스에 대한 직접 호출에 해당 인증을 사용합니다.
```
let config = aws_config::defaults(BehaviorVersion::latest()).load().await;
let s3 = aws_sdk_s3::Client::new(&config);
```
### 자격 증명 가져오기 순서
자격 증명 공급자 체인은 다음과 같은 사전 정의된 시퀀스를 사용하여 자격 증명을 검색합니다.
1. **액세스 키 환경 변수**
SDK는 `AWS_ACCESS_KEY_ID` 및 `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN` 환경 변수에서 자격 증명을 로드하려고 시도합니다.
1. **공유 AWS `config` 및 `credentials` 파일**
SDK는 공유 AWS `config` 및 `credentials` 파일의 `[default]` 프로필에서 자격 증명을 로드하려고 시도합니다. `AWS_PROFILE` 환경 변수를 사용하여 `[default]`를 사용하는 대신 SDK가 로드할 명명된 프로파일을 선택할 수 있습니다. `config` 및 `credentials` 파일은 다양한 AWS SDKs 및 도구에서 공유됩니다. 이러한 파일에 관한 자세한 정보를 알아보려면 *AWS SDK 및 도구 참조 가이드*에 나와 있는 [공유 `config` 및 `credentials` 파일](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) 섹션을 참조하세요. 프로필에서 지정할 수 있는 표준화된 공급자에 대한 자세한 내용은 [AWS SDKs 및 도구 표준화된 자격 증명 공급자를 참조하세요](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html).
1. **AWS STS 웹 자격 증명**
액세스가 필요한 모바일 애플리케이션 또는 클라이언트 기반 웹 애플리케이션을 생성할 때 AWS AWS Security Token Service (AWS STS)는 퍼블릭 자격 증명 공급자(IdP)를 통해 인증된 페더레이션 사용자를 위한 임시 보안 자격 증명 세트를 반환합니다.
+ 프로필에서 이를 지정하면 SDK 또는 도구가 API 메서드를 사용하여 AWS STS `AssumeRoleWithWebIdentity` 임시 자격 증명을 검색하려고 시도합니다. 이 메서드에 관한 자세한 정보는 *AWS Security Token Service API 참조*의 [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)를 참조하세요.
+ 이 공급자 구성에 대한 지침은 *AWS SDK 및 도구 참조 안내서*의 [웹 자격 증명 또는 OpenID Connect로 페더레이션](https://docs.aws.amazon.com/sdkref/latest/guide/access-assume-role.html#webidentity)을 참조하세요.
+ 이 공급자의 SDK 구성 속성에 대한 자세한 내용은 *AWS SDK 및 도구 참조 안내서*의 [역할 자격 증명 공급자 수임](https://docs.aws.amazon.com/sdkref/latest/guide/feature-assume-role-credentials.html)을 참조하세요.
1. **Amazon ECS 및 Amazon EKS 컨테이너 자격 증명 **
Amazon Elastic Container Service 작업과 Kubernetes 서비스 계정에는 이와 연결된 IAM 역할이 있을 수 있습니다. IAM 역할에서 부여된 권한은 작업에서 실행 중인 컨테이너 또는 포드의 컨테이너에 위임됩니다. 이 역할을 통해 컨테이너에 있는 SDK for Rust 애플리케이션 코드가 다른 AWS 서비스를 사용할 수 있습니다.
SDK는 Amazon ECS 및 Amazon EKS에서 자동으로 설정할 수 있는 `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` 또는 `AWS_CONTAINER_CREDENTIALS_FULL_URI` 환경 변수에서 자격 증명을 검색하려고 시도합니다.
+ Amazon ECS에서 이 역할을 설정하는 방법에 관한 자세한 내용은 *Amazon Elastic Container Service 개발자 안내서*의 [Amazon ECS 작업 IAM 역할](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)을 참조하세요.
+ Amazon EKS 설정 정보는 **Amazon EKS 사용 설명서**의 [Amazon EKS Pod Identity Agent 설정](https://docs.aws.amazon.com/eks/latest/userguide/pod-id-agent-setup.html)을 참조하세요.
+ 이 공급자의 SDK 구성 속성에 대한 자세한 내용은 *AWS SDK 및 도구 참조 안내서*의 [컨테이너 자격 증명 공급자](https://docs.aws.amazon.com/sdkref/latest/guide/feature-container-credentials.html)를 참조하세요.
1. **Amazon EC2 인스턴스 메타데이터 서비스 **
IAM 역할을 생성하여 이를 인스턴스에 연결합니다. 인스턴스의 SDK for Rust 애플리케이션은 인스턴스 메타데이터에서 역할이 제공하는 자격 증명을 검색하려고 시도합니다.
+ SDK for Rust는 [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html)만 지원합니다.
+ 이 역할 설정과 메타데이터 사용에 대한 자세한 내용은 *Amazon EC2 사용 설명서*의 [Amazon EC2용 IAM 역할](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) 및 [인스턴스 메타데이터 작업](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html)에서 확인하세요.
+ 이 공급자의 SDK 구성 속성에 대한 자세한 내용은 *AWS SDK 및 도구 참조 안내서*의 [IMDS 자격 증명 공급자](https://docs.aws.amazon.com/sdkref/latest/guide/feature-imds-credentials.html)를 참조하세요.
1. 이 시점에서 자격 증명이 여전히 확인되지 않으면 오류가 있는 panics 작업입니다.
AWS 자격 증명 공급자 구성 설정에 대한 자세한 내용은 SDK 및 도구 참조 안내서의 *설정 참조*에서 [표준화된 자격 증명 공급자](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html)를 참조하세요. *AWS SDKs *
## 명시적 자격 증명 공급자
자격 증명 공급자 체인을 사용하여 인증 방법을 감지하는 대신 SDK에서 사용해야 하는 특정 자격 증명 공급자를 지정할 수 있습니다. `aws_config::defaults`를 사용하여 일반 구성을 로드할 때 다음과 같이 사용자 지정 자격 증명 공급자를 지정할 수 있습니다.
```
let config = aws_config::defaults(BehaviorVersion::latest())
.credentials_provider(MyCredentialsProvider::new())
.load()
.await;
```
[https://docs.rs/aws-credential-types/latest/aws_credential_types/provider/trait.ProvideCredentials.html](https://docs.rs/aws-credential-types/latest/aws_credential_types/provider/trait.ProvideCredentials.html) 특성을 구현하여 자체 자격 증명 공급자를 구현할 수 있습니다.
## 자격 증명 캐싱
SDK는 자격 증명 및 SSO 토큰과 같은 기타 자격 증명 유형을 캐싱합니다. 기본적으로 SDK는 처음 요청 시 자격 증명을 로드하고 캐싱한 다음 만료될 때 다른 요청 중에 자격 증명을 새로 고치려고 시도하는 지연 캐시 구현을 사용합니다. 동일한 `SdkConfig`에서 생성된 클라이언트는 [https://docs.rs/aws-smithy-runtime/latest/aws_smithy_runtime/client/identity/struct.IdentityCache.html](https://docs.rs/aws-smithy-runtime/latest/aws_smithy_runtime/client/identity/struct.IdentityCache.html)를 공유합니다.
# 에서 동작 버전 사용 AWS SDK for Rust
AWS SDK for Rust 개발자는 언어와 주요 라이브러리가 제공하는 강력하고 예측 가능한 동작을 기대하고 신뢰합니다. SDK for Rust를 사용하는 개발자가 예상 동작을 얻을 수 있도록 하려면 클라이언트 구성에 `BehaviorVersion`이 포함되어 있어야 합니다. `BehaviorVersion`은 기본값이 예상되는 SDK의 버전을 지정합니다. 이렇게 하면 시간이 지남에 따라 SDK가 발전하여 애플리케이션 동작에 예상치 못한 부정적인 영향 없이 새로운 표준에 맞게 모범 사례를 변경하고 새로운 기능을 지원할 수 있습니다.
**주의**
`BehaviorVersion`을 명시적으로 지정하지 않고 SDK를 구성하거나 클라이언트를 생성하려고 하면 생성자가 panic을 수행합니다.
예를 들어 SDK의 새 버전이 새 기본 재시도 정책과 함께 릴리스되었다고 가정해 보겠습니다. 애플리케이션에서 이전 버전의 SDK와 일치하는 `BehaviorVersion`을 사용하는 경우 새 기본 구성 대신 이전 구성이 사용됩니다.
SDK for Rust의 새 동작 버전이 릴리스될 때마다 이전 `BehaviorVersion`에 SDK for Rust `deprecated` 속성이 표시되고 새 버전이 추가됩니다. 이로 인해 컴파일 시 경고가 발생하지만, 그렇지 않으면 빌드가 평소와 같이 계속됩니다. `BehaviorVersion::latest()`도 새 버전의 기본 동작을 나타내도록 업데이트됩니다.
**참고**
코드가 매우 구체적인 동작 특성에 의존하지 않는 경우 코드에서 `BehaviorVersion::latest()`를 사용하거나 `Cargo.toml` 파일의 `behavior-version-latest` 기능 플래그를 사용해야 합니다. 지연 시간에 민감하거나 Rust SDK 동작을 조정하는 코드를 작성하는 경우 `BehaviorVersion`을 특정 메이저 버전에 고정하는 것이 좋습니다.
## `Cargo.toml`에서 동작 버전 설정
`Cargo.toml` 파일에 적절한 기능 플래그를 포함하여 SDK 및 `aws-sdk-s3` 또는 `aws-sdk-iam`과 같은 개별 모듈의 동작 버전을 지정할 수 있습니다. 현재 `Cargo.toml`에서는 SDK의 `latest` 버전만 지원됩니다.
```
[dependencies]
aws-config = { version = "1", features = ["behavior-version-latest"] }
aws-sdk-s3 = { version = "1", features = ["behavior-version-latest"] }
```
## 코드에서 동작 버전 설정
SDK 또는 클라이언트를 구성할 때 코드를 지정하여 필요에 따라 코드로 동작 버전을 변경할 수 있습니다.
```
let config = aws_config::load_defaults(BehaviorVersion::v2023_11_09()).await;
```
이 예제에서는 환경을 사용하여 SDK를 구성하지만 `BehaviorVersion`을 `v2023_11_09()`로 설정하는 구성을 생성합니다.
# AWS SDK for Rust에서 재시도 구성
AWS SDK for Rust는 서비스 요청 및 사용자 지정 가능한 구성 옵션에 대한 기본 재시도 동작을 제공합니다. 를 호출하여 예기치 않은 예외 AWS 서비스 를 가끔 반환합니다. 직접 호출을 재시도하면 스로틀링 또는 일시적 오류와 같은 특정 유형의 오류가 성공할 수 있습니다.
공유 AWS `config` 파일의 환경 변수 또는 설정을 사용하여 전역적으로 재시도 동작을 구성할 수 있습니다. 이 접근법에 대한 정보는 *AWS SDK 및 도구 참조 설명서*의 [재시도 동작](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html)을 참조하세요. 또한 재시도 전략 구현에 대한 자세한 정보와 적절한 구현을 선택하는 방법도 포함되어 있습니다.
또는 다음 섹션과 같이 코드에서 이러한 옵션을 구성할 수도 있습니다.
## 기본 재시도 구성
모든 서비스 클라이언트는 기본적으로 [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html) 구조체를 통해 제공되는 `standard` 재시도 전략 구성을 사용합니다. 기본적으로 직접 호출은 세 번 시도됩니다(*초기 시도와 두 번의 재시도*). 또한 재시도 폭풍을 방지하기 위해 각 재시도는 임의의 짧은 기간을 두고 지연됩니다. 이 규칙은 대부분의 사용 사례에 적합하지만 처리량이 많은 시스템과 같은 특정 상황에서는 적합하지 않을 수 있습니다.
일부 유형의 오류만 SDK에서 재시도 가능한 것으로 간주됩니다. 재시도 가능한 오류의 예는 다음과 같습니다.
+ 소켓 제한 시간
+ 서비스 측 스로틀링
+ HTTP 5XX 응답과 같은 일시적인 서비스 오류
다음 예제는 재시도 가능한 것으로 간주되지 **않습니다**.
+ 파라미터 누락 또는 유효하지 않음
+ 인증/보안 오류
+ 잘못된 구성 예외
최대 시도 횟수, 지연 횟수 및 백오프 구성을 설정하여 `standard` 재시도 전략을 사용자 지정할 수 있습니다.
## 최대 시도 횟수
수정된 [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html)를 `aws_config::defaults`에 제공하여 코드의 최대 시도 횟수를 사용자 지정할 수 있습니다.
```
const CUSTOM_MAX_ATTEMPTS: u32 = 5;
let retry_config = RetryConfig::standard()
// Set max attempts. When max_attempts is 1, there are no retries.
// This value MUST be greater than zero.
// Defaults to 3.
.with_max_attempts(CUSTOM_MAX_ATTEMPTS);
let config = aws_config::defaults(BehaviorVersion::latest())
.retry_config(retry_config)
.load()
.await;
```
## 지연 및 백오프
재시도가 필요한 경우 기본 재시도 전략은 후속 시도를 수행하기 전에 대기합니다. 첫 번째 재시도의 지연 시간은 짧지만 이후 재시도에서는 기하급수적으로 증가합니다. 최대 지연 시간은 너무 크게 증가하지 않도록 제한됩니다.
무작위 지터는 모든 시도 사이의 지연에 적용됩니다. 지터는 재시도 폭풍을 일으킬 수 있는 대규모 플릿의 영향을 완화하는 데 도움이 됩니다. 지수 백오프 및 지터에 대한 자세한 내용은 *AWS 아키텍처 블로그*의 [지수 백오프 및 지터](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/)를 참조하세요.
수정된 [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html)를 `aws_config::defaults`에 제공하여 코드의 지연 설정을 사용자 지정할 수 있습니다. 다음 코드는 첫 번째 재시도를 최대 100밀리초 동안 지연하고 재시도 사이의 최대 시간이 5초가 되도록 구성을 설정합니다.
```
let retry_config = RetryConfig::standard()
// Defaults to 1 second.
.with_initial_backoff(Duration::from_millis(100))
// Defaults to 20 seconds.
.with_max_backoff(Duration::from_secs(5));
let config = aws_config::defaults(BehaviorVersion::latest())
.retry_config(retry_config)
.load()
.await;
```
## 적응형 재시도 모드
`standard` 모드 재시도 전략의 대안으로 `adaptive` 모드 재시도 전략은 스로틀링 오류를 최소화하기 위해 이상적인 요청 속도를 찾는 고급 접근 방식입니다.
**참고**
적응형 재시도는 고급 재시도 모드입니다. 이 전략의 사용은 일반적으로 권장되지 않습니다. *AWS SDK 및 도구 참조 안내서*의 [재시도 동작](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html#standardvsadaptive)을 참조하세요.
적응형 재시도에는 표준 재시도의 모든 기능이 포함됩니다. 비스로틀링 요청과 비교하여 스로틀링 요청의 속도를 측정하는 클라이언트 측 속도 제한 도구를 추가합니다. 또한 트래픽을 제한하여 안전한 대역폭 내에 유지하려는 시도로 스로틀링 오류가 발생하지 않는 것이 이상적입니다.
속도는 변화하는 서비스 조건 및 트래픽 패턴에 실시간으로 적응하며 그에 따라 트래픽 속도를 높이거나 낮출 수 있습니다. 트래픽이 많은 시나리오에서는 속도 제한 도구가 초기 시도를 지연시킬 수 있습니다.
수정된 [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html)를 제공하여 코드에서 `adaptive` 재시도 전략을 선택할 수 있습니다.
```
let config = aws_config::defaults(BehaviorVersion::latest())
.retry_config(RetryConfig::adaptive())
.load()
.await;
```
# AWS SDK for Rust에서 제한 시간 구성
AWS SDK for Rust는 AWS 서비스 요청 제한 시간 및 중지된 데이터 스트림을 관리하기 위한 몇 가지 설정을 제공합니다. 이를 통해 네트워크에서 예기치 않은 지연 및 장애가 발생할 때 애플리케이션이 최적으로 동작할 수 있습니다.
## API 제한 시간
요청 시도가 오래 걸리거나 완전히 실패할 수 있는 일시적인 문제가 있는 경우 애플리케이션이 빠른 실패 후 최적으로 작동할 수 있도록 제한 시간을 검토하고 설정하는 것이 중요합니다. 실패한 요청은 SDK에서 자동으로 재시도될 수 있습니다. 개별 시도와 전체 요청 모두에 대해 제한 시간을 설정하는 것이 좋습니다.
SDK for Rust는 요청에 대한 연결을 설정하기 위한 기본 제한 시간을 제공합니다. SDK에는 요청 시도 또는 전체 요청에 대한 응답을 수신하기 위한 기본 최대 대기 시간이 설정되어 있지 않습니다. 사용 가능한 제한 시간 옵션은 다음과 같습니다.
| 파라미터 | 기본값 | 설명 |
| --- | --- | --- |
| 연결 제한 시간 | 3.1초 | 포기하기 전에 연결을 설정하기 위해 대기하는 최대 시간입니다. |
| 작업 시간 제한 | 없음 | 모든 재시도를 포함하여 SDK for Rust로부터 응답을 받기 전에 대기하는 최대 시간입니다. |
| 작업 시도 제한 시간 | 없음 | 단일 HTTP 시도를 위해 대기하는 최대 시간을 설정합니다. 이 시간이 지나면 API 직접 호출을 재시도할 수 있습니다. |
| 읽기 제한 시간 | 없음 | 요청이 시작된 시점부터 응답의 첫 번째 바이트를 읽기 위해 대기하는 최대 시간입니다. |
다음 예제는 사용자 지정 시간 제한 값을 사용하는 Amazon S3 클라이언트의 구성을 보여줍니다.
```
let config = aws_config::defaults(BehaviorVersion::latest())
.timeout_config(
TimeoutConfig::builder()
.operation_timeout(Duration::from_secs(5))
.operation_attempt_timeout(Duration::from_millis(1500))
.build()
)
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
```
작업 및 시도 제한 시간을 함께 사용하면 재시도 전체에 걸쳐 모든 시도에 소요되는 총 시간에 대한 엄격한 제한을 설정합니다. 또한 느린 요청에 대해 빠르게 실패하도록 개별 HTTP 요청을 설정합니다.
모든 작업에 대해 서비스 클라이언트에서 이러한 제한 시간 값을 설정하는 대신 이를 구성하거나 [단일 요청을 재정의](peroperation.md)할 수 있습니다.
**중요**
SDK for Rust가 응답을 반환한 후 사용된 스트리밍 데이터에는 작업 및 시도 제한 시간이 적용되지 않습니다. 예를 들어 응답의 `ByteStream` 멤버에서 데이터를 사용하는 경우 작업 제한 시간이 적용되지 않습니다.
## 중단된 스트림 보호
SDK for Rust는 중단된 스트림 감지와 관련된 또 다른 형태의 제한 시간을 제공합니다. 중단된 스트림은 구성된 유예 기간보다 오래 데이터를 생성하지 않는 업로드 또는 다운로드 스트림입니다. 이렇게 하면 애플리케이션이 무기한 중단되고 진행되지 않는 것을 방지할 수 있습니다.
스트림 보호가 중단되면 스트림이 허용 기간보다 오래 유휴 상태일 때 오류가 반환됩니다.
기본적으로 SDK for Rust는 업로드와 다운로드 모두에 대해 중단된 스트림 보호를 활성화하고 20초의 충분한 유예 기간으로 최소 1바이트/초의 활동을 찾습니다.
다음 예제에서는 업로드 보호를 비활성화하고 활동 없는 유예 기간을 10초로 변경하는 사용자 지정 `StalledStreamProtectionConfig`를 보여줍니다.
```
let config = aws_config::defaults(BehaviorVersion::latest())
.stalled_stream_protection(
StalledStreamProtectionConfig::enabled()
.upload_enabled(false)
.grace_period(Duration::from_secs(10))
.build()
)
.load()
.await;
```
**주의**
중단된 스트림 보호는 고급 구성 옵션입니다. 애플리케이션에 더 엄격한 성능이 필요하거나 다른 문제가 발생하는 경우에만 이러한 값을 변경하는 것이 좋습니다.
### 중단된 스트림 보호 비활성화
다음 예제에서는 중단된 스트림 보호를 완전히 비활성화하는 방법을 보여줍니다.
```
let config = aws_config::defaults(BehaviorVersion::latest())
.stalled_stream_protection(StalledStreamProtectionConfig::disabled())
.load()
.await;
```
# AWS SDK for Rust에서 관찰성 기능 구성
관찰성은 시스템의 현재 상태를 내보내는 데이터에서 추론할 수 있는 범위입니다. 방출되는 데이터를 일반적으로 원격 측정이라고 합니다.
**Topics**
+ [로깅](logging.md)
# AWS SDK for Rust에서 로깅 구성 및 사용
AWS SDK for Rust는 로깅에 [추적](http://tracing.rs/) 프레임워크를 사용합니다. 로깅을 활성화하려면 `tracing-subscriber` 크레이트를 추가하고 Rust 애플리케이션에서 초기화합니다. 로그에는 타임스탬프, 로그 수준 및 모듈 경로가 포함되어 있어 API 요청 및 SDK 동작을 디버깅하는 데 도움이 됩니다. `RUST_LOG` 환경 변수를 사용하여 필요한 경우 모듈별로 필터링하여 로그 세부 정보를 제어합니다.
## AWS SDK for Rust에서 로깅을 활성화하는 방법
1. 프로젝트 디렉터리에 대한 명령 프롬프트에서 [tracing-subscriber](https://crates.io/crates/tracing-subscriber) 크레이트를 종속성으로 추가합니다.
```
$ cargo add tracing-subscriber --features tracing-subscriber/env-filter
```
이렇게 하면 `[dependencies]` 파일의 `Cargo.toml` 섹션에 크레이트가 추가됩니다.
1. 구독자를 초기화합니다. 일반적으로 SDK for Rust 작업을 직접 호출하기 전에 `main` 함수 초기에 수행됩니다.
```
use aws_config::BehaviorVersion;
type BoxError = Box;
#[tokio::main]
async fn main() -> Result<(), BoxError> {
tracing_subscriber::fmt::init(); // Initialize the subscriber.
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
let _resp = s3.list_buckets()
.send()
.await?;
Ok(())
}
```
1. `RUST_LOG` 환경 변수를 사용하여 로깅을 켭니다. 로깅 정보 표시를 활성화하려면 명령 프롬프트에서 `RUST_LOG` 환경 변수를 로그하려는 수준으로 설정합니다. 다음 예제에서는 로깅을 `debug` 수준으로 설정합니다.
------
#### [ Linux/macOS ]
```
$ RUST_LOG=debug
```
------
#### [ Windows ]
VSCode를 사용하는 경우 터미널 창은 주로 PowerShell로 기본 설정됩니다. 사용 중인 프롬프트 유형을 확인합니다.
```
C:\> set RUST_LOG=debug
```
------
#### [ PowerShell ]
```
PS C:\> $ENV:RUST_LOG="debug"
```
------
1. 프로그램을 실행합니다.
```
$ cargo run
```
콘솔 또는 터미널 창에 추가 출력이 표시됩니다.
자세한 내용은 `tracing-subscriber` 설명서의 [환경 변수를 사용하여 이벤트 필터링](https://docs.rs/tracing-subscriber/0.3.18/tracing_subscriber/fmt/index.html#filtering-events-with-environment-variables)을 참조하세요.
## 로그 출력 해석
이전 섹션의 단계에 따라 로깅을 켜면 기본적으로 추가 로그 정보가 표준으로 인쇄됩니다.
기본 로그 출력 형식(추적 모듈에서 ‘full’이라고 함)을 사용하는 경우 로그 출력에 표시되는 정보는 다음과 같습니다.
```
2024-06-25T16:10:12.367482Z DEBUG invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt:lazy_load_identity: aws_smithy_runtime::client::identity::cache::lazy: identity cache miss occurred; added new identity (took 480.892ms) new_expiration=2024-06-25T23:07:59Z valid_for=25066.632521s partition=IdentityCachePartition(7)
2024-06-25T16:10:12.367602Z DEBUG invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::identity::cache::lazy: loaded identity
2024-06-25T16:10:12.367643Z TRACE invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::orchestrator::auth: resolved identity identity=Identity { data: Credentials {... }, expiration: Some(SystemTime { tv_sec: 1719356879, tv_nsec: 0 }) }
2024-06-25T16:10:12.367695Z TRACE invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::orchestrator::auth: signing request
```
각 항목에는 다음이 포함되어 있습니다.
+ 로그 항목의 타임스탬프.
+ 항목의 로그 수준. `INFO`, `DEBUG` 또는 `TRACE`와 같은 단어입니다.
+ 로그 항목이 생성된 중첩된 [스팬](https://docs.rs/tracing/latest/tracing/span/index.html) 세트로, 콜론(‘:’)으로 구분됩니다. 이렇게 하면 로그 항목의 소스를 식별할 수 있습니다.
+ 로그 항목을 생성한 코드가 포함된 Rust 모듈 경로입니다.
+ 로그 메시지 텍스트입니다.
추적 모듈의 표준 출력 형식은 ANSI 이스케이프 코드를 사용하여 출력을 색상화합니다. 출력을 필터링하거나 검색할 때 이러한 이스케이프 시퀀스를 염두에 두십시오.
**참고**
중첩된 스팬 세트 내에 나타나는 `sdk_invocation_id`는 로그 메시지의 상관관계를 파악하는 데 도움이 되도록 SDK에서 생성한 고유한 ID 클라이언트 측입니다. 이는 AWS 서비스의 응답에 있는 요청 ID와 관련이 없습니다.
## 로깅 수준 미세 조정
`tracing_subscriber`와 같은 환경 필터링을 지원하는 크레이트를 사용하는 경우 모듈별로 로그의 세부 정보를 제어할 수 있습니다.
모든 모듈에 대해 동일한 로깅 수준을 켤 수 있습니다. 다음은 모든 모듈에 대해 로깅 수준을 `trace`로 설정합니다.
```
$ RUST_LOG=trace cargo run
```
특정 모듈에 대해 추적 수준 로깅을 활성화할 수 있습니다. 다음 예제에서는 `aws_smithy_runtime`에서 오는 로그만 `trace` 레벨로 들어옵니다.
```
$ RUST_LOG=aws_smithy_runtime=trace
```
여러 모듈에 대해 쉼표로 구분하여 다른 로그 수준을 지정할 수 있습니다. 다음 예제에서는 `aws_config` 모듈을 `trace` 레벨 로깅으로 설정하고 `aws_smithy_runtime` 모듈을 `debug` 레벨 로깅으로 설정합니다.
```
$ RUST_LOG=aws_config=trace,aws_smithy_runtime=debug cargo run
```
다음 표에서는 로그 메시지를 필터링하는 데 사용할 수 있는 몇 가지 모듈에 대해 설명합니다.
| Prefix | 설명 |
| --- | --- |
| `aws_smithy_runtime` | 요청 및 응답 유선 로깅 |
| `aws_config` | 자격 증명 로딩 |
| `aws_sigv4` | 요청 서명 및 표준 요청 |
로그 출력에 포함해야 하는 모듈을 파악하는 한 가지 방법은 먼저 모든 것을 로그한 다음 필요한 정보를 위해 로그 출력에서 크레이트 이름을 찾는 것입니다. 그런 다음 그에 따라 환경 변수를 설정하고 프로그램을 다시 실행할 수 있습니다.
# 에서 클라이언트 엔드포인트 구성 AWS SDK for Rust
가를 AWS SDK for Rust 호출할 때 첫 번째 단계 AWS 서비스중 하나는 요청을 라우팅할 위치를 결정하는 것입니다. 이 프로세스를 엔드포인트 확인이라고 합니다.
서비스 클라이언트를 생성할 때 SDK에 대한 엔드포인트 확인을 구성할 수 있습니다. 엔드포인트 확인의 기본 구성은 일반적으로 괜찮지만 기본 구성을 수정하려는 몇 가지 이유가 있습니다. 두 가지 이유를 예로 들면 다음과 같습니다.
+ 서비스의 시험판 버전 또는 서비스의 로컬 배포를 요청하기 위해서입니다.
+ SDK에서 아직 모델링되지 않은 특정 서비스 기능에 액세스하기 위해서입니다.
**주의**
엔드포인트 확인은 고급 SDK 주제입니다. 기본 설정을 변경하면 코드가 손상될 위험이 있습니다. 기본 설정은 프로덕션 환경 내 대부분의 사용자에게 적용됩니다.
사용자 지정 엔드포인트는 모든 서비스 요청에 사용되도록 전역적으로 설정하거나 특정에 대해 사용자 지정 엔드포인트를 설정할 수 있습니다 AWS 서비스.
사용자 지정 엔드포인트는 공유 AWS `config` 파일의 환경 변수 또는 설정을 사용하여 구성할 수 있습니다. 이 접근 방식에 대한 자세한 내용은 *AWS SDK 및 도구 참조 안내서*의 [서비스별 엔드포인트](https://docs.aws.amazon.com/sdkref/latest/guide/feature-ss-endpoints.html)를 참조하세요. 모든에 대한 공유 `config` 파일 설정 및 환경 변수의 전체 목록은 서비스별 엔드포인트 식별자를 AWS 서비스참조하세요. [https://docs.aws.amazon.com/sdkref/latest/guide/ss-endpoints-table.html](https://docs.aws.amazon.com/sdkref/latest/guide/ss-endpoints-table.html)
또는 다음 섹션과 같이 코드에서 이 사용자 지정을 구성할 수도 있습니다.
## 사용자 지정 구성
클라이언트를 빌드할 때 사용할 수 있는 두 가지 방법으로 서비스 클라이언트의 엔드포인트 확인을 사용자 지정할 수 있습니다.
1. `endpoint_url(url: Into)`
1. `endpoint_resolver(resolver: impl crate::config::endpoint::ResolveEndpoint + `static)`
두 속성을 모두 설정할 수 있습니다. 그러나 대부분의 경우 하나만 제공하면 됩니다. 일반 사용의 경우 `endpoint_url`이 가장 자주 사용자 지정됩니다.
### 엔드포인트 URL 설정
`endpoint_url`의 값을 설정하여 서비스의 ‘기본’ 호스트 이름을 나타낼 수 있습니다. 그러나 이 값은 클라이언트의 `ResolveEndpoint` 인스턴스에 파라미터로 전달되므로 최종적인 것은 아닙니다. 그러면 `ResolveEndpoint` 구현을 통해 해당 값을 검사하고 잠재적으로 수정하여 최종 엔드포인트를 결정할 수 있습니다.
### 엔드포인트 해석기 설정
서비스 클라이언트의 `ResolveEndpoint` 구현에 따라 SDK가 특정 요청에 사용하는 최종 확인 엔드포인트가 결정됩니다. 서비스 클라이언트는 모든 요청에 대해 `resolve_endpoint` 메서드를 직접 호출하고 더 이상 변경하지 않고 해석기가 반환하는 [https://docs.rs/aws-smithy-runtime-api/latest/aws_smithy_runtime_api/client/endpoint/struct.EndpointFuture.html](https://docs.rs/aws-smithy-runtime-api/latest/aws_smithy_runtime_api/client/endpoint/struct.EndpointFuture.html) 값을 사용합니다.
다음 예제에서는 스테이징 및 프로덕션 등 단계별로 다른 엔드포인트를 확인하는 Amazon S3 클라이언트에 대한 사용자 지정 엔드포인트 해석기 구현을 제공하는 방법을 보여줍니다.
```
use aws_sdk_s3::config::endpoint::{ResolveEndpoint, EndpointFuture, Params, Endpoint};
#[derive(Debug)]
struct StageResolver { stage: String }
impl ResolveEndpoint for StageResolver {
fn resolve_endpoint(&self, params: &Params) -> EndpointFuture<'_> {
let stage = &self.stage;
EndpointFuture::ready(Ok(Endpoint::builder().url(format!("{stage}.myservice.com")).build()))
}
}
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
let resolver = StageResolver { stage: std::env::var("STAGE").unwrap() };
let s3_config = aws_sdk_s3::config::Builder::from(&config)
.endpoint_resolver(resolver)
.build();
let s3 = aws_sdk_s3::Client::from_conf(s3_config);
```
**참고**
엔드포인트 해석기 및 확장을 통해 `ResolveEndpoint` 특성은 각 서비스에 고유하므로 서비스 클라이언트 구성에서만 구성할 수 있습니다. 반면 엔드포인트 URL은 공유 구성을 사용하거나(이에서 파생된 모든 서비스에 적용) 특정 서비스에 대해 구성할 수 있습니다.
#### ResolveEndpoint 파라미터
`resolve_endpoint` 메서드는 엔드포인트 확인에 사용되는 속성을 포함하는 서비스별 파라미터를 허용합니다.
모든 서비스에는 다음 기본 속성이 포함됩니다.
| 이름 | Type | 설명 |
| --- | --- | --- |
| region | 문자열 | 클라이언트의 AWS 리전 |
| endpoint | 문자열 | 값 집합 endpointUrl의 문자열 표현 |
| use\$1fips | 부울 | 클라이언트의 구성에서 FIPS 엔드포인트가 활성화되었는지 여부 |
| use\$1dual\$1stack | 부울 | 클라이언트의 구성에서 듀얼 스택 엔드포인트가 활성화되었는지 여부 |
AWS 서비스 는 확인에 필요한 추가 속성을 지정할 수 있습니다. 예를 들어 Amazon S3 [엔드포인트 파라미터](https://docs.rs/aws-sdk-s3/latest/aws_sdk_s3/config/endpoint/struct.Params.html)에는 버킷 이름과 여러 Amazon S3 전용 기능 설정이 포함됩니다. 예를 들어 `force_path_style` 속성은 가상 호스트 주소 지정을 사용할 수 있는지 여부를 결정합니다.
자체 공급자를 구현하는 경우 엔드포인트 파라미터의 자체 인스턴스를 구성할 필요가 없습니다. SDK는 각 요청에 대한 속성을 제공하고 이를 `resolve_endpoint` 구현에 전달합니다.
### `endpoint_url` 사용과 `endpoint_resolver` 사용의 비교
다음 두 가지 구성, 즉 `endpoint_url`을 사용하는 구성과 `endpoint_resolver`를 사용하는 구성은 동등한 엔드포인트 확인 동작을 가진 클라이언트를 생성하지 않는다는 점을 이해하는 것이 중요합니다.
```
use aws_sdk_s3::config::endpoint::{ResolveEndpoint, EndpointFuture, Params, Endpoint};
#[derive(Debug, Default)]
struct CustomResolver;
impl ResolveEndpoint for CustomResolver {
fn resolve_endpoint(&self, _params: &Params) -> EndpointFuture<'_> {
EndpointFuture::ready(Ok(Endpoint::builder().url("https://endpoint.example").build()))
}
}
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
// use endpoint url
aws_sdk_s3::config::Builder::from(&config)
.endpoint_url("https://endpoint.example")
.build();
// Use endpoint resolver
aws_sdk_s3::config::Builder::from(&config)
.endpoint_resolver(CustomResolver::default())
.build();
```
`endpoint_url`을 설정하는 클라이언트는 엔드포인트 확인의 일부로 수정할 수 있는 (기본) 공급자에게 전달되는 *기본* URL을 지정합니다.
`endpoint_resolver`를 설정하는 클라이언트는 Amazon S3 클라이언트가 사용하는 *최종* URL을 지정합니다.
## 예제
사용자 지정 엔드포인트는 종종 테스트에 사용됩니다. 클라우드 기반 서비스를 직접 호출하는 대신 로컬에서 호스팅되고 시뮬레이션된 서비스로 직접 호출이 라우팅됩니다. 이러한 두 가지 옵션은 다음과 같습니다.
+ [DynamoDB 로컬](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html) – Amazon DynamoDB 서비스의 로컬 버전입니다.
+ [LocalStack](https://github.com/localstack/localstack) - 로컬 시스템의 컨테이너에서 실행되는 클라우드 서비스 에뮬레이터입니다.
다음 예제에서는 이 두 테스트 옵션을 사용할 사용자 지정 엔드포인트를 지정하는 두 가지 방법을 보여줍니다.
### 코드에서 DynamoDB 로컬 직접 사용
이전 섹션에서 설명한 대로 코드에서 직접 `endpoint_url`을 설정하여 로컬 DynamoDB 서버를 가리키도록 기본 엔드포인트를 재정의할 수 있습니다. 코드에서:
```
let config = aws_config::defaults(aws_config::BehaviorVersion::latest())
.test_credentials()
// DynamoDB run locally uses port 8000 by default.
.endpoint_url("http://localhost:8000")
.load()
.await;
let dynamodb_local_config = aws_sdk_dynamodb::config::Builder::from(&config).build();
let client = aws_sdk_dynamodb::Client::from_conf(dynamodb_local_config);
```
[전체 예제](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/dynamodb/src/bin/list-tables-local.rs)는 GitHub에 있습니다.
### `config` 파일을 사용하여 LocalStack 사용
공유 AWS `config` 파일에서 [서비스별 엔드포인트](https://docs.aws.amazon.com/sdkref/latest/guide/feature-ss-endpoints.html)를 설정할 수 있습니다. 다음 구성 프로필은 `4566` 포트에서 `localhost`에 연결할 `endpoint_url`을 설정합니다. LocalStack 구성에 대한 자세한 내용은 *LocalStack 문서* 웹 사이트의 [엔드포인트 URL을 통해 LocalStack 액세스](https://docs.localstack.cloud/references/network-troubleshooting/endpoint-url/)를 참조하세요.
```
[profile localstack]
region=us-east-1
endpoint_url = http://localhost:4566
```
SDK는 공유 `config` 파일의 변경 사항을 선택하여 `localstack` 프로필을 사용할 때 SDK 클라이언트에 적용합니다. 이 접근 방식을 사용하면 코드에 엔드포인트에 대한 참조를 포함할 필요가 없으며, 이는 다음과 같습니다.
```
// set the environment variable `AWS_PROFILE=localstack` when running
// the application to source `endpoint_url` and point the SDK at the
// localstack instance
let config = aws_config::defaults(BehaviorVersion::latest()).load().await;
let s3_config = aws_sdk_s3::config::Builder::from(&config)
.force_path_style(true)
.build();
let s3 = aws_sdk_s3::Client::from_conf(s3_config);
```
[전체 예제](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/localstack)는 GitHub에 있습니다.
# AWS SDK for Rust에서 클라이언트의 단일 작업 구성 재정의
[서비스 클라이언트를 생성](config-code.md)한 후에는 구성을 변경할 수 없으며 모든 후속 작업에 적용됩니다. 이 시점에서는 구성을 수정할 수 없지만 작업별로 재정의할 수 있습니다.
각 작업 빌더에는 기존 구성의 개별 복사본을 재정의할 수 있도록 `CustomizableOperation`을 생성하는 데 사용할 수 있는 `customize` 메서드가 있습니다. 원래 클라이언트 구성은 수정되지 않은 상태로 유지됩니다.
다음 예제는 두 작업을 직접 호출하는 Amazon S3 클라이언트의 생성을 보여줍니다. 두 번째 작업은 다른 AWS 리전으로 전송하도록 재정의됩니다. 모든 Amazon S3의 객체 간접 호출은 수정된 `us-west-2`를 사용하도록 API 직접 호출이 명시적으로 재정의되는 경우를 제외하고 `us-east-1` 리전을 사용합니다.
```
use aws_config::{BehaviorVersion, Region};
let config = aws_config::defaults(BehaviorVersion::latest())
.region("us-east-1")
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
// Request will be sent to "us-east-1"
s3.list_buckets()
.send()
.await?;
// Unset fields default to using the original config value
let modified = aws_sdk_s3::Config::builder()
.region(Region::from_static("us-west-2"));
// Request will be sent to "us-west-2"
s3.list_buckets()
// Creates a CustomizableOperation
.customize()
.config_override(modified)
.send()
.await?;
```
**참고**
이전 예제는 Amazon S3용이지만 개념은 모든 작업에 대해 동일합니다. 특정 작업에는 `CustomizeableOperation`에 대한 추가 메서드가 있을 수 있습니다.
단일 작업에 `customize`를 사용하여 인터셉터를 추가하는 예제는 [특정 작업에 대한 인터셉터](interceptors.md#interceptors-registration-specific) 섹션을 참조하세요.
# AWS SDK for Rust 내에서 HTTP 수준 설정 구성
는 코드에서 생성한 클라이언트가 AWS 서비스 사용하는 내장 HTTP 기능을 AWS SDK for Rust 제공합니다.
기본적으로 SDK for Rust는 `hyper`, `rustls` 및 `aws-lc-rs`를 기반으로 HTTPS 클라이언트를 사용합니다. 이 클라이언트는 추가 구성 없이 대부분의 사용 사례에 적합합니다.
+ [https://docs.rs/hyper/latest/hyper/](https://docs.rs/hyper/latest/hyper/)는와 함께 사용하여 API 서비스를 호출 AWS SDK for Rust 할 수 있는 Rust용 하위 수준 HTTP 라이브러리입니다.
+ [https://github.com/rustls/rustls](https://github.com/rustls/rustls)는 Rust로 작성된 최신 TLS 라이브러리로, 암호화 공급자를 위한 옵션이 내장되어 있습니다.
+ [https://github.com/aws/aws-lc](https://github.com/aws/aws-lc)는 TLS 및 일반 애플리케이션에 필요한 알고리즘을 포함하는 범용 암호화 라이브러리입니다.
+ [https://github.com/aws/aws-lc-rs](https://github.com/aws/aws-lc-rs)는 Rust의 `aws-lc` 라이브러리 주변에 있는 자연스러운 래퍼입니다.
다른 TLS 또는 암호화 공급자를 선택하려는 경우 `aws-smithy-http-client` 크레이트는 몇 가지 추가 옵션과 구성을 제공합니다. 고급 사용 사례의 경우 자체 HTTP 클라이언트 구현을 가져오거나 고려 대상 기능 요청을 제출하는 것이 좋습니다.
## 대체 TLS 공급자 선택
`aws-smithy-http-client` 크레이트는 몇 가지 대체 TLS 공급자를 제공합니다.
다음과 같은 공급자를 사용할 수 있습니다.
**`rustls`가 있는 `aws-lc`**
암호화에 [https://github.com/aws/aws-lc-rs](https://github.com/aws/aws-lc-rs)를 사용하는 [https://github.com/rustls/rustls](https://github.com/rustls/rustls) 기반 TLS 공급자입니다.
이는 SDK for Rust의 기본 HTTP 동작입니다. 이 옵션을 사용하려면 코드에서 추가 작업을 수행할 필요가 없습니다.
**`s2n-tls`**
[https://github.com/aws/s2n-tls](https://github.com/aws/s2n-tls) 기반 TLS 공급자입니다.
**`rustls`가 있는 `aws-lc-fips`**
암호화를 위해 [https://github.com/aws/aws-lc-rs](https://github.com/aws/aws-lc-rs)의 FIPS 호환 버전을 사용하는 [https://github.com/rustls/rustls](https://github.com/rustls/rustls) 기반 TLS 공급자
**`rustls`가 있는 `ring`**
암호화에 [https://github.com/briansmith/ring](https://github.com/briansmith/ring)를 사용하는 [https://github.com/rustls/rustls](https://github.com/rustls/rustls) 기반 TLS 공급자입니다.
### 사전 조건
`aws-lc-rs` 또는 `s2n-tls`를 사용하려면 C 컴파일러(Clang 또는 GCC)를 빌드해야 합니다. 일부 플랫폼의 경우 빌드에 CMake가 필요할 수도 있습니다. 모든 플랫폼에서 ‘fips’ 기능을 사용하여 빌드하려면 CMake 및 Go가 필요합니다. 자세한 내용은 [AWS Libcrypto for Rust(`aws-lc-rs`)](https://github.com/aws/aws-lc-rs/blob/main/aws-lc-rs/README.md) 리포지토리 및 빌드 지침을 참조하세요.
### 대체 TLS 공급자를 사용하는 방법
`aws-smithy-http-client` 크레이트는 추가 TLS 옵션을 제공합니다. AWS 서비스 클라이언트가 다른 TLS 공급자를 사용하려면 `aws_config` 크레이트의 로더를 사용하여 `http_client`를 재정의합니다. HTTP 클라이언트는 AWS 서비스 및 자격 증명 공급자 모두에 사용됩니다.
다음 예제에서는 `s2n-tls` TLS 공급자를 사용하는 방법을 보여줍니다. 그러나 다른 공급자에게도 유사한 접근 방식이 적용됩니다.
예제 코드를 컴파일하려면 다음 명령을 실행하여 프로젝트에 종속성을 추가합니다.
```
cargo add aws-smithy-http-client -F s2n-tls
```
예제 코드:
```
use aws_smithy_http_client::{tls, Builder};
#[tokio::main]
async fn main() {
let http_client = Builder::new()
.tls_provider(tls::Provider::S2nTls)
.build_https();
let sdk_config = aws_config::defaults(
aws_config::BehaviorVersion::latest()
)
.http_client(http_client)
.load()
.await;
// create client(s) using sdk_config
// e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```
## FIPS 지원 활성화
`aws-smithy-http-client` 크레이트는 FIPS 준수 암호화 구현을 활성화하는 옵션을 제공합니다. AWS 서비스 클라이언트가 FIPS 준수 공급자를 사용하려면 `aws_config` 상자의 로더를 `http_client` 사용하여를 재정의합니다. HTTP 클라이언트는 AWS 서비스 및 자격 증명 공급자 모두에 사용됩니다.
**참고**
FIPS 지원에는 빌드 환경에 추가 종속성이 필요합니다. `aws-lc` 크레이트에 대한 [빌드](https://github.com/aws/aws-lc/blob/main/BUILDING.md) 지침을 참조하세요.
예제 코드를 컴파일하려면 다음 명령을 실행하여 프로젝트에 종속성을 추가합니다.
```
cargo add aws-smithy-http-client -F rustls-aws-lc-fips
```
다음 예제 코드는 FIPS 지원을 활성화합니다.
```
// file: main.rs
use aws_smithy_http_client::{
tls::{self, rustls_provider::CryptoMode},
Builder,
};
#[tokio::main]
async fn main() {
let http_client = Builder::new()
.tls_provider(tls::Provider::Rustls(CryptoMode::AwsLcFips))
.build_https();
let sdk_config = aws_config::defaults(
aws_config::BehaviorVersion::latest()
)
.http_client(http_client)
.load()
.await;
// create client(s) using sdk_config
// e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```
## 포스트 퀀텀 키 교환 우선 순위 지정
기본 TLS 공급자는 `X25519MLKEM768` 포스트 퀀텀 키 교환 알고리즘을 지원하는 `rustls`를 사용한 `aws-lc-rs`를 기반으로 합니다. `X25519MLKEM768`을 우선순위가 가장 높은 알고리즘으로 만들려면 `rustls` 패키지를 크레이트에 추가하고 `prefer-post-quantum` 기능 플래그를 활성화해야 합니다. 그렇지 않으면 사용은 가능하지만 우선 순위가 가장 높지는 않습니다. 자세한 내용은 `rustls` [설명서를](https://docs.rs/rustls/0.23.23/rustls/manual/_05_defaults/index.html#about-the-post-quantum-secure-key-exchange-x25519mlkem768) 참조하세요.
**참고**
이는 향후 릴리스에서 기본값이 됩니다.
## DNS 해석기 재정의
HTTP 클라이언트를 수동으로 구성하여 기본 DNS 해석기를 재정의할 수 있습니다.
예제 코드를 컴파일하려면 다음 명령을 실행하여 프로젝트에 종속성을 추가합니다.
```
cargo add aws-smithy-http-client -F rustls-aws-lc
cargo add aws-smithy-runtime-api -F client
```
다음 예제 코드는 DNS 해석기를 재정의합니다.
```
use aws_smithy_http_client::{
tls::{self, rustls_provider::CryptoMode},
Builder
};
use aws_smithy_runtime_api::client::dns::{DnsFuture, ResolveDns};
use std::net::{IpAddr, Ipv4Addr};
/// A DNS resolver that returns a static IP address (127.0.0.1)
#[derive(Debug, Clone)]
struct StaticResolver;
impl ResolveDns for StaticResolver {
fn resolve_dns<'a>(&'a self, _name: &'a str) -> DnsFuture<'a> {
DnsFuture::ready(Ok(vec![IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1))]))
}
}
#[tokio::main]
async fn main() {
let http_client = Builder::new()
.tls_provider(tls::Provider::Rustls(CryptoMode::AwsLc))
.build_with_resolver(StaticResolver);
let sdk_config = aws_config::defaults(
aws_config::BehaviorVersion::latest()
)
.http_client(http_client)
.load()
.await;
// create client(s) using sdk_config
// e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```
**참고**
기본적으로 Amazon Linux 2023(AL2023)은 운영 체제 수준에서 DNS를 캐싱하지 않습니다.
## 루트 CA 인증서 사용자 지정
기본적으로 TLS 공급자는 지정된 플랫폼에 대한 시스템 네이티브 루트 인증서를 로드합니다. 사용자 지정 CA 번들을 로드하도록 이 동작을 사용자 지정하려면 자체 `TrustStore`로 `TlsContext`를 구성할 수 있습니다.
예제 코드를 컴파일하려면 다음 명령을 실행하여 프로젝트에 종속성을 추가합니다.
```
cargo add aws-smithy-http-client -F rustls-aws-lc
```
다음 예제에서는 `rustls`를 `aws-lc`와 함께 사용하지만 지원되는 모든 TLS 공급자에 대해 작동합니다.
```
use aws_smithy_http_client::{
tls::{self, rustls_provider::CryptoMode},
Builder
};
use std::fs;
/// read the PEM encoded root CA (bundle) and return a custom TLS context
fn tls_context_from_pem(filename: &str) -> tls::TlsContext {
let pem_contents = fs::read(filename).unwrap();
// Create a new empty trust store (this will not load platform native certificates)
let trust_store = tls::TrustStore::empty()
.with_pem_certificate(pem_contents.as_slice());
tls::TlsContext::builder()
.with_trust_store(trust_store)
.build()
.expect("valid TLS config")
}
#[tokio::main]
async fn main() {
let http_client = Builder::new()
.tls_provider(tls::Provider::Rustls(CryptoMode::AwsLc))
.tls_context(tls_context_from_pem("my-custom-ca.pem"))
.build_https();
let sdk_config = aws_config::defaults(
aws_config::BehaviorVersion::latest()
)
.http_client(http_client)
.load()
.await;
// create client(s) using sdk_config
// e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```
# AWS SDK for Rust에서 인터셉터 구성
인터셉터를 사용하여 API 요청 및 응답 실행에 연결할 수 있습니다. 인터셉터는 SDK가 요청/응답 수명 주기에 동작을 주입하기 위해 작성하는 코드를 직접 호출하는 개방형 메커니즘입니다. 이 방법으로 진행 중인 요청 수정, 요청 처리 디버그, 오류 보기 등의 작업을 수행할 수 있습니다.
다음 예제는 재시도 루프가 입력되기 전에 모든 발신 요청에 헤더를 추가하는 간단한 인터셉터를 보여줍니다.
```
use std::borrow::Cow;
use aws_smithy_runtime_api::client::interceptors::{
Intercept,
context::BeforeTransmitInterceptorContextMut,
};
use aws_smithy_runtime_api::client::runtime_components::RuntimeComponents;
use aws_smithy_types::config_bag::ConfigBag;
use aws_smithy_runtime_api::box_error::BoxError;
#[derive(Debug)]
struct AddHeaderInterceptor {
key: Cow<'static, str>,
value: Cow<'static, str>,
}
impl AddHeaderInterceptor {
fn new(key: &'static str, value: &'static str) -> Self {
Self {
key: Cow::Borrowed(key),
value: Cow::Borrowed(value),
}
}
}
impl Intercept for AddHeaderInterceptor {
fn name(&self) -> &'static str {
"AddHeader"
}
fn modify_before_retry_loop(
&self,
context: &mut BeforeTransmitInterceptorContextMut<'_>,
_runtime_components: &RuntimeComponents,
_cfg: &mut ConfigBag,
) -> Result<(), BoxError> {
let headers = context.request_mut().headers_mut();
headers.insert(self.key.clone(), self.value.clone());
Ok(())
}
}
```
자세한 내용과 사용 가능한 인터셉터 후크는 [인터셉트](https://docs.rs/aws-smithy-runtime-api/latest/aws_smithy_runtime_api/client/interceptors/trait.Intercept.html) 특성을 참조하세요.
## 인터셉터 등록
서비스 클라이언트를 구성하거나 특정 작업에 대한 구성을 재정의할 때 인터셉터를 등록합니다. 등록은 인터셉터를 클라이언트의 모든 작업에 적용할지 아니면 특정 작업에만 적용할지에 따라 달라집니다.
### 서비스 클라이언트의 모든 작업에 대한 인터셉터
전체 클라이언트에 대한 인터셉터를 등록하려면 `Builder` 패턴을 사용하여 인터셉터를 추가합니다.
```
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
// All service operations invoked using 's3' will have the header added.
let s3_conf = aws_sdk_s3::config::Builder::from(&config)
.interceptor(AddHeaderInterceptor::new("x-foo-version", "2.7"))
.build();
let s3 = aws_sdk_s3::Client::from_conf(s3_conf);
```
### 특정 작업에 대한 인터셉터
단일 작업에 대해서만 인터셉터를 등록하려면 `customize` 확장을 사용합니다. 이 방법을 사용하여 작업별 수준에서 서비스 클라이언트 구성을 재정의할 수 있습니다. 사용자 지정 가능한 작업에 대한 자세한 내용은 [AWS SDK for Rust에서 클라이언트의 단일 작업 구성 재정의](peroperation.md) 섹션을 참조하세요.
```
// Only the list_buckets operation will have the header added.
s3.list_buckets()
.customize()
.interceptor(AddHeaderInterceptor::new("x-bar-version", "3.7"))
.send()
.await?;
```