Configurar os clientes HTTP baseados em AWS CRT - AWS SDK for Java 2.x
Acessar os clientes HTTP baseados em AWS CRTUsar e configurar um cliente HTTP baseado em AWS CRTDefinir um cliente HTTP baseado em AWS CRT como padrãoConfiguração avançadaSuporte a HTTP/2Exemplo de configuração do proxy

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Configurar os clientes HTTP baseados em AWS CRT

Os clientes HTTP baseados em AWS CRT incluem o AwsCrtHttpClient síncrono e o AwsCrtAsyncHttpClient assíncrono. Os clientes HTTP baseados em AWS CRT oferecem os seguintes benefícios do cliente HTTP:

  • Menor tempo de inicialização do SDK

  • Menor espaço ocupado na memória

  • Tempo de latência reduzido

  • Gerenciamento de integridade da conexão

  • balanceamento de carga do DNS

Componentes da AWS baseados em CRT no SDK

Os clientes HTTP baseados em AWS CRT, descritos neste tópico, e o cliente do S3 baseado em AWS CRT são componentes diferentes no SDK.

Os clientes HTTP baseados em AWS CRT síncronos e assíncronos são implementações da interface de cliente HTTP do SDK usadas para a comunicação HTTP em geral. Eles são alternativas aos outros clientes HTTP síncronos ou assíncronos no SDK, com benefícios adicionais.

O cliente do S3 baseado no AWS CRT é uma implementação da interface S3AsyncClient e é usado para trabalhar com o serviço Amazon S3. É uma alternativa à implementação da interface S3AsyncClient baseada em Java e oferece vários benefícios.

Embora os dois componentes usem bibliotecas do AWS Common Runtime, o cliente HTTP baseado em AWS CRT não usa a biblioteca aws-c-s3 e não é compatível com os recursos da API de multipart upload do S3. O cliente S3 da AWS baseado em CRT, por outro lado, foi criado especificamente para oferecer suporte aos recursos da API de upload em várias partes do S3.

Acessar os clientes HTTP baseados em AWS CRT

Para usar os clientes HTTP baseados em AWS CRT, adicione o artefato aws-crt-client com, no mínimo, a versão 2.22.0 às dependências do projeto.

Use uma das opções a seguir para configurar o arquivo pom.xml do Maven.

nota

Você pode optar por usar a opção jar específica da plataforma se precisar manter o tamanho das dependências de runtime menor, por exemplo, se a aplicação for executada em uma função do AWS Lambda.

Uber-jar option

Por padrão, o aws-crt-client usa um uber-jar de artefatos do AWS CRT que contém binários para várias plataformas, incluindo Linux, Windows e macOS.

