Configurar clientes AWS HTTP baseados em CRT

Os clientes HTTP AWS baseados em CRT incluem o síncrono e o assíncrono. AwsCrtHttpClientAwsCrtAsyncHttpClient Os clientes HTTP AWS baseados em 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

AWS Componentes baseados em CRT no SDK

Os clientes HTTP AWS baseados em CRT, descritos neste tópico, e o cliente S3 AWS baseado em 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 S3 AWS baseado em CRT é uma implementação da AsyncClient interface S3 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 ambos os componentes usem bibliotecas do AWS Common Runtime, os clientes HTTP AWS baseados em CRT não usam a biblioteca aws-c-s 3 e não oferecem suporte aos recursos da API de upload de várias partes do S3. O cliente S3 AWS baseado em CRT, por outro lado, foi criado especificamente para oferecer suporte aos recursos da API de upload de várias partes do S3.

Acesse os clientes AWS HTTP baseados em CRT

Antes de usar os clientes HTTP AWS baseados em CRT, adicione o aws-crt-client artefato com uma versão mínima de 2.22.0 às dependências do seu projeto.

O Maven a seguir pom.xml mostra os clientes HTTP AWS baseados em CRT declarados usando o mecanismo de lista de materiais (BOM).

<project>
   <properties>
     <aws.sdk.version>2.22.0</aws.sdk.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>

Visite o repositório central do Maven para receber a versão mais recente.

Use e configure um cliente HTTP AWS baseado em CRT

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

Com qualquer abordagem, você usa um construtor para configurar as propriedades da instância do cliente HTTP AWS baseada em 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 AWS baseado em CRT, recomendamos que você dedique a instância construindo-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 ajuda a evitar possíveis vazamentos de memória se a instância do cliente HTTP AWS baseada em CRT não for fechada quando não for mais necessária.

O exemplo a seguir cria um cliente de serviço S3 e configura um cliente HTTP AWS baseado em CRT com valores e. connectionTimeout 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

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

// 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 memória do seu aplicativo, você pode configurar um cliente HTTP AWS baseado em 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 de cliente HTTP AWS baseada em CRT é compartilhada, você deve 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 AWS baseada em CRT com valores e. connectionTimeout 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

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

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

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

Você pode configurar seu arquivo de compilação do Maven para que o SDK use um cliente HTTP AWS baseado em 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 pom.xml exemplo a seguir, o SDK usa um cliente HTTP AWS baseado em 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 AWS baseados em CRT como o HTTP padrão para seu aplicativo, você pode definir a propriedade do sistema Java software.amazon.awssdk.http.async.service.impl 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

Você precisa adicionar uma dependência do aws-crt-client artefato em seu poml.xml arquivo ao usar uma propriedade do sistema para configurar o uso dos clientes HTTP baseados em AWS CRT.

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

Você pode usar várias configurações dos clientes HTTP AWS baseados em CRT, incluindo configuração de integridade da conexão e 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

Você pode configurar a integridade da conexão para os clientes HTTP AWS baseados em CRT usando o connectionHealthConfiguration método no construtor de clientes HTTP.

O exemplo a seguir cria um cliente de serviço S3 que usa uma instância de cliente HTTP AWS baseada em CRT configurada com configuração de integridade da conexão e um tempo máximo de inatividade para 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

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

// 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 é suportado nos clientes HTTP AWS baseados em 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 KinesisAsyncClientou o TranscribeStreamingAsyncClient, considere usar o. NettyNioAsyncHttpClient

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

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

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