Configuration de HTTP clients AWS CRT basés sur la configuration - AWS SDK for Java 2.x
Accédez aux HTTP clients AWS CRT basésUtiliser et configurer un HTTP client AWS CRT baséDéfinir un HTTP client AWS CRT basé comme client par défautConfiguration avancéeHTTP/2 supportExemple de configuration de proxy

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Configuration de HTTP clients AWS CRT basés sur la configuration

Les HTTP clients AWS CRT basés incluent les clients synchrones AwsCrtHttpClientet asynchrones AwsCrtAsyncHttpClient. Les HTTP clients AWS CRT basés offrent les avantages suivants aux HTTP clients :

  • Temps de SDK démarrage plus rapide

  • Empreinte mémoire réduite

  • Temps de latence réduit

  • Gestion de l'état de la connexion

  • DNSéquilibrage de charge

AWS CRTcomposants basés dans le SDK

Les HTTPclients AWS CRT basés, décrits dans cette rubrique, et le client S3 AWS CRT basé sur S3 sont des composants différents duSDK.

Les HTTPclients synchrones et asynchrones sont AWS CRT des interfaces SDK HTTP client d'implémentation et sont utilisés pour la communication générale. HTTP Ils constituent des alternatives aux autres HTTP clients synchrones ou asynchrones SDK avec des avantages supplémentaires.

Le client AWS CRT basé sur S3 est une implémentation de l'AsyncClientinterface S3 et est utilisé pour travailler avec le service Amazon S3. Il s'agit d'une alternative à l'implémentation Java de l'S3AsyncClientinterface et offre plusieurs avantages.

Bien que les deux composants utilisent des bibliothèques issues du AWS Common Runtime, les HTTP clients AWS CRT basés n'utilisent pas la bibliothèque aws-c-s 3 et ne prennent pas en charge les API fonctionnalités de téléchargement partitionné S3. Le client AWS CRT S3, en revanche, a été spécialement conçu pour prendre en charge les fonctionnalités de téléchargement partitionné S3. API

Accédez aux HTTP clients AWS CRT basés

Avant de pouvoir utiliser les HTTP clients AWS CRT basés, ajoutez l'aws-crt-clientartefact avec une version minimale de 2.22.0 aux dépendances de votre projet.

Utilisez l'une des options suivantes pour configurer votre pom.xml fichier Maven.

Note

Vous pouvez choisir d'utiliser l'option jar spécifique à la plate-forme si vous devez réduire la taille des dépendances d'exécution, par exemple si votre application s'exécute dans une fonction. AWS Lambda

Uber-jar option

Par défaut, il aws-crt-client utilise un uber-jar d' AWS CRTartefacts contenant des fichiers binaires pour plusieurs plateformes, notamment Linux, Windows et 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>

*Remplacez la version affichée en rouge par la version de Java SDK que vous souhaitez utiliser. Découvrez les dernières actualités sur Maven Central.

Platform-specific jar option

Pour limiter le runtime Java à la version de la AWS CRT bibliothèque spécifique à la plate-forme, apportez les modifications suivantes à l'option Uber-JAR.

  • Ajoutez un exclusions élément à SDK l'aws-crt-clientartefact. Cette exclusion les empêche d'utiliser l' AWS CRTuber-jar SDK de manière transitive.

  • Ajoutez un élément de dépendance pour la version de AWS CRT plate-forme spécifique dont vous avez besoin. Consultez les étapes pour déterminer la version de l' AWS CRTartefact ci-dessous pour savoir comment déterminer la bonne version.

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

1 Remplacez la version affichée en rouge par la version de Java SDK que vous souhaitez utiliser. Découvrez les dernières actualités sur Maven Central.

2 Remplacez la version software.amazon.awssdk.crt:aws-crt qui serait fournie par l'option Uber-jar. Consultez les étapes suivantes pour déterminer la version de l' AWS CRTartefact.

3 Remplacez la classifier valeur par une valeur pour votre plateforme. Reportez-vous à la GitHub page dédiée à Java AWS CRT pour obtenir la liste des valeurs disponibles.

Étapes pour déterminer la version de l' AWS CRTartefact

Procédez comme suit pour déterminer la version de l' AWS CRTartefact compatible avec la version SDK pour Java que vous utilisez.

  1. Configurez votre pom.xml fichier comme indiqué dans l'option Uber-jar. Cette configuration vous permet de voir quelle version software.amazon.awssdk.crt:aws-crt du SDK apporte par défaut.

  2. À la racine du projet (dans le même répertoire que le pom.xml fichier), exécutez la commande Maven suivante :

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

    Maven peut effectuer d'autres actions, mais à la fin, vous devriez voir le résultat de la console indiquant la software.amazon.awssdk.crt:aws-crt dépendance utilisée de SDK manière transitive. L'extrait suivant montre un exemple de sortie basé sur une SDK version de : 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. Utilisez la version affichée sur la console pour l'software.amazon.awssdk.crt:aws-crtartefact. Dans ce cas, ajoutez-le 0.31.3 à votre pom.xml fichier.

Utiliser et configurer un HTTP client AWS CRT basé

Vous pouvez configurer un HTTP client AWS CRT basé tout en créant un client de service, ou vous pouvez configurer une instance unique à partager entre plusieurs clients de service.

Quelle que soit l'approche, vous utilisez un générateur pour configurer les propriétés de l'instance HTTP cliente AWS CRT basée.