<project>
   <properties>
     <aws.sdk.java.version>2.29.10*</aws.sdk.java.version>
  </properties>
  <dependencyManagement>
   <dependencies>
      <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>bom</artifactId>
        <version>${aws.sdk.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
   </dependencies>
  </dependencyManagement>
  <dependencies>
   <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>aws-crt-client</artifactId>
   </dependency>
  </dependencies>
</project>

*Substitua a versão mostrada em vermelho pela versão do Java SDK que você deseja usar. Encontre as últimas novidades no Maven Central.

Platform-specific jar option

Para restringir o runtime do Java à versão específica da plataforma da biblioteca do AWS CRT, faça as seguintes alterações na opção Uber-jar.

  • Adicione um elemento exclusions ao artefato aws-crt-client do SDK. Essa exclusão impede que o SDK use transitivamente o uber-jar do AWS CRT.

  • Adicione um elemento de dependência para a versão específica da plataforma AWS CRT de que você precisa. Consulte as Etapas para determinar a versão do artefato do AWS CRT abaixo para saber como você pode determinar a versão correta.

<project>
   <properties>
     <aws.sdk.java.version>2.29.101</aws.sdk.java.version>
  </properties>
   <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>software.amazon.awssdk</groupId>
                <artifactId>bom</artifactId>
                <version>${aws.sdk.java.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>aws-crt-client</artifactId>
            <exclusions>
                <exclusion>
                    <groupId>software.amazon.awssdk.crt</groupId>
                    <artifactId>aws-crt</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>software.amazon.awssdk.crt</groupId>
            <artifactId>aws-crt</artifactId>
            <version>0.31.32</version>
            <classifier>linux-x86_643</classifier>
        </dependency>
    </dependencies>

1Substitua a versão mostrada em vermelho pela versão do Java SDK que você deseja usar. Encontre as últimas novidades no Maven Central.

2Substitua a versão de software.amazon.awssdk.crt:aws-crt que seria fornecida pela opção Uber-JAR. Consulte as seguintes Etapas para determinar a versão do artefato do AWS CRT.

3Substitua o valor classifier por um para sua plataforma. Consulte a página do AWS CRT para Java no GitHub para obter uma lista dos valores disponíveis.

Etapas para determinar a versão do artefato do AWS CRT

Use as etapas a seguir para determinar a versão do artefato do AWS CRT compatível com a versão do SDK para Java que você está usando.

  1. Configure o arquivo pom.xml conforme mostrado na opção Uber-JAR. Essa configuração permite que você veja qual versão do software.amazon.awssdk.crt:aws-crt o SDK traz por padrão.

  2. Na raiz do projeto (no mesmo diretório do arquivo pom.xml), execute o seguinte comando do Maven:

    mvn dependency:tree -Dincludes=software.amazon.awssdk.crt:aws-crt

    O Maven pode realizar outras ações, mas no final você deve ver a saída do console da dependência software.amazon.awssdk.crt:aws-crt que o SDK usa transitivamente. O trecho a seguir mostra um exemplo de saída com base em uma versão do SDK do 2.29.10:

    [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

  3. Use a versão que o console mostra para o artefato software.amazon.awssdk.crt:aws-crt. Nesse caso, adicione 0.31.3 ao arquivo pom.xml.

Usar e configurar um cliente HTTP baseado em AWS CRT

É possível configurar um cliente HTTP baseado em AWS CRT junto com a criação de um cliente de serviço ou configurar uma única instância para compartilhar entre vários clientes de serviço.

Com qualquer abordagem, você vai usar um criador para configurar as propriedades da instância do cliente HTTP baseado em AWS CRT.

Prática recomendada: dedicar uma instância do a um cliente de serviço

Se você precisar configurar uma instância de um cliente HTTP baseado em AWS CRT, recomendamos dedicar a instância desenvolvendo-a junto com o cliente de serviço. Faça isso usando o método httpClientBuilder do builder do cliente do serviço. Dessa forma, o ciclo de vida do cliente HTTP é gerenciado pelo SDK, o que ajudará a evitar possíveis vazamentos de memória se a instância do cliente HTTP baseado em AWS CRT não for fechada quando não for mais necessária.

O exemplo a seguir cria um cliente de serviço do S3 e configura um cliente HTTP baseado em AWS CRT com os valores de connectionTimeout e maxConcurrency.

Synchronous client

Importações

import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;

Código da

// 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

Importações

import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import java.time.Duration;

Código da

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

Abordagem alternativa: compartilhar uma instância do

Para ajudar a reduzir o uso de recursos e de memória da aplicação, é possível configurar um cliente HTTP baseado em AWS CRT e compartilhá-lo entre vários clientes de serviço. O pool de conexões HTTP será compartilhado, o que reduz o uso de recursos.

nota

Quando uma instância do cliente HTTP baseado em AWS CRT é compartilhada, é necessário fechá-la quando ela estiver pronta para ser descartada. O SDK não fechará a instância quando o cliente de serviço for fechado.

O exemplo a seguir configura uma instância de cliente HTTP baseado em AWS CRT com os valores de connectionTimeout e maxConcurrency. A instância configurada é transmitida ao método httpClient do criador de cada cliente de serviço. Quando os clientes do serviço e o cliente HTTP não são mais necessários, eles são explicitamente fechados. O cliente HTTP é fechado por último.

Synchronous client

Importações

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;

Código da

// 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

Importações

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;

Código da

// 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.

Definir um cliente HTTP baseado em AWS CRT como padrão

É possível configurar o arquivo de compilação do Maven para que o SDK use um cliente HTTP baseado em AWS CRT como o cliente HTTP padrão para clientes de serviço.

Você faz isso adicionando um elemento exclusions com as dependências padrão do cliente HTTP a cada artefato do cliente de serviço.

No exemplo pom.xml a seguir, o SDK usa um cliente HTTP baseado em AWS CRT para serviços do S3. Se o cliente de serviço no código for um S3AsyncClient, o SDK usará AwsCrtAsyncHttpClient. Se o cliente de serviço for um S3Client, o SDK usará AwsCrtHttpClient. Com essa configuração, o cliente HTTP assíncrono padrão baseado em Netty e o HTTP síncrono padrão baseado em Apache não estão disponíveis.

<project>
   <properties>
     <aws.sdk.version>VERSION</aws.sdk.version>
  </properties>
  <dependencies>
   <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>s3</artifactId>
      <version>${aws.sdk.version}</version>
      <exclusions>
         <exclusion>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>netty-nio-client</artifactId>
         </exclusion>
         <exclusion>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>apache-client</artifactId>
         </exclusion>
      </exclusions>
   </dependency>
   <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>aws-crt-client</artifactId>
   </dependency>
  </dependencies>
</project>

Visite o repositório central do Maven para obter o valor mais recente de VERSION.

nota

Se vários clientes de serviço forem declarados em um arquivo pom.xml, todos precisarão do elemento XML exclusions.

Usar uma propriedade do sistema Java

Para usar os clientes HTTP baseados em AWS CRT como o HTTP padrão para a aplicação, é possível definir a propriedade software.amazon.awssdk.http.async.service.impl do sistema Java com um valor de software.amazon.awssdk.http.crt.AwsCrtSdkHttpService.

Para definir durante a inicialização do aplicativo, execute um comando semelhante ao seguinte.

java app.jar -Dsoftware.amazon.awssdk.http.async.service.impl=\
software.amazon.awssdk.http.crt.AwsCrtSdkHttpService

Use o trecho de código a seguir para definir a propriedade do sistema no código do seu aplicativo.

System.setProperty("software.amazon.awssdk.http.async.service.impl",
"software.amazon.awssdk.http.crt.AwsCrtSdkHttpService");
nota

É necessário adicionar uma dependência do artefato aws-crt-client no arquivo poml.xml ao usar uma propriedade do sistema para configurar o uso do cliente HTTP baseado em AWS CRT.

Configuração avançada de clientes HTTP baseados em AWS CRT

É possível usar várias configurações dos clientes HTTP baseados em AWS CRT, incluindo a configuração de integridade da conexão e o tempo máximo de inatividade. Você pode revisar as opções de configuração disponíveis para o AwsCrtAsyncHttpClient. É possível configurar as mesmas opções para o AwsCrtHttpClient.

Configuração de integridade da conexão

É possível configurar a integridade da conexão para o cliente HTTP baseado em AWS CRT usando o método connectionHealthConfiguration no criador de clientes HTTP.

O exemplo a seguir cria um serviço do S3 que usa uma instância do cliente HTTP baseado em AWS CRT definida com a configuração de integridade da conexão e um tempo máximo de inatividade para as conexões.

Synchronous client

Importações

import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;

Código da

// 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

Importações

import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.services.s3.S3AsyncClient;
import java.time.Duration;

Código da

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

Suporte a HTTP/2

O protocolo HTTP/2 ainda não é aceito nos clientes HTTP baseados em AWS CRT, mas está planejado para uma versão futura.

Enquanto isso, se você estiver usando clientes de serviço que exigem suporte a HTTP/2, como o KinesisAsyncClient ou o TranscribeStreamingAsyncClient, considere usar o NettyNioAsyncHttpClient em vez disso.

Exemplo de configuração do proxy

O trecho de código a seguir mostra o uso do ProxyConfiguration.Builder que você usa para definir a configuração de proxy no código.

Synchronous client

Importações

import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtHttpClient;
import software.amazon.awssdk.http.crt.ProxyConfiguration;

Código da

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

Importações

import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
import software.amazon.awssdk.http.crt.AwsCrtAsyncHttpClient;
import software.amazon.awssdk.http.crt.ProxyConfiguration;

Código da

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

As propriedades equivalentes do sistema Java para a configuração do proxy são mostradas no trecho da linha de comando a seguir.

$ java -Dhttps.proxyHost=myproxy -Dhttps.proxyPort=1234 -Dhttps.proxyUser=username \
-Dhttps.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App
Importante

Para usar qualquer uma das propriedades do sistema proxy HTTPS, a propriedade scheme deve ser definida no código como https. Se a propriedade scheme não estiver definida no código, o esquema usará HTTP como padrão, e o SDK procurará somente as propriedades do sistema http.*.

A configuração equivalente que usa variáveis de ambiente é:

// 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