Configurar clientes de serviço no código do AWS SDK para C++ no código

Quando a configuração é tratada diretamente no código, o escopo da configuração é limitado à aplicação que usa esse código. Dentro dessa aplicação, há opções para a configuração global de todos os clientes de serviço, a configuração para todos os clientes de determinado tipo de AWS service (Serviço da AWS) ou a configuração para uma instância específica do cliente de serviço.

O AWS SDK para C++ inclui classes de cliente de AWS service (Serviço da AWS) que fornecem funcionalidade para interagir com os Serviços da AWS que você usa em sua aplicação. No SDK para C++, é possível alterar a configuração padrão do cliente, o que é útil quando você quer fazer coisas, como:

Conectar-se à Internet por meio de proxy
Alterar configurações de transporte HTTP, como tempo limite da conexão e novas tentativas de requisição
Especificar dicas de tamanho do buffer de soquete TCP

ClientConfiguration é uma estrutura no SDK para C++ que você pode instanciar e utilizar em seu código. O trecho a seguir ilustra o uso dessa classe para acessar o Amazon S3 por meio de um proxy.


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

Declarações de variáveis de configuração

A estrutura ClientConfiguration declara as seguintes variáveis de membro:


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);

Declarações de variáveis de configuração

A lista a seguir descreve as variáveis do membro ClientConfiguration que você pode usar para personalizar o comportamento do cliente.