Meilleure pratique : dédier une instance à un client de service

Si vous devez configurer une instance d'un HTTP client AWS CRT basé, nous vous recommandons de la dédier en la créant avec le client de service. Vous pouvez le faire en utilisant la httpClientBuilder méthode du générateur du client de service. Ainsi, le cycle de vie du HTTP client est géré par leSDK, ce qui permet d'éviter d'éventuelles fuites de mémoire si l'instance HTTP cliente AWS CRT basée n'est pas fermée alors qu'elle n'est plus nécessaire.

L'exemple suivant crée un client de service S3 et configure un HTTP client AWS CRT basé avec des maxConcurrency valeurs connectionTimeout et.

Synchronous client

Importations

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

Code

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

Importations

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

Code

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

Approche alternative : partager une instance

Pour réduire l'utilisation des ressources et de la mémoire de votre application, vous pouvez configurer un HTTP client AWS CRT basé et le partager entre plusieurs clients de service. Le pool de HTTP connexions sera partagé, ce qui réduira l'utilisation des ressources.

Note

Lorsqu'une instance HTTP cliente AWS CRT basée est partagée, vous devez la fermer lorsqu'elle est prête à être supprimée. Ils ne SDK fermeront pas l'instance lorsque le client de service est fermé.

L'exemple suivant configure une instance HTTP client AWS CRT basée avec des maxConcurrency valeurs connectionTimeout et. L'instance configurée est transmise à la httpClient méthode du générateur de chaque client de service. Lorsque les clients du service et le HTTP client ne sont plus nécessaires, ils sont explicitement fermés. Le HTTP client est fermé en dernier.

Synchronous client

Importations

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;

Code

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

Importations

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;

Code

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

Définir un HTTP client AWS CRT basé comme client par défaut

Vous pouvez configurer votre fichier de compilation Maven pour SDK utiliser un HTTP client AWS CRT basé comme HTTP client par défaut pour les clients de service.

Pour ce faire, ajoutez un exclusions élément avec les dépendances HTTP client par défaut à chaque artefact client de service.

Dans l'pom.xmlexemple suivant, SDK utilise un HTTP client AWS CRT basé pour les services S3. Si le client de service de votre code est unS3AsyncClient, les SDK utilisationsAwsCrtAsyncHttpClient. Si le client du service est un client S3, les SDK utilisations. AwsCrtHttpClient Avec cette configuration, le client asynchrone par défaut basé sur Netty et le HTTP client synchrone basé sur Apache par défaut ne sont pas disponibles. HTTP

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

Visitez le dépôt central de Maven pour obtenir les dernières informations VERSIONValeur .

Note

Si plusieurs clients de service sont déclarés dans un pom.xml fichier, tous ont besoin de l'exclusionsXMLélément.

Utiliser une propriété système Java

Pour utiliser les HTTP clients AWS CRT basés par défaut HTTP pour votre application, vous pouvez définir la propriété système Java software.amazon.awssdk.http.async.service.impl sur une valeur desoftware.amazon.awssdk.http.crt.AwsCrtSdkHttpService.

Pour définir lors du démarrage de l'application, exécutez une commande similaire à la suivante.

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

Utilisez l'extrait de code suivant pour définir la propriété système dans le code de votre application.

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

Vous devez ajouter une dépendance à l'aws-crt-clientartefact de votre poml.xml fichier lorsque vous utilisez une propriété système pour configurer l'utilisation des HTTP clients AWS CRT basés.

Configuration avancée de HTTP clients AWS CRT basés

Vous pouvez utiliser différents paramètres de configuration des HTTP clients AWS CRT basés, notamment la configuration de l'état de la connexion et le temps d'inactivité maximal. Vous pouvez consulter les options de configuration disponibles pourAwsCrtAsyncHttpClient. Vous pouvez configurer les mêmes options pourAwsCrtHttpClient.

Configuration de l'état de la connexion

Vous pouvez configurer la configuration de l'état de la connexion pour HTTP les clients AWS CRT basés en utilisant la connectionHealthConfiguration méthode du générateur de HTTP clients.

L'exemple suivant crée un client de service S3 qui utilise une instance HTTP client AWS CRT basée configurée avec une configuration d'état de connexion et une durée d'inactivité maximale pour les connexions.

Synchronous client

Importations

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

Code

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

Importations

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

Code

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

HTTP/2 support

Le protocole HTTP /2 n'est pas encore pris en charge dans les HTTP clients AWS CRT basés, mais il est prévu pour une future version.

En attendant, si vous utilisez des clients de service qui ont besoin d'un support HTTP /2 tel que le KinesisAsyncClientou le TranscribeStreamingAsyncClient, pensez à utiliser le à la NettyNioAsyncHttpClientplace.

Exemple de configuration de proxy

L'extrait de code suivant montre l'utilisation de ProxyConfiguration.Buildercelui que vous utilisez pour configurer les paramètres du proxy dans le code.

Synchronous client

Importations

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

Code

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

Importations

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

Code

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

Les propriétés système Java équivalentes pour la configuration du proxy sont indiquées dans l'extrait de ligne de commande suivant.

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

Pour utiliser l'une des propriétés du système HTTPS proxy, la scheme propriété doit être définie dans le code surhttps. Si la propriété du schéma n'est pas définie dans le code, le schéma est défini par défaut HTTP et ne SDK recherche que les propriétés http.* du système.

La configuration équivalente qui utilise des variables d'environnement est la suivante :

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