AWS CRT-basierte HTTP-Clients konfigurieren

Zu den AWS CRT-basierten HTTP-Clients gehören synchrone und asynchrone AwsCrtHttpClientClients. AwsCrtAsyncHttpClient Die AWS CRT-basierten HTTP-Clients bieten die folgenden Vorteile für HTTP-Clients:

• Schnellere SDK-Startzeit

• Geringerer Speicherbedarf

• Reduzierte Latenzzeit

• Verwaltung der Verbindungsintegrität

• DNS-Lastenausgleich

AWS CRT-basierte Komponenten im SDK

Die in diesem Thema beschriebenen AWS CRT-basierten HTTP-Clients und der AWS CRT-basierte S3-Client sind unterschiedliche Komponenten im SDK.

Die synchronen und asynchronen AWS CRT-basierten HTTP-Clients sind SDK-HTTP-Client-Schnittstellen für Implementierungen und werden für die allgemeine HTTP-Kommunikation verwendet. Sie sind Alternativen zu den anderen synchronen oder asynchronen HTTP-Clients im SDK mit zusätzlichen Vorteilen.

Der AWS CRT-basierte S3-Client ist eine Implementierung der AsyncClientS3-Schnittstelle und wird für die Arbeit mit dem Amazon S3 S3-Service verwendet. Es ist eine Alternative zur Java-basierten Implementierung der S3AsyncClient Schnittstelle und bietet mehrere Vorteile.

Obwohl beide Komponenten Bibliotheken aus der AWS Common Runtime verwenden, verwenden die AWS CRT-basierten HTTP-Clients die aws-c-s3-Bibliothek nicht und unterstützen auch nicht die API-Funktionen für mehrteilige Uploads von S3. Der AWS CRT-basierte S3-Client wurde dagegen speziell für die Unterstützung der API-Funktionen für mehrteilige S3-Uploads entwickelt.

Greifen Sie auf die CRT-basierten HTTP-Clients zu AWS

Bevor Sie die AWS CRT-basierten HTTP-Clients verwenden können, fügen Sie das aws-crt-client Artefakt mit einer Mindestversion von 2.22.0 zu den Abhängigkeiten Ihres Projekts hinzu.

Der folgende Maven pom.xml zeigt die AWS CRT-basierten HTTP-Clients, die mithilfe des Stücklistenmechanismus (BOM) deklariert wurden.

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

Besuchen Sie das zentrale Maven-Repository für die neueste Version.

Verwenden und konfigurieren Sie einen AWS CRT-basierten HTTP-Client

Sie können einen AWS CRT-basierten HTTP-Client zusammen mit der Erstellung eines Service-Clients konfigurieren, oder Sie können eine einzelne Instanz so konfigurieren, dass sie von mehreren Service-Clients gemeinsam genutzt wird.

Bei beiden Ansätzen verwenden Sie einen Builder, um die Eigenschaften für die AWS CRT-basierte HTTP-Clientinstanz zu konfigurieren.

Bewährtes Verfahren: Dedizieren Sie eine Instanz einem Service-Client

Wenn Sie eine Instanz eines AWS CRT-basierten HTTP-Clients konfigurieren müssen, empfehlen wir, dass Sie die Instanz dedizieren, indem Sie sie zusammen mit dem Service-Client erstellen. Sie können dies tun, indem Sie die httpClientBuilder Methode des Builders des Service-Clients verwenden. Auf diese Weise wird der Lebenszyklus des HTTP-Clients vom SDK verwaltet, wodurch potenzielle Speicherlecks vermieden werden, wenn die AWS CRT-basierte HTTP-Client-Instanz nicht geschlossen wird, wenn sie nicht mehr benötigt wird.

Im folgenden Beispiel wird ein S3-Serviceclient erstellt und ein AWS CRT-basierter HTTP-Client mit Werten und konfiguriert. connectionTimeout maxConcurrency

Synchronous client

Importe

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

Importe

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

Alternativer Ansatz: gemeinsame Nutzung einer Instanz

Um die Ressourcen- und Speicherauslastung für Ihre Anwendung gering zu halten, können Sie einen AWS CRT-basierten HTTP-Client konfigurieren und ihn von mehreren Service-Clients gemeinsam nutzen. Der HTTP-Verbindungspool wird gemeinsam genutzt, was die Ressourcennutzung senkt.

Anmerkung

Wenn eine AWS CRT-basierte HTTP-Client-Instanz gemeinsam genutzt wird, müssen Sie sie schließen, wenn sie bereit ist, gelöscht zu werden. Das SDK schließt die Instanz nicht, wenn der Service-Client geschlossen wird.

Im folgenden Beispiel wird eine AWS CRT-basierte HTTP-Clientinstanz mit connectionTimeout Werten und konfiguriert. maxConcurrency Die konfigurierte Instanz wird an die httpClient Methode des Builders jedes Service-Clients übergeben. Wenn die Service-Clients und der HTTP-Client nicht mehr benötigt werden, werden sie explizit geschlossen. Der HTTP-Client wird zuletzt geschlossen.