accountId: Especifica o ID da Conta da AWS para roteamento de endpoints baseado em conta. Use o formato 111122223333. O roteamento de endpoints baseado em conta oferece melhor desempenho em solicitações para alguns serviços.
accountIdEndpointMode: Controla o comportamento de roteamento de endpoints baseado na conta. Os valores válidos são “obrigatório”, “desabilitado” ou “preferencial”. O valor padrão é “preferido”. Defina como “desabilitado” para desativar o roteamento de endpoints baseado em conta quando necessário.
allowSystemProxy: Controla se o cliente HTTP descobre as configurações de proxy do sistema. A configuração padrão é false. Defina como true para habilitar a descoberta automática de proxy.
appId: Especifica um identificador opcional específico da aplicação. Quando definido, esse valor é anexado ao cabeçalho User-Agent no formato App/{appId}. É possível definir esse valor usando a variável de ambiente AWS_SDK_UA_APP_ID ou o atributo de perfil de configuração compartilhado sdk_ua_app_id.
caPath, caFile: Instrui o cliente HTTP sobre onde encontrar o armazenamento confiável de certificados SSL. Um exemplo de armazenamento confiável pode ser um diretório preparado com o utilitário OpenSSL c_rehash. Essas variáveis não precisam ser definidas, a menos que seu ambiente use links simbólicos. Essas variáveis não têm efeito nos sistemas Windows e macOS.
checksumConfig: Contém configurações de cálculo e validação da soma de verificação. Inclui requestChecksumCalculation e responseChecksumValidation com valor padrão WHEN_SUPPORTED.
configFactories: Especifica métodos de fábrica para inicializar classes de utilitários do cliente, como Executor e RetryStrategy. Usa fábricas padrão, a menos que seja substituído.
requestTimeoutMs e connectTimeoutMs: Especifica o tempo em milissegundos a aguardar antes de uma solicitação HTTP atingir o tempo limite. Por exemplo, pense em aumentar esses tempos ao transferir arquivos grandes.
credentialProviderConfig: Contém definições de configuração para provedores de credenciais. Use essa estrutura para personalizar o modo como o SDK recupera as credenciais da AWS.
disableExpectHeader: Aplicável somente para clientes HTTP CURL. Por padrão, o CURL adiciona um cabeçalho “Expect: 100-Continue” a uma solicitação HTTP para evitar o envio da carga útil HTTP em situações em que o servidor responde com um erro imediatamente após receber o cabeçalho. Esse comportamento pode economizar uma ida e volta e é útil em situações em que a carga útil é pequena e a latência da rede é relevante. A configuração padrão da variável é false. Se definido como true, o CURL é instruído a enviar o cabeçalho da solicitação HTTP e a carga útil do corpo juntos.
disableIMDS: Controla se as chamadas do Serviço de Metadados de Instância (IMDS) estão desabilitadas. A configuração padrão é false. Defina como true para desabilitar as chamadas do IMDS quando executadas fora das instâncias do EC2.
disableImdsV1: Controla se as chamadas do IMDSv1 estão desabilitadas ao habilitar o IMDSv2. A configuração padrão é false. Defina como true para desabilitar somente as chamadas do IMDSv1 para aumentar a segurança.
enableClockSkewAdjustment: Controla se a o desvio de relógio é ajustado após cada tentativa de HTTP. A configuração padrão é false.
enableEndpointDiscovery: Controla se a descoberta de endpoints é usada. Por padrão, endpoints regionais ou substituídos são usados. Para habilitar a descoberta de endpoints, defina a variável como true.
enableHostPrefixInjection: Controla se o host HTTP adiciona um prefixo “data-” às solicitações DiscoverInstances. Por padrão, esse comportamento é habilitado. Para desabilitá-la, defina a variável como false.
enableHttpClientTrace: Controla se o rastreamento do cliente HTTP está habilitado para fins de depuração. A configuração padrão é false. Defina como true para habilitar o registro em log de solicitações e respostas HTTP.
enableTcpKeepAlive: Controla se os pacotes TCP keep-alive devem ser enviados. A configuração padrão é true. Use em conjunto com a variável tcpKeepAliveIntervalMs. Essa variável não se aplica ao WinINet e ao cliente IXMLHTTPRequest2.
endpointOverride: Especifica um endpoint HTTP substitutivo com o qual se comunicar com um serviço.
executor: Faz referência à implementação do manipulador executor assíncrono. O comportamento padrão é criar e desanexar um encadeamento para cada chamada assíncrona. Para alterar esse comportamento, implemente uma subclasse da classe Executor e atribua uma instância a essa variável.
followRedirects: Controla o comportamento ao lidar com códigos de redirecionamento HTTP 300.
httpLibOverride: Especifica a implementação HTTP exibida pela fábrica HTTP padrão. O cliente HTTP padrão para Windows é WinHTTP. O cliente HTTP padrão para todas as outras plataformas é CURL.
httpLibPerfMode: Especifica o modo de desempenho da biblioteca HTTP. A configuração padrão é LOW_LATENCY. É possível ajustar essa configuração para otimizar as diferentes características de desempenho.
httpRequestTimeoutMs: Especifica o tempo limite da solicitação HTTP em milissegundos. O valor padrão é 0 (nenhum tempo limite). Pense em aumentar esse valor ao transferir arquivos grandes.
lowSpeedLimit: Especifica a velocidade de transferência mínima permitida em bytes por segundo. Se a velocidade de transferência cair abaixo da velocidade especificada, a operação de transferência será abortada. A configuração padrão é de 1 byte/segundo. Essa variável é aplicável somente para clientes CURL.
maxConnections: Especifica o número máximo de conexões HTTP com um único servidor. O valor padrão é 25. Não existe nenhum valor máximo permitido além do que sua largura de banda pode razoavelmente suportar.
nonProxyHosts: Especifica uma matriz de nomes de host que devem ignorar as configurações de proxy. Use essa configuração para excluir hosts específicos da configuração do proxy.
profileName: Especifica o nome do perfil da AWS a ser usado para configuração. O SDK carrega as configurações do perfil especificado no arquivo de configuração da AWS.
proxyCaFile: Especifica o caminho do arquivo da autoridade de certificação para conexões proxy quando ele é diferente do padrão.
proxyCaPath: Especifica o caminho do armazenamento de confiança da autoridade de certificação para conexões proxy quando ele é diferente do padrão.
proxyScheme, proxyHost, proxyPort, proxyUserName, and proxyPassword: Usado para instalar e configurar um proxy para todas as comunicações com AWS. Exemplos de quando essa funcionalidade pode ser útil incluem a depuração em conjunto com o pacote Burp ou o uso de um proxy para se conectar à Internet.
proxySSLCertPath: Especifica o caminho do arquivo de certificado SSL para conexões proxy que exigem certificados de cliente.
proxySSLCertType: Especifica o tipo de certificado SSL para conexões proxy. Os tipos comuns incluem PEM e DER.
proxySSLKeyPassword: Especifica a senha da chave privada SSL usada em conexões proxy quando a chave é protegida por senha.
proxySSLKeyPath: Especifica o caminho do arquivo de chave privada SSL para conexões proxy que exigem certificados de cliente.
proxySSLKeyType: Especifica o tipo de chave privada SSL para conexões proxy. Os tipos comuns incluem PEM e DER.
writeRateLimiter e readRateLimiter: Referências às implementações de limitadores de taxa de leitura e gravação que são usados para realizar o controle de utilização da largura de banda usada pela camada de transporte. Por padrão, as taxas de leitura e gravação não têm controle de utilização. Para introduzir o controle de utilização, implemente uma subclasse de RateLimiterInterface e atribua uma instância a essas variáveis.
região: Especifica a região da AWS a ser usada, como us-east-1. Por padrão, a região usada é a região padrão configurada nas credenciais aplicáveis da AWS.
requestCompressionConfig: Contém definições de configuração para compactação de solicitações. Use essa estrutura para controlar quando e como as solicitações são compactadas antes da transmissão.
retryStrategy: Faz referência à implementação da estratégia de repetição. A estratégia padrão implementa uma política de recuo exponencial. Para realizar uma estratégia diferente, implemente uma subclasse da classe RetryStrategy e atribua uma instância a essa variável.
scheme: Especifica o esquema de endereçamento do URI, HTTP ou HTTPS. O esquema padrão é HTTPS.
tcpKeepAliveIntervalMs: Especifica o intervalo de tempo em milissegundos para enviar um pacote keep-alive por uma conexão TCP. O intervalo padrão é 30 segundos. A configuração mínima é de 15 segundos. Essa variável não se aplica ao WinINet e ao cliente IXMLHTTPRequest2.
telemetryProvider: Faz referência à implementação do provedor de telemetria para coletar métricas e rastrear dados. Defina essa configuração para habilitar os recursos de observabilidade.
userAgent: Apenas para uso interno. Não altere a configuração dessa variável.
useDualStack: Controla se é necessário usar endpoints IPv4 e IPv6 de pilha dupla. Observe que nem todos os serviços da AWS comportam IPv6 em todas as regiões.
useFIPS: Controla se é necessário usar módulos criptográficos validados pelo Federal Information Processing Standards (FIPS) 140-2. A configuração padrão é false. Defina como true quando a conformidade com FIPS for necessária.
verifySSL: Controla se os certificados SSL devem ser verificados. Por padrão, os certificados SSL são verificados. Para desabilitar a verificação, defina a variável como false.
version: Especifica a versão HTTP a ser usada para solicitações. A configuração padrão é HTTP_VERSION_2TLS (HTTP/2 sobre TLS).
winHTTPOptions: Contém opções de configuração HTTP específicas do Windows. Inclui useAnonymousAuth com configuração padrão false.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Configuração externa de cliente

Região da AWS