코드에서 AWS SDK for C++ 서비스 클라이언트 구성

구성을 코드 내에서 직접 처리할 경우 구성 범위는 해당 코드를 사용하는 애플리케이션으로 제한됩니다. 해당 애플리케이션 내에는 모든 서비스 클라이언트의 글로벌 구성, 특정 AWS 서비스 유형의 모든 클라이언트에 대한 구성 또는 특정 서비스 클라이언트 인스턴스에 대한 구성에 대한 옵션이 있습니다.

AWS SDK for C++에는 애플리케이션에서 사용하는 AWS 서비스와 상호 작용하는 기능을 제공하는 AWS 서비스 클라이언트 클래스가 포함되어 있습니다. SDK for C++에서는 기본 클라이언트 구성을 변경할 수 있으며, 이는 다음과 같은 작업을 수행할 때 유용합니다.

프록시를 통해 인터넷에 연결
연결 제한 시간 및 요청 재시도 등 HTTP 전송 설정 변경
TCP 소켓 버퍼 크기 힌트 지정

ClientConfiguration는 코드에서 인스턴스화하고 활용할 수 있는 SDK for C++의 구조입니다. 다음 스니펫은 이 클래스를 사용하여 프록시를 통해 Amazon S3에 액세스하는 방법을 보여줍니다.


Aws::Client::ClientConfiguration clientConfig;
clientConfig.proxyHost = "localhost";
clientConfig.proxyPort = 1234;
clientConfig.proxyScheme = Aws::Http::Scheme::HTTPS;
Aws::S3::S3Client(clientConfig);

구성 변수 선언

ClientConfiguration 구조체는 다음과 같이 멤버 변수를 선언합니다.


Aws::String accountId;
Aws::String accountIdEndpointMode = "preferred";
bool allowSystemProxy = false;
Aws::String appId;
Aws::String caPath;
Aws::String caFile;

struct {
  RequestChecksumCalculation requestChecksumCalculation = RequestChecksumCalculation::WHEN_SUPPORTED;
  ResponseChecksumValidation responseChecksumValidation = ResponseChecksumValidation::WHEN_SUPPORTED;
} checksumConfig;

ProviderFactories configFactories = ProviderFactories::defaultFactories;
long connectTimeoutMs = 1000;

struct CredentialProviderConfiguration {
    Aws::String profile;
    Aws::String region;
    struct {
        long metadataServiceNumAttempts = 1;
        long metadataServiceTimeout = 1;
        std::shared_ptr<RetryStrategy> imdsRetryStrategy;
        bool disableImdsV1;
        bool disableImds;
    } imdsConfig;
    struct STSCredentialsCredentialProviderConfiguration {
        Aws::String roleArn;
        Aws::String sessionName;
        Aws::String tokenFilePath;
        std::chrono::milliseconds retrieveCredentialsFutureTimeout = std::chrono::seconds(10);
    } stsCredentialsProviderConfig;
} credentialProviderConfig;

bool disableExpectHeader = false;
bool disableIMDS = false;
bool disableImdsV1 = false;
bool enableClockSkewAdjustment = true;
Aws::Crt::Optional<bool> enableEndpointDiscovery;
bool enableHostPrefixInjection = true;
bool enableHttpClientTrace = false;
bool enableTcpKeepAlive = true;
Aws::String endpointOverride;
std::shared_ptr<Aws::Utils::Threading::Executor> executor = nullptr;
FollowRedirectsPolicy followRedirects;
Aws::Http::TransferLibType httpLibOverride;
Aws::Http::TransferLibPerformanceMode httpLibPerfMode = Http::TransferLibPerformanceMode::LOW_LATENCY;
long httpRequestTimeoutMs = 0;
unsigned long lowSpeedLimit = 1;
unsigned maxConnections = 25;
Aws::Utils::Array<Aws::String> nonProxyHosts;
Aws::String profileName;
Aws::String proxyCaFile;
Aws::String proxyCaPath;
Aws::Http::Scheme proxyScheme;
Aws::String proxyHost;
unsigned proxyPort = 0;
Aws::String proxyUserName;
Aws::String proxyPassword;
Aws::String proxySSLCertPath;
Aws::String proxySSLCertType;
Aws::String proxySSLKeyPath;
Aws::String proxySSLKeyType;
Aws::String proxySSLKeyPassword;
std::shared_ptr<Aws::Utils::RateLimits::RateLimiterInterface> readRateLimiter = nullptr;
Aws::String region;
Aws::Client::RequestCompressionConfig requestCompressionConfig;
long requestTimeoutMs = 0;
std::shared_ptr<RetryStrategy> retryStrategy = nullptr;
Aws::Http::Scheme scheme;
unsigned long tcpKeepAliveIntervalMs = 30000;
std::shared_ptr<smithy::components::tracing::TelemetryProvider> telemetryProvider;
Aws::String userAgent;
bool useDualStack = false;
bool useFIPS = false;
bool verifySSL = true;
Aws::Http::Version version = Http::Version::HTTP_VERSION_2TLS;

