コード内での AWS SDK for C++ サービスクライアントの設定 - AWS SDK for C++
宣言説明

コード内での 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

SSL 証明書の信頼ストアの場所を HTTP クライアントに指示します。信頼ストアの例は、OpenSSL c_rehash ユーティリティで準備されたディレクトリです。シンボリックリンクを使用している環境でない限り、これらの変数を設定する必要はありません。これらの変数は Windows および macOS システムでは効果がありません。

checksumConfig

チェックサムの計算と検証の設定が含まれます。requestChecksumCalculation および responseChecksumValidation が含まれ、デフォルト値は WHEN_SUPPORTED です。

configFactories

Executor や RetryStrategy などのクライアントユーティリティクラスを初期化するためのファクトリメソッドを指定します。オーバーライドされない限り、デフォルトのファクトリが使用されます。

requestTimeoutMs および connectTimeoutMs

HTTP リクエストがタイムアウトするまでの待機時間をミリ秒単位で指定します。例えば、大きなファイルを転送する際には、これらの値を増やすことを検討してください。

credentialProviderConfig

認証情報プロバイダーの設定が含まれます。この構造を使用して、SDK が AWS 認証情報を取得する方法をカスタマイズします。

disableExpectHeader

CURL HTTP クライアントにのみ適用されます。デフォルトでは、CURL は HTTP リクエストに「Expect: 100-Continue」ヘッダーを追加します。これは、ヘッダー受信直後にサーバーがエラーを返すような状況で、HTTP ペイロードが送信されるのを防ぐためです。この動作により、ラウンドトリップが節約され、ペイロードが小さくネットワークレイテンシーが影響する場合に有効です。この変数のデフォルト設定は 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 クラスのサブクラスを実装し、そのインスタンスをこの変数に割り当てます。

followRedirects

HTTP 300 番台のリダイレクトコードを処理する際の動作を制御します。

httpLibOverride

デフォルトの HTTP ファクトリから返される HTTP 実装を指定します。Windows のデフォルトの HTTP クライアントは WinHTTP です。他のすべてのプラットフォームのデフォルトの HTTP クライアントは CURL です。

httpLibPerfMode

HTTP ライブラリのパフォーマンスモードを指定します。デフォルト設定は LOW_LATENCY です。さまざまなパフォーマンス特性に合わせた最適化のために、この設定を調整できます。

httpRequestTimeoutMs

HTTP リクエストのタイムアウトをミリ秒単位で指定します。デフォルト値は 0 (タイムアウトなし) です。大きなファイルを転送する際は、この値を増やすことを検討してください。

lowSpeedLimit

許可される最小転送速度をバイト/秒単位で指定します。転送速度が指定された速度を下回ると、転送オペレーションは中止されます。デフォルト設定は 1 バイト/秒です。この変数は CURL クライアントにのみ適用されます。

maxConnections

1 つのサーバーへの HTTP 接続の最大数を指定します。デフォルト値は 25 です。許容される最大値は明示されていませんが、利用している帯域幅で無理なく対応できる範囲にとどめる必要があります。

nonProxyHosts

プロキシ設定をバイパスするホスト名の配列を指定します。この設定を使用して、プロキシ設定から特定のホストを除外します。

profileName

設定に使用する AWS プロファイル名を指定します。SDK は、AWS 設定ファイルの指定されたプロファイルから設定をロードします。

proxyCaFile

プロキシ接続に使用する認証局ファイルへのパスが、デフォルトと異なる場合に、そのパスを指定します。

proxyCaPath

プロキシ接続時に使用する認証局トラストストアへのパスが、デフォルトと異なる場合に、そのパスを指定します。

proxyScheme、proxyHost、proxyPort、proxyUserName、proxyPassword

AWS とのすべての通信用のプロキシを設定するために使用されます。Burp スイートと組み合わせてデバッグする場合や、インターネット接続にプロキシを使用する場合などに便利です。

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

連邦情報処理標準 (FIPS) 140-2 検証済みの暗号化モジュールを使用するかどうかを制御します。デフォルト設定は false です。FIPS 準拠が必要な場合は true に設定します。

verifySSL

SSL 証明書を検証するかどうかを制御します。デフォルトでは、SSL 証明書は検証されます。検証を無効にするには、変数を false に設定します。

version

リクエストに使用する HTTP バージョンを指定します。デフォルト設定は HTTP_VERSION_2TLS (TLS 経由の HTTP/2) です。

winHTTPOptions

Windows 固有の HTTP 設定オプションが含まれます。useAnonymousAuth (デフォルト設定は false) などが含まれます。