Synchronous client

Importe

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

Importe

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.

Stellen Sie einen AWS CRT-basierten HTTP-Client als Standard ein

Sie können Ihre Maven-Build-Datei so einrichten, dass das SDK einen AWS CRT-basierten HTTP-Client als Standard-HTTP-Client für Service-Clients verwendet.

Dazu fügen Sie jedem Service-Client-Artefakt ein exclusions Element mit den standardmäßigen HTTP-Client-Abhängigkeiten hinzu.

Im folgenden pom.xml Beispiel verwendet das SDK einen AWS CRT-basierten HTTP-Client für S3-Dienste. Wenn der Service-Client in Ihrem Code ein istS3AsyncClient, verwendet das SDK. AwsCrtAsyncHttpClient Wenn der Service-Client ein S3Client ist, verwendet das SDK. AwsCrtHttpClient Bei diesem Setup sind der standardmäßige asynchrone HTTP-Client auf Netty-Basis und der standardmäßige asynchrone HTTP-Client auf Apache-Basis nicht verfügbar.

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

Den neuesten VERSION-Wert finden Sie im zentralen Maven-Repository.

Anmerkung

Wenn mehrere Service-Clients in einer pom.xml Datei deklariert sind, benötigen alle das exclusions XML-Element.

Verwenden Sie eine Java-Systemeigenschaft

Um die AWS CRT-basierten HTTP-Clients als Standard-HTTP für Ihre Anwendung zu verwenden, können Sie die Java-Systemeigenschaft software.amazon.awssdk.http.async.service.impl auf den Wert von setzen. software.amazon.awssdk.http.crt.AwsCrtSdkHttpService

Um den Wert beim Start der Anwendung festzulegen, führen Sie einen Befehl aus, der dem folgenden ähnelt.

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

Verwenden Sie den folgenden Codeausschnitt, um die Systemeigenschaft in Ihrem Anwendungscode festzulegen.

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

Anmerkung

Sie müssen eine Abhängigkeit von dem aws-crt-client Artefakt in Ihrer poml.xml Datei hinzufügen, wenn Sie eine Systemeigenschaft verwenden, um die Verwendung der AWS CRT-basierten HTTP-Clients zu konfigurieren.

Erweiterte Konfiguration von CRT-basierten HTTP-Clients AWS

Sie können verschiedene Konfigurationseinstellungen der AWS CRT-basierten HTTP-Clients verwenden, einschließlich der Konfiguration des Verbindungsstatus und der maximalen Leerlaufzeit. Sie können die verfügbaren Konfigurationsoptionen für überprüfen. AwsCrtAsyncHttpClient Sie können dieselben Optionen für den konfigurierenAwsCrtHttpClient.

Konfiguration des Verbindungsstatus

Sie können die Verbindungsintegritätskonfiguration für die AWS CRT-basierten HTTP-Clients konfigurieren, indem Sie die connectionHealthConfiguration Methode im HTTP-Client-Builder verwenden.

Im folgenden Beispiel wird ein S3-Dienstclient erstellt, der eine AWS CRT-basierte HTTP-Clientinstanz verwendet, die mit einer Verbindungsintegritätskonfiguration und einer maximalen Leerlaufzeit für Verbindungen konfiguriert ist.

Synchronous client

Importe

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

Importe

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

Das HTTP/2-Protokoll wird in den AWS CRT-basierten HTTP-Clients noch nicht unterstützt, ist aber für eine future Version geplant.

Wenn Sie in der Zwischenzeit Service-Clients verwenden, die HTTP/2-Unterstützung benötigen, wie z. B. der KinesisAsyncClientoder der, sollten Sie in Erwägung ziehen TranscribeStreamingAsyncClient, stattdessen den zu verwenden. NettyNioAsyncHttpClient

Beispiel für eine Proxykonfiguration

Der folgende Codeausschnitt zeigt die Verwendung der Einstellung ProxyConfiguration.Builder, die Sie zur Konfiguration der Proxyeinstellungen verwenden, im Code.

Synchronous client

Importe

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

Importe

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

Die entsprechenden Java-Systemeigenschaften für die Proxykonfiguration werden im folgenden Befehlszeilenausschnitt angezeigt.

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

Wichtig

Um eine der HTTPS-Proxy-Systemeigenschaften verwenden zu können, muss die scheme Eigenschaft im Code auf gesetzt werden. https Wenn die Schemaeigenschaft nicht im Code festgelegt ist, verwendet das Schema standardmäßig HTTP und das SDK sucht nur nach http.* Systemeigenschaften.

Das äquivalente Setup, das Umgebungsvariablen verwendet, ist:

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