struct WinHTTPOptions {
  bool useAnonymousAuth = false;
} winHTTPOptions;

std::shared_ptr<Aws::Utils::RateLimits::RateLimiterInterface> writeRateLimiter = nullptr;

static Aws::String LoadConfigFromEnvOrProfile(const Aws::String& envKey, const Aws::String& profile,
                                              const Aws::String& profileProperty, const Aws::Vector<Aws::String>& allowedValues,
                                              const Aws::String& defaultValue);

구성 변수 설명

다음 목록은 클라이언트 동작을 사용자 지정하는 데 사용할 수 있는 ClientConfiguration 멤버 변수를 설명합니다.

accountId: 계정 기반 엔드포인트 라우팅의 AWS 계정 ID를 지정합니다. 111122223333 형식을 사용합니다. 계정 기반 엔드포인트 라우팅을 사용하면 일부 서비스의 요청 성능이 향상됩니다.
accountIdEndpointMode: 계정 기반 엔드포인트 라우팅 동작을 제어합니다. 유효한 값은 "required", "disabled", "preferred" 중 하나입니다. 기본값은 "preferred"입니다. 필요한 경우 계정 기반 엔드포인트 라우팅을 끄려면 "disabled"로 설정합니다.
allowSystemProxy: HTTP 클라이언트에서 시스템 프록시 설정을 검색할지 여부를 제어합니다. 기본 설정은 false입니다. 자동 프록시 검색을 활성화하려면 true로 설정합니다.
appId: 애플리케이션별 식별자(선택 사항)를 지정합니다. 설정할 경우 이 값이User-Agent 헤더에 App/{appId} 형식으로 추가됩니다. 이 값은 AWS_SDK_UA_APP_ID 환경 변수 또는 sdk_ua_app_id 공유 구성 프로필 속성을 사용하여 설정할 수 있습니다.
caPath, caFile: HTTP 클라이언트에 SSL 인증서 트러스트 스토어를 찾을 위치를 지시합니다. 예제 트러스트 스토어는 OpenSSL c_rehash 유틸리티로 준비된 디렉터리일 수 있습니다. 환경에서 symlink를 사용하지 않는 한 이러한 변수를 설정할 필요가 없습니다. Windows 및 macOS 시스템에서는 이 변수들이 아무런 영향을 미치지 않습니다.
checksumConfig: 체크섬 계산 및 검증 설정을 포함합니다. requestChecksumCalculation 및 responseChecksumValidation으로 구성되며 기본값은 WHEN_SUPPORTED입니다.
configFactories: 클라이언트 유틸리티 클래스(Executor 및 RetryStrategy)를 초기화하기 위한 팩토리 메서드를 지정합니다. 재정의하지 않는 한 기본 팩토리가 사용됩니다.
requestTimeoutMs 및 connectTimeoutMs: HTTP 요청의 제한 시간까지 대기할 시간(밀리초)을 지정합니다. 예를 들어, 대용량 파일을 전송할 경우에는 이 시간을 늘리는 것이 좋습니다.
credentialProviderConfig: 자격 증명 공급자에 대한 구성 설정을 포함합니다. 이 구조를 사용하여 SDK에서 AWS 자격 증명을 얻는 방법을 사용자 지정합니다.
disableExpectHeader: CURL HTTP 클라이언트에만 적용됩니다. 기본적으로 CURL은 HTTP 헤더 수신 직후 서버가 오류로 응답하는 상황에서 HTTP 페이로드 전송을 방지하기 위해 HTTP 요청에 “Expect: 100-Continue” 헤더를 추가합니다. 이 동작으로 왕복 통신을 절약할 수 있으며 페이로드가 작고 네트워크 지연 시간이 우려되는 상황에서 유용합니다. 이 변수의 기본 설정은 false입니다. true로 설정하면 CURL에 HTTP 요청 헤더와 본문 페이로드를 모두 함께 전송하도록 지시합니다.
disableIMDS: 인스턴스 메타데이터 서비스(IMDS) 호출을 비활성화할지 여부를 제어합니다. 기본 설정은 false입니다. EC2 인스턴스 외부에서 실행될 때 IMDS 호출을 비활성화하려면 true로 설정합니다.
disableImdsV1: IMDSv2 호출은 허용하면서 IMDSv1 호출을 비활성화할지 여부를 제어합니다. 기본 설정은 false입니다. 보안 강화를 위해 IMDSv1 호출만 비활성화하려면 true로 설정합니다.
enableClockSkewAdjustment: 매 HTTP 시도 후 클록 스큐를 조정할지 여부를 제어합니다. 기본 설정은 false입니다.
enableEndpointDiscovery: 엔드포인트 검색 사용 여부를 제어합니다. 기본적으로 리전 엔드포인트 또는 재정의된 엔드포인트가 사용됩니다. 엔드포인트 검색을 활성화하려면 이 변수를 true로 설정합니다.
enableHostPrefixInjection: HTTP 호스트가 DiscoverInstances 요청에 "data-" 접두사를 추가할지 여부를 제어합니다. 기본적으로 이 동작은 활성화되어 있습니다. 비활성화하려면 이 변수를 false로 설정합니다.
enableHttpClientTrace: 디버깅을 위해 HTTP 클라이언트 추적을 활성화할지 여부를 제어합니다. 기본 설정은 false입니다. 자세한 HTTP 요청 및 응답 로깅을 활성화하려면 true로 설정합니다.
enableTcpKeepAlive: TCP 연결 유지 패킷을 전송할지 여부를 제어합니다. 기본 설정은 true입니다. tcpKeepAliveIntervalMs 변수와 함께 사용합니다. WinINet 및 IXMLHTTPRequest2 클라이언트에는 이 변수를 적용할 수 없습니다.
endpointOverride: 서비스와 통신할 때 사용할 재정의 HTTP 엔드포인트를 지정합니다.
executor: 비동기식 Executor 핸들러의 구현을 참조합니다. 기본 동작은 각 비동기 호출마다 스레드를 생성하고 분리하는 것입니다. 이 동작을 변경하려면 Executor 클래스의 하위 클래스를 구현하고 해당 인스턴스를 이 변수에 할당합니다.
followRedirects: HTTP 300 리디렉션 코드 처리 시 동작을 제어합니다.
httpLibOverride: 기본 HTTP 팩토리에서 반환하는 HTTP 구현을 지정합니다. Windows의 기본 HTTP 클라이언트는 WinHTTP입니다. 다른 모든 플랫폼의 기본 HTTP 클라이언트는 CURL입니다.
httpLibPerfMode: HTTP 라이브러리 성능 모드를 지정합니다. 기본 설정은 LOW_LATENCY입니다. 이 설정을 조정하여 다양한 성능 특성에 맞게 최적화할 수 있습니다.
httpRequestTimeoutMs: HTTP 요청 제한 시간(밀리초)을 지정합니다. 기본값은 0(제한 시간 없음)입니다. 대용량 파일을 전송할 경우에는 이 값을 늘리는 것이 좋습니다.
lowSpeedLimit: 허용되는 최소 전송 속도(바이트/초)를 지정합니다. 전송 속도가 지정된 속도 아래로 떨어지면 전송 작업이 중단됩니다. 기본 설정은 1바이트/초입니다. 이 변수는 CURL 클라이언트에만 적용됩니다.
maxConnections: 단일 서버에 대한 최대 HTTP 연결 수를 지정합니다. 기본값은 25입니다. 대역폭이 합리적으로 지원하는 범위 외에는 허용되는 최대값이 없습니다.
nonProxyHosts: 프록시 설정을 우회해야 하는 호스트 이름 배열을 지정합니다. 프록시 구성에서 특정 호스트를 제외하려면 이 설정을 사용합니다.
profileName: 구성에 사용할 AWS 프로필 이름을 지정합니다. SDK는 AWS 구성 파일의 지정된 프로필에서 설정을 로드합니다.
proxyCaFile: 기본값과 다른 경우 프록시 연결용 인증 기관 파일의 경로를 지정합니다.
proxyCaPath: 기본값과 다른 경우 프록시 연결용 인증 기관 트러스트 스토어의 경로를 지정합니다.
proxyScheme, proxyHost, proxyPort, proxyUserName 및 proxyPassword: AWS와의 모든 통신에 대한 프록시를 설정하고 구성하는 데 사용됩니다. 이 기능이 유용할 수 있는 예시로는 Burp Suite와 함께 디버깅을 수행하거나, 프록시를 사용하여 인터넷에 연결하는 경우가 있습니다.
proxySSLCertPath: 클라이언트 인증서가 필요한 프록시 연결용 SSL 인증서 파일의 경로를 지정합니다.
proxySSLCertType: 프록시 연결에 사용할 SSL 인증서 유형을 지정합니다. 일반적인 유형으로는 PEM과 DER이 있습니다.
proxySSLKeyPassword: 키가 암호로 보호된 경우 프록시 연결에 사용되는 SSL 프라이빗 키의 암호를 지정합니다.
proxySSLKeyPath: 클라이언트 인증서가 필요한 프록시 연결용 SSL 프라이빗 키 파일의 경로를 지정합니다.
proxySSLKeyType: 프록시 연결에 사용할 SSL 프라이빗 키 유형을 지정합니다. 일반적인 유형으로는 PEM과 DER이 있습니다.
writeRateLimiter 및 readRateLimiter: 전송 계층에서 사용하는 대역폭을 스로틀링하는 데 사용되는 읽기 및 쓰기 속도 제한기 구현에 대한 참조입니다. 기본적으로 읽기 및 쓰기 속도는 스로틀링되지 않습니다. 스로틀링을 도입하려면 RateLimiterInterface의 하위 클래스를 구현하고 해당 인스턴스를 이 변수에 할당합니다.
region: 사용할 AWS 리전을 지정합니다(예: us-east-1). 기본적으로 사용되는 리전은 해당 AWS 자격 증명에 구성된 기본 리전입니다.
requestCompressionConfig: 요청 압축에 대한 구성 설정을 포함합니다. 이 구조를 사용하여 전송 전에 요청이 압축되는 시기와 방식을 제어합니다.
retryStrategy: 재시도 전략의 구현을 참조합니다. 기본 전략은 지수 백오프 정책을 구현합니다. 다른 전략을 수행하려면 RetryStrategy 클래스의 하위 클래스를 구현하고 해당 인스턴스를 이 변수에 할당합니다.
scheme: URI 주소 지정 체계를 HTTP 또는 HTTPS로 지정합니다. 기본 체계는 HTTPS입니다.
tcpKeepAliveIntervalMs: TCP 연결을 통해 연결 유지 패킷을 전송할 시간 간격(밀리초)을 지정합니다. 기본 간격은 30초입니다. 최소 설정은 15초입니다. WinINet 및 IXMLHTTPRequest2 클라이언트에는 이 변수를 적용할 수 없습니다.
telemetryProvider: 지표 및 추적 데이터를 수집하기 위한 원격 측정 공급자 구현을 참조합니다. 관찰성 특성을 활성화하려면 이 설정을 구성합니다.
userAgent: 내부용입니다. 이 변수의 설정은 변경하지 않습니다.
useDualStack: 듀얼 스택 IPv4 및 IPv6 엔드포인트를 사용할지 여부를 제어합니다. 모든 AWS 서비스가 모든 리전에서 IPv6를 지원하는 것은 아닙니다.
useFIPS: Federal Information Processing Standards(FIPS) 140-2로 검증된 암호화 모듈을 사용할지 여부를 제어합니다. 기본 설정은 false입니다. FIPS 규정 준수가 필요한 경우 true로 설정합니다.
verifySSL: SSL 인증서 확인 여부를 제어합니다. 기본적으로 SSL 인증서를 확인합니다. 확인을 비활성화하려면 변수를 false로 설정합니다.
version: 요청에 사용할 HTTP 버전을 지정합니다. 기본 설정은 HTTP_VERSION_2TLS(TLS를 통한 HTTP/2)입니다.
winHTTPOptions: Windows별 HTTP 구성 옵션을 포함합니다. 기본 설정이 false인 useAnonymousAuth를 포함합니다.

javascript가 브라우저에서 비활성화되거나 사용이 불가합니다.

AWS 설명서를 사용하려면 Javascript가 활성화되어야 합니다. 지침을 보려면 브라우저의 도움말 페이지를 참조하십시오.

문서 규칙

외부에서 클라이언트 구성

AWS 리전