Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.
# Konfiguration von Service-Clients in AWS SDK for Java 2.x
Für den programmgesteuerten Zugriff AWS-Services verwendet das SDK for Java 2.x jeweils ein Client-Objekt. AWS-Service Wenn Ihre Anwendung beispielsweise auf Amazon EC2 zugreifen muss, erstellen Sie ein Amazon EC2 EC2-Client-Objekt — eine Instance der Klasse [Ec2Client — als Schnittstelle zu diesem Service](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/ec2/Ec2Client.html). Anschließend verwenden Sie den Service-Client, um Anfragen an dieses zu stellen. AWS-Service Für die meisten Anwendungen können Sie eine [Singleton-Instanz eines Service-Clients](singleton-service-clients.md) verwenden.
Es gibt viele Möglichkeiten, das SDK-Verhalten zu konfigurieren, aber letztlich hat alles mit dem Verhalten von Service-Clients zu tun. Jede Konfiguration hat keine Wirkung, bis Ihr Code einen Service-Client erstellt, der die Konfiguration verwendet.
Beispiele für die Konfiguration, die Sie bereitstellen, sind:
+ Wie sich Ihr Code authentifiziert AWS , wenn Sie einen Dienst aufrufen
+ Den AWS-Region Sie möchten, dass ein Service-Client verwendet
+ Einstellungen für Wiederholungsversuche und Timeout für Serviceanrufe
+ HTTP-Proxykonfiguration
Einstellungen, Funktionen [AWS SDKs und andere grundlegende Konzepte, die vielen der Tools gemeinsam sind, finden Sie im Referenzhandbuch](https://docs.aws.amazon.com/sdkref/latest/guide/) und im Tools-Referenzhandbuch. AWS SDKs
**Topics**
+ [Client-Konfiguration extern](configuring-service-clients-ext.md)
+ [Client-Konfiguration im Code](configuring-service-clients-code.md)
+ [Singleton-Serviceclients](singleton-service-clients.md)
+ [AWS-Region](region-selection.md)
+ [Anmeldeinformationsanbieter](credentials.md)
+ [Erneute Versuche](retry-strategy.md)
+ [Timeouts](timeouts.md)
+ [Beobachtbarkeit](observability.md)
+ [Endpunkte](endpoint-config.md)
+ [Konfigurieren Sie HTTP-Clients](http-configuration.md)
+ [Interzeptoren](interceptors.md)
# Konfiguration von Service-Clients für den AWS SDK for Java 2.x externen
Viele Konfigurationseinstellungen können außerhalb Ihres Codes bearbeitet werden. Wenn Sie die Konfiguration extern vornehmen, kann sie für alle Ihre Anwendungen im selben Java-Prozess gelten. Die meisten Konfigurationseinstellungen können entweder als Umgebungsvariablen, JVM-Systemeigenschaften oder in einer separaten gemeinsam genutzten AWS `config` Datei festgelegt werden. Die gemeinsam genutzte `config` Datei kann separate Einstellungssätze, sogenannte Profile, enthalten, um unterschiedliche Konfigurationen für verschiedene Umgebungen oder Tests bereitzustellen.
Die meisten Umgebungsvariablen und gemeinsam genutzten `config` Dateieinstellungen sind standardisiert und werden von allen AWS SDKs Tools gemeinsam genutzt, um konsistente Funktionen in verschiedenen Programmiersprachen und Anwendungen zu unterstützen. In den meisten Fällen spiegeln die JVM-Systemeigenschaften, die das SDK for Java verwenden kann, die Umgebungsvariablen wider.
Weitere Informationen zur Konfiguration Ihrer Anwendung mithilfe dieser *[Methoden AWS SDKs sowie Einzelheiten zu den einzelnen SDK-übergreifenden Einstellungen finden Sie im Referenzhandbuch](https://docs.aws.amazon.com/sdkref/latest/guide/overview.html)* und im Tools-Referenzhandbuch. Alle Einstellungen, die das SDK anhand der Umgebungsvariablen, der JVM-Systemeigenschaften oder der Konfigurationsdateien auflösen kann, finden Sie in der [Einstellungsreferenz im Referenzhandbuch AWS](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html) *SDKs und im Tools-Referenzhandbuch*.
## Kette von Konfigurationsanbietern für die Client-Konfiguration
Das SDK sucht an mehreren Stellen (oder Quellen) nach Konfigurationswerten.
1. Jede explizite Einstellung, die im Code oder auf einem Service-Client selbst festgelegt ist, hat Vorrang vor allen anderen Einstellungen.
1. JVM-Systemeigenschaften
+ Einzelheiten zur Einstellung der JVM-Systemeigenschaften finden Sie unter [So legen Sie JVM-Systemeigenschaften fest](https://docs.aws.amazon.com/sdkref/latest/guide/jvm-system-properties.html#jvm-sys-props-set) im Referenzhandbuch *AWS SDKs und im Tools-Referenzhandbuch*.
1. Umgebungsvariablen
+ Einzelheiten zur Einstellung von Umgebungsvariablen finden Sie unter [Umgebungsvariablen](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html) im Referenzhandbuch *AWS SDKs und im Tools-Referenzhandbuch.*
+ Beachten Sie, dass Sie Umgebungsvariablen für eine Shell auf verschiedenen Gültigkeitsebenen konfigurieren können: systemweit, benutzerweit und für eine bestimmte Terminalsitzung.
1. Geteilte Dateien und Dateien `config` `credentials`
+ Einzelheiten zum Einrichten dieser Dateien finden Sie im *Referenzhandbuch „[Gemeinsam genutzte `config``credentials` Dateien](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html)“AWS SDKs und „Tools*“.
1. Jeder vom SDK-Quellcode selbst bereitgestellte Standardwert wird zuletzt verwendet.
+ Für einige Eigenschaften, z. B. Region, gibt es keine Standardeinstellung. Sie müssen sie entweder explizit im Code, in einer Umgebungseinstellung oder in der gemeinsam genutzten `config` Datei angeben. Wenn das SDK die erforderliche Konfiguration nicht auflösen kann, können API-Anfragen zur Laufzeit fehlschlagen.
Neben dieser allgemeinen Konfigurationskette verwendet das SDK for Java 2.x auch spezialisierte Anbieterketten, darunter die [Credentials Provider Chain](credentials-chain.md) und die [AWS-Region Provider Chain](region-selection.md#default-region-provider-chain). Diese spezialisierten Ketten fügen zusätzliche Anbieter hinzu, die die Umgebung berücksichtigen, in der das SDK ausgeführt wird. Zum Beispiel in einem Container oder einer EC2-Instance.
## Erstellen Sie einen Service-Client, der mit externen Einstellungen konfiguriert wurde
Sie müssen in Ihrer Anwendung einen Service-Client erstellen, um mit einem zu kommunizieren AWS-Service. Serviceclients sind Ihre wichtigste Verbindung zu AWS-Services ihnen. Sie kümmern sich um alle komplexen Kommunikationsdetails, sodass Sie sich keine Gedanken über sie machen müssen. Sie kümmern sich automatisch um wichtige Aufgaben wie Sicherheit, Fehlerbehandlung und Wiederholungen, sodass Sie sich auf die Erstellung Ihrer Anwendung konzentrieren können, anstatt sich um technische Komplikationen zu kümmern.
### Verwenden Sie die Methode `create()`
Wenn alle benötigten Konfigurationseinstellungen aus externen Quellen stammen, können Sie mit einer einfachen Methode einen Service-Client erstellen:
```
S3Client s3Client = S3Client.create();
```
Der vorherige Codeausschnitt erstellt eine Instanz`S3Client`. Während der Erstellung durchsucht das SDK die Kette der Konfigurationsanbieter nach Einstellungen. Sobald das SDK einen Einstellungswert gefunden hat, wird der Wert auch dann verwendet, wenn eine Konfiguration existiert, die sich später in der Kette befindet.
Nehmen wir beispielsweise an, ein Benutzer legt die JVM-Einstellung für fest, AWS-Region indem er die Systemeigenschaft `-Daws.region=us-west-2` festlegt. Wenn die `AWS_REGION` Umgebungsvariable ebenfalls gesetzt ist, wird ihr Wert ignoriert.
Die standardmäßige Anbieterkette für Regionen und die Anbieterkette für Standardanmeldedaten werden ebenfalls im Erstellungsprozess verwendet. Irgendwo in der Kette muss das SDK die AWS-Region zu verwendenden Einstellungen auflösen und Einstellungen finden, die es ermöglichen, Anmeldeinformationen für Signieranfragen abzurufen. Wenn die SDKs Dateien diese Werte finden, schlägt die Client-Erstellung fehl.
Sie können zwar mit diesem leeren Builder-Muster einen Client erstellen, aber Sie verwenden dieses Muster [in der Regel, wenn Sie dem Code eine Konfiguration hinzufügen](configuring-service-clients-code.md#conf-service-client-code-basic) möchten.
## SDK for Java 2.x-Umgebungsvariablen und JVM-Systemeigenschaften
Neben den [SDK-übergreifenden Einstellungen](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html#settingsPages), die von den meisten unterstützt werden AWS SDKs, bietet das SDK for Java 2.x die folgenden Einstellungen.
**Anmerkung**
Diese Umgebungsvariablen und JVM-Systemeigenschaften sind in erster Linie für erweiterte Anwendungsfälle, Tests oder spezifische Bereitstellungsszenarien vorgesehen. In den meisten Anwendungscodes ist es vorzuziehen, die programmatischen Konfigurationsoptionen zu verwenden, die von den Client-Buildern des SDK bereitgestellt werden, um die Typsicherheit und IDE-Unterstützung zu verbessern.
### Umgebungsvariablen des Container-Anmeldeinformationsanbieters
Zusätzlich zu den im Referenzhandbuch dokumentierten Standard-Umgebungsvariablen für Container-Anmeldeinformationen unterstützt das SDK auch:
`AWS_CONTAINER_SERVICE_ENDPOINT`— Diese Umgebungsvariable gibt den Endpunkt für den Container-Metadatendienst an, wenn der Anbieter für Container-Anmeldeinformationen verwendet wird.
Java-Systemeigenschaft: `aws.containerServiceEndpoint`
Standardwert: `http://169.254.170.2`
### Umgebungsvariablen für die Implementierung des HTTP-Clients
`SYNC_HTTP_SERVICE_IMPL`— Identifiziert explizit die standardmäßige [synchrone HTTP-Implementierung](http-configuration.md#http-config-sync), die das SDK verwenden wird. Dies ist nützlich, wenn der Klassenpfad mehrere Implementierungen enthält, oder zur Leistungsoptimierung, da für die Implementierungserkennung ein Scannen des Klassenpfads erforderlich ist.
Java-Systemeigenschaft: `software.amazon.awssdk.http.service.impl`
`ASYNC_HTTP_SERVICE_IMPL`— Identifiziert explizit die standardmäßige [asynchrone HTTP-Implementierung](http-configuration.md#http-config-async), die das SDK verwenden wird. Dies ist nützlich, wenn der Klassenpfad mehrere Implementierungen enthält, oder zur Leistungsoptimierung, da für die Implementierungserkennung ein Scannen des Klassenpfads erforderlich ist.
Java-Systemeigenschaft: `software.amazon.awssdk.http.async.service.impl`
# Konfiguration von Service-Clients im Code für den AWS SDK for Java 2.x
Als Alternative oder zusätzlich zur [externen Konfiguration von Service-Clients](configuring-service-clients-ext.md) können Sie sie programmgesteuert im Code konfigurieren.
Durch die Konfiguration von Service-Clients im Code erhalten Sie eine detaillierte Kontrolle über die vielen Optionen, die Ihnen zur Verfügung stehen. Die meisten Konfigurationen, die Sie extern festlegen können, stehen Ihnen auch zur Verfügung, um sie im Code festzulegen.
## Grundkonfiguration im Code
Der folgende Codeausschnitt setzt beispielsweise den AWS-Region Wert `EU_SOUTH_2` für einen Amazon S3-Serviceclient im Code:
```
S3Client s3Client = S3Client.builder()
.region(Region.EU_SOUTH_2)
.build();
```
Das vorherige Snippet zeigt die statische Factory-Methode,. `builder()` Die `builder()` Methode gibt ein `builder` Objekt zurück, mit dem Sie den Service-Client anpassen können. Die Fluent-Setter-Methoden geben das `builder` Objekt — in diesem Fall eine [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3ClientBuilder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3ClientBuilder.html)Instanz — zurück, sodass Sie die Methodenaufrufen der Einfachheit halber und für besser lesbaren Code verketten können. Nachdem Sie die gewünschten Eigenschaften konfiguriert haben, rufen Sie die Methode auf, um den Client zu erstellen. `build()`
## Erweiterte Konfiguration im Code
Der folgende Ausschnitt zeigt zusätzliche Konfigurationsoptionen:
```
ClientOverrideConfiguration clientOverrideConfiguration =
ClientOverrideConfiguration.builder()
.apiCallAttemptTimeout(Duration.ofSeconds(1))
.addMetricPublisher(CloudWatchMetricPublisher.create())
.build();
S3Client s3Client = S3Client.builder()
.region(Region.EU_SOUTH_2)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.overrideConfiguration(clientOverrideConfiguration)
.httpClientBuilder(
ApacheHttpClient.builder()
.maxConnections(100)
.connectionTimeout(Duration.ofSeconds(5))
.proxyConfiguration(ProxyConfiguration.builder()
.endpoint(URI.create("http://proxy:8080"))
.build())
).build();
```
Im vorherigen Snippet sehen Sie mehrere Einstiegspunkte für die Konfiguration eines Service-Clients:
+ [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/client/config/ClientOverrideConfiguration.Builder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/client/config/ClientOverrideConfiguration.Builder.html), das Konfigurationsoptionen bereitstellt, die allen Service-Clients gemeinsam sind. Bei diesen Einstellungen handelt es sich um AWS spezifische Verhaltensweisen, die unabhängig von einer HTTP-Implementierung sind.
+ **HTTP-Clientkonfiguration über eine separate HTTP-Client-Builder-Implementierung.** Das `ApacheHttpClient.Builder` ist ein Beispiel. Der Service-Client stellt die `httpClientBuilder()` Methode bereit, um den konfigurierten HTTP-Client dem Service-Client zuzuordnen.
+ **Methoden im [Client-Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3ClientBuilder.html) selbst,** wie `region()` und `credentialsProvider()`
### Dieselbe Konfiguration unter Verwendung von Konfigurationsblöcken
Anstatt separate Objekte zu erstellen und sie dann an Service-Client-Methoden zu übergeben, AWS SDK for Java 2.x bietet der Methoden, die Lambda-Ausdrücke akzeptieren, um diese Objekte inline zu erstellen. Die Konfigurationsmethoden im Builder haben denselben Namen, haben jedoch unterschiedliche Signaturen. Beispiel:
+ [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/client/builder/SdkClientBuilder.html#overrideConfiguration(software.amazon.awssdk.core.client.config.ClientOverrideConfiguration)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/client/builder/SdkClientBuilder.html#overrideConfiguration(software.amazon.awssdk.core.client.config.ClientOverrideConfiguration))
+ [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/client/builder/SdkClientBuilder.html#overrideConfiguration(java.util.function.Consumer)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/client/builder/SdkClientBuilder.html#overrideConfiguration(java.util.function.Consumer))
Die zuvor mit diesem Ansatz gezeigte Konfiguration des S3-Clients kann in einem Codeblock erfolgen:
```
S3Client s3Client = S3Client.builder()
.region(Region.EU_SOUTH_2)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.overrideConfiguration(b -> b
.apiCallAttemptTimeout(Duration.ofSeconds(1))
.addMetricPublisher(CloudWatchMetricPublisher.create()))
.httpClientBuilder(ApacheHttpClient.builder()
.maxConnections(100)
.connectionTimeout(Duration.ofSeconds(5))
.proxyConfiguration(ProxyConfiguration.builder()
.endpoint(URI.create("http://proxy:8080"))
.build()))
.build();
```
## Konfigurationsoptionen sind im Code nicht verfügbar
Da sich die folgenden Einstellungen auf grundlegende Initialisierungsprozesse im SDK auswirken, können Sie die folgenden Konfigurationseinstellungen nur extern und nicht im Code festlegen:
### Einstellungen für den Speicherort der Datei
Diese Einstellungen steuern den Speicherort der gemeinsam genutzten Konfigurations- und Anmeldeinformationsdateien und können nicht programmgesteuert außer Kraft gesetzt werden, nachdem das SDK sie geladen hat:
+ **AWS\$1CONFIG\$1FILE (Umgebungsvariable)/**aws.ConfigFile**** (JVM-Systemeigenschaft)
+ **AWS\$1SHARED\$1CREDENTIALS\$1FILE (Umgebungsvariable****)/aws. sharedCredentialsFile** (JVM-Systemeigenschaft)
Diese Einstellungen müssen festgelegt werden, bevor das SDK die Konfigurationsdateien lädt, da sie bestimmen, wo das SDK nach der Konfiguration sucht. Sobald das SDK initialisiert wurde, hat eine Änderung dieser Werte keine Auswirkung.
### Deaktivierung des Instanz-Metadatendienstes
+ **AWS\$1EC2\$1METADATA\$1DISABLED** **(Umgebungsvariable)/aws.DisableEC2Metadata (JVM-Systemeigenschaft)**
Diese Einstellung steuert, ob das SDK versucht, den EC2-Instanz-Metadatendienst überhaupt zu verwenden. Sobald das SDK initialisiert wurde, können Sie diese Einstellung nicht programmgesteuert ändern.
### Profilauswahl
+ **AWS\$1PROFILE**(Umgebungsvariable)/**aws.profile** (JVM-Systemeigenschaft)
Diese Einstellung teilt dem SDK mit, welches Profil aus den gemeinsam genutzten Konfigurations- und Anmeldeinformationsdateien geladen werden soll. Nach dem Laden hat die Änderung dieses Werts keine Auswirkung.
### Pfade für Container-Anmeldeinformationen
+ **AWS\$1CONTAINER\$1CREDENTIALS\$1RELATIVE\$1URI**
+ **AWS\$1CONTAINER\$1CREDENTIALS\$1VOLLSTÄNDIGER\$1URI**
+ **AWS\$1CONTAINER\$1AUTORISIERUNGSTOKEN**
+ **AWS\$1CONTAINER\$1AUTORISIERUNGSTOKEN-DATEI**
Sie verwenden diese Umgebungsvariablen, um dem SDK mitzuteilen, wie Anmeldeinformationen von Containerdiensten abgerufen werden sollen. Nachdem die Anmeldeinformationsanbieterkette während der Initialisierung des Service Clients eingerichtet wurde, können Sie diese Einstellungen nicht mehr ändern.
### Auswahl der standardmäßigen HTTP-Implementierung
+ **SYNC\$1HTTP\$1SERVICE\$1IMPL (Umgebungsvariable)/software.amazon.awssdk.http.service.impl** **(JVM-Systemeigenschaft)**
+ **ASYNC\$1HTTP\$1SERVICE\$1IMPL** (Umgebungsvariable)/**software.amazon.awssdk.http.async.service.impl** (JVM-Systemeigenschaft)
Diese globalen Einstellungen bestimmen, welche HTTP-Client-Implementierung das SDK für alle Service-Clients verwendet, sofern sie nicht im Code für einzelne Service-Clients überschrieben werden. Sie müssen diese Einstellungen festlegen, bevor das SDK seine HTTP-Clients initialisiert. Sie können danach nicht mehr geändert werden.
# Verwenden Sie Singleton Service Client-Instanzen mit dem AWS SDK for Java 2.x
Die Service-Clients in der AWS SDK for Java 2.x sind threadsicher. Sie können für jeden Service-Client eine Instanz erstellen und diese in Ihrer gesamten Anwendung wiederverwenden. Dieser Ansatz verbessert die Leistung und verwaltet Ressourcen effizienter.
## Vorteile von Singleton Service Clients
Verbindungspooling
Service-Clients verwalten interne HTTP-Verbindungspools. Das Erstellen und Löschen dieser Pools ist teuer. Wenn Sie Clients wiederverwenden, werden diese Pools effizient von allen Anfragen gemeinsam genutzt.
Reduzierter Initialisierungsaufwand
Das Erstellen eines Clients umfasst das Laden der Konfiguration, das Einrichten von Anmeldeinformationen und das Initialisieren interner Komponenten. Singleton-Instanzen eliminieren diesen Overhead.
Bessere Ressourcennutzung
Singleton-Clients verhindern die Erschöpfung von Ressourcen, die auftreten kann, wenn Sie viele Client-Instanzen erstellen.
## Erstellen und verwenden Sie Singleton-Serviceclients
Das folgende Beispiel zeigt, wie Singleton-Serviceclients erstellt und verwendet werden:
```
// Create one instance and use it throughout the application.
public class ServiceClientSource {
private static final S3Client s3Client = S3Client.create();
public static S3Client getS3Client() {
return s3Client;
}
}
```
Erstellen Sie nicht für jeden Vorgang neue Clients:
```
// This approach creates unnecessary overhead.
public void badExample() {
try (S3Client s3 = S3Client.create()) {
s3.listBuckets();
}
}
```
## Wichtige Überlegungen
+ Service-Clients sind Thread-sicher. Sie können sie sicher über mehrere Threads hinweg teilen.
+ Schließen Sie Clients nur, wenn Ihre Anwendung heruntergefahren wird oder wenn Sie den Client nicht mehr benötigen. Verwenden Sie `client.close()` oder try-with-resources auf Anwendungsebene.
+ Wenn Sie unterschiedliche Konfigurationen wie Regionen oder Anmeldeinformationen benötigen, erstellen Sie separate Singleton-Instanzen für jede Konfiguration.
Wenn Sie Dependency Injection-Frameworks wie Spring verwenden, konfigurieren Sie Service-Clients als Singleton-Beans. Dies gewährleistet ein ordnungsgemäßes Lebenszyklusmanagement.
# Einstellung der AWS-Region für AWS SDK for Java 2.x
SDK-Clients stellen eine Verbindung zu einem bestimmten AWS-Service in einem bestimmten Bereich her AWS-Region , den Sie bei der Erstellung des Clients angeben. Diese Konfiguration ermöglicht es Ihrer Anwendung, mit AWS Ressourcen in diesem geografischen Gebiet zu interagieren. Wenn Sie einen Service-Client erstellen, ohne explizit eine Region festzulegen, verwendet das SDK die Standardregion aus Ihrer externen Konfiguration.
## Konfigurieren Sie explizit ein AWS-Region
Um eine Region explizit festzulegen, empfehlen wir, die in der [Region-Klasse](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/regions/Region.html) definierten Konstanten zu verwenden. Dabei handelt es sich um eine Aufzählung aller öffentlich verfügbaren Regionen.
Verwenden Sie die Methode des Client Builders, um einen Client mit einer aufgezählten Region aus der Klasse zu erstellen. `region`
```
Ec2Client ec2 = Ec2Client.builder()
.region(Region.US_WEST_2)
.build();
```
Wenn die Region, die Sie verwenden möchten, keine der Aufzählungen in der `Region` Klasse ist, können Sie mithilfe der statischen Methode eine neue Region erstellen. `of` Mit dieser Methode können Sie auf neue Regionen zugreifen, ohne das SDK aktualisieren zu müssen.
```
Region newRegion = Region.of("us-east-42");
Ec2Client ec2 = Ec2Client.builder()
.region(newRegion)
.build();
```
**Anmerkung**
Nachdem Sie einen Client mit dem Builder erstellt haben, ist er *unveränderlich* und AWS-Region *kann nicht geändert werden*. Wenn Sie mit mehreren AWS-Regionen für denselben Service arbeiten müssen, sollten Sie mehrere Clients erstellen — einen pro Region.
## Lassen Sie das SDK den Standard automatisch anhand der Umgebung AWS-Region ermitteln
Wenn Ihr Code auf Amazon EC2 oder ausgeführt wird AWS Lambda, möchten Sie möglicherweise Clients so konfigurieren, AWS-Region dass sie dasselbe verwenden, auf dem Ihr Code ausgeführt wird. Dadurch wird Ihr Code von der Umgebung entkoppelt, in der er ausgeführt wird, und es ist einfacher, Ihre Anwendung AWS-Regionen für mehrere Anwendungen bereitzustellen, um Latenz oder Redundanz zu reduzieren.
Verwenden Sie die Methode des Client Builders, um die Region anhand der AWS-Region Standardanbieterkette von der Umgebung zu bestimmen. `create`
```
Ec2Client ec2 = Ec2Client.create();
```
Sie können den Client auch auf andere Weise konfigurieren, aber nicht die Region festlegen. Das SDK übernimmt das AWS-Region mithilfe der standardmäßigen Anbieterkette für die Region:
```
Ec2Client ec2Client = Ec2Client.builder()
.credentialsProvider(ProfileCredentialsProvider.builder()
.profileName("my-profile")
.build())
.build();
```
Wenn Sie AWS-Region mithilfe der `region` Methode nicht explizit eine festlegen, verwendet das SDK die Standardregion-Providerkette, um die zu verwendende Region zu ermitteln.
### Grundlegendes zur AWS-Region Standardanbieterkette
**Das SDK unternimmt die folgenden Schritte, um nach einem zu suchen AWS-Region:**
1. Jede explizite Region, die mithilfe der `region` Methode im Builder selbst festgelegt wurde, hat Vorrang vor allem anderen.
1. Das SDK sucht nach der JVM-Systemeigenschaft `aws.region` und verwendet ihren Wert, falls er gefunden wird.
1. Die Umgebungsvariable `AWS_REGION` wird geprüft. Wenn es gesetzt ist, wird diese Region zur Konfiguration des Clients verwendet.
**Anmerkung**
Der Lambda Container legt diese Umgebungsvariable fest.
1. Das SDK überprüft das aktive Profil in den [AWS gemeinsam genutzten Konfigurations- und Anmeldeinformationsdateien](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html). Wenn die `region` Eigenschaft vorhanden ist, verwendet das SDK sie.
Das `default` Profil ist das aktive Profil, sofern es nicht durch eine `AWS_PROFILE` Umgebungsvariable oder eine `aws.profile` JVM-Systemeigenschaft überschrieben wird. Wenn das SDK die `region` Eigenschaft in beiden Dateien für dasselbe Profil (einschließlich des Profils) findet, verwendet das `default` SDK den Wert in der Datei mit den gemeinsamen Anmeldeinformationen.
1. Das SDK versucht, den Amazon EC2 Instanz-Metadatendienst (IMDS) zu verwenden, um die Region der aktuell laufenden Amazon EC2 Instanz zu ermitteln.
+ Aus Sicherheitsgründen sollten Sie verhindern, dass das SDK versucht, Version 1 von IMDS zu verwenden. Sie verwenden dieselbe Einstellung, um Version 1 zu deaktivieren, die im [Besorgen Sie sich auf sichere Weise Anmeldeinformationen für IAM-Rollen](ec2-iam-roles.md#securely-read-IAM-role_credentials) Abschnitt beschrieben wird.
1. Wenn das SDK bis zu diesem Zeitpunkt immer noch keine Region gefunden hat, schlägt die Client-Erstellung mit einer Ausnahme fehl.
Bei der Entwicklung von AWS Anwendungen besteht ein gängiger Ansatz darin, die *gemeinsam genutzte Konfigurationsdatei* zu verwenden, um die Region für die lokale Entwicklung festzulegen, und sich auf die Standardregions-Providerkette zu verlassen, um die Region zu bestimmen, wenn die Anwendung in der AWS Infrastruktur ausgeführt wird. Dies vereinfacht die Client-Erstellung stark und sorgt dafür, dass Ihre Anwendung portabel bleibt.
## Prüfen Sie, ob ein Dienst in einer Region verfügbar ist
Verwenden Sie die statische `serviceMetadata` Methode auf einem Service-Client, um festzustellen, ob ein bestimmter Artikel in einer Region verfügbar AWS-Service ist:
```
DynamoDbClient.serviceMetadata().regions().forEach(System.out::println);
```
Das vorherige Snippet druckt eine lange Liste von AWS-Region Codes aus, die den DynamoDB-Dienst haben:
```
af-south-1
ap-east-1
ap-northeast-1
ap-northeast-2
ap-northeast-3
ap-south-1
ap-south-2
ap-southeast-1
...
```
Sie können einen Code verwenden, um die [Region-Klassenaufzählung für die Region](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/regions/Region.html) nachzuschlagen, die Ihr Service-Client verwenden soll.
Wenn Sie beispielsweise mit DynamoDB in der Region mit dem Code arbeiten möchten`ap-northeast-2`, erstellen Sie Ihren DynamoDB-Client mit mindestens der folgenden Konfiguration:
```
DynamoDbClient ddb = DynamoDbClient.builder()
.region(Region.AP_NORTHEAST_2)
.build();
```
## Wählen Sie einen bestimmten Endpunkt
In bestimmten Situationen, z. B. um Vorschaufunktionen eines Dienstes zu testen, bevor die Funktionen allgemein verfügbar sind, müssen Sie möglicherweise einen bestimmten Endpunkt in einer Region angeben. In diesen Situationen können Service-Clients durch Aufrufen der Methode konfiguriert werden. `endpointOverride`
Um beispielsweise einen Amazon EC2 Client so zu konfigurieren, dass er die Region Europa (Irland) mit einem bestimmten Endpunkt verwendet, verwenden Sie den folgenden Code.
```
Ec2Client ec2 = Ec2Client.builder()
.region(Region.EU_WEST_1)
.endpointOverride(URI.create("https://ec2.eu-west-1.amazonaws.com"))
.build();
```
Die aktuelle Liste der [Regionen und der entsprechenden Endpunkte](https://docs.aws.amazon.com/general/latest/gr/rande.html) für alle AWS Dienste finden Sie unter Regionen und Endpunkte.
# Verwenden von Anmeldeinformationsanbietern in der AWS SDK for Java 2.x
Die Rolle eines Anbieters von Anmeldeinformationen in der AWS SDK for Java 2.x besteht darin, Anmeldeinformationen für die Kunden des AWS-Service SDK zu beschaffen und bereitzustellen. Das SDK verwendet die Anmeldeinformationen, die es bezieht, um sich beim Dienst zu authentifizieren, indem es jede Anfrage kryptografisch signiert. Anmeldeinformationen bestehen normalerweise aus Zugriffsschlüsseln — einer Zugriffsschlüssel-ID und einem geheimen Zugriffsschlüssel zusammen.
Wenn Sie temporäre Anmeldeinformationen verwenden, die beispielsweise verwendet werden, wenn Sie die [Konfiguration des SSO-Token-Anbieters](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#sso-token-config) einrichten oder Ihre Laufzeit so konfigurieren, dass sie [eine IAM (AWS Identity and Access Management) -Rolle annimmt](https://docs.aws.amazon.com/sdkref/latest/guide/access-assume-role.html#credOrSourceAssumeRole), wird den Zugriffsschlüsseln ein Sitzungstoken hinzugefügt, das einen zeitlich begrenzten Zugriff auf Ressourcen ermöglicht. AWS
In diesem Thema werden verschiedene Möglichkeiten beschrieben, wie Sie dem SDK den Zugriff auf Anmeldeinformationen ermöglichen.
**Topics**
+ [Interaktive Entwicklungsarbeit](credentials-temporary.md)
+ [Anbieterkette für Standardanmeldeinformationen](credentials-chain.md)
+ [Zwischenspeichern von Anmeldeinformationen](credential-caching.md)
+ [Geben Sie einen bestimmten Anbieter für Anmeldeinformationen an](credentials-providers.md)
+ [Verwenden Sie gemeinsam genutzte Konfigurationsprofile](credentials-profiles.md)
+ [Verwenden Sie einen externen Prozess](credentials-process.md)
+ [Geben Sie Anmeldeinformationen im Code ein](credentials-explicit.md)
+ [Lesen Sie die Anmeldeinformationen für IAM-Rollen auf Amazon EC2](ec2-iam-roles.md)
# Zugangsdaten für interaktive Entwicklungsarbeiten mit AWS SDK for Java 2.x
Um die Sicherheit zu erhöhen, AWS empfiehlt es sich, das SDK for Java so zu konfigurieren, dass [temporäre Anmeldeinformationen anstelle von langlebigen Anmeldeinformationen verwendet](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-users-federation-idp) werden. Temporäre Anmeldeinformationen bestehen aus Zugriffsschlüsseln (Zugriffsschlüssel-ID und geheimer Zugriffsschlüssel) und einem Sitzungstoken.
Für die Arbeit mit temporären Anmeldeinformationen stehen Ihnen mehrere Methoden zur Verfügung. Der von Ihnen verwendete Ansatz und damit die Konfiguration, die Sie dem SDK zur Verfügung stellen, hängen von Ihrem Anwendungsfall ab.
Wenn Sie interaktive Entwicklungsarbeiten mit dem Java-SDK durchführen, empfehlen wir Ihnen, die Anmeldeinformationen für die AWS Konsole zu verwenden.
## Verwenden Sie die Anmeldeinformationen für die Konsole
Sie können Ihre vorhandenen Anmeldedaten für die AWS Management Console für den programmgesteuerten Zugriff AWS auf Dienste verwenden. AWS Generiert nach einem browserbasierten Authentifizierungsablauf temporäre Anmeldeinformationen, die in allen lokalen Entwicklungstools wie dem AWS CLI und dem SDK for Java 2.x funktionieren.
Bei diesem Prozess können Sie sich mit Root-Anmeldeinformationen, die bei der ersten Kontoeinrichtung erstellt wurden, mit einem IAM-Benutzer oder mit einer föderierten Identität von Ihrem Identitätsanbieter authentifizieren, der die temporären Anmeldeinformationen AWS CLI automatisch für Sie verwaltet. Dieser Ansatz erhöht die Sicherheit, da die Notwendigkeit entfällt, langfristige Anmeldeinformationen lokal zu speichern.
Wenn Sie den `aws login` Befehl ausführen, können Sie aus Ihren aktiven Konsolensitzungen wählen oder sich über den browserbasierten Authentifizierungsablauf anmelden. Dabei werden automatisch temporäre Anmeldeinformationen generiert. Das SDK for Java 2.x aktualisiert diese Anmeldeinformationen automatisch für bis zu 12 Stunden.
**Wichtig**
Zusätzlich zu der Konfiguration, die Sie in der gemeinsam genutzten Konfigurationsdatei festgelegt haben und die für alle Projekte funktioniert, erfordert jedes einzelne Java-Projekt die folgende Abhängigkeit in der `pom.xml` Maven-Datei:
```
software.amazon.awssdksignin
```
Die `signin` Abhängigkeit stellt den Code bereit, der es dem SDK for Java 2.x ermöglicht, auf die Anmeldeinformationen für die Konsole zuzugreifen und diese zu verwenden.
Weitere Informationen zu den Voraussetzungen, zum An- und Abmelden finden Sie im *AWS SDK* - und Tools-Referenzhandbuch unter [Anmeldung für die AWS lokale Entwicklung mithilfe von Konsolenanmeldedaten](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html).
## Single-sign-on Ansatz
Wenn Sie interaktive Entwicklungsarbeiten mit dem Java SDK durchführen, können Sie alternativ den Single-Sign-On-Ansatz verwenden. Für diesen Ansatz ist das folgende Setup erforderlich:
+ [Einrichtung über das IAM Identity Center](get-started-auth.md#setup-auth)
+ [Konfigurieren Sie ein Profil in der AWS gemeinsam genutzten Konfigurationsdatei](get-started-auth.md#setup-credentials)
+ Verwenden Sie den Befehl AWS CLI und [führen Sie einen Befehl aus](get-started-auth.md#setup-login-sso), um sich anzumelden und eine aktive Sitzung zu erstellen
### IAM Identity Center-Konfiguration
Wenn Sie das SDK für die Verwendung des IAM Identity Center Single Sign-On-Zugriffs konfigurieren, wie [Übersicht über die Einrichtung](setup.md#setup-overview) in diesem Handbuch beschrieben, verwendet das SDK temporäre Anmeldeinformationen.
Das SDK verwendet das IAM Identity Center-Zugriffstoken, um Zugriff auf die IAM-Rolle zu erhalten, die mit der `sso_role_name` Einstellung in Ihrer Datei konfiguriert ist. `config` Das SDK übernimmt diese IAM-Rolle und ruft temporäre Anmeldeinformationen ab, um Anfragen zu signieren. AWS-Service
Weitere Informationen darüber, wie das SDK temporäre Anmeldeinformationen aus der Konfiguration bezieht, finden Sie im Abschnitt [Grundlegendes zur IAM Identity Center-Authentifizierung](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html) im Referenzhandbuch AWS SDKs zu Tools.
**Wichtig**
Zusätzlich zu der Konfiguration, die Sie in der gemeinsam genutzten `config` Datei festgelegt haben und die für alle Projekte funktioniert, erfordert jedes einzelne Java-Projekt die folgenden Abhängigkeiten in der `pom.xml` Maven-Datei:
```
software.amazon.awssdkssosoftware.amazon.awssdkssooidc
```
Die `ssooidc` Abhängigkeiten `sso` und stellen den Code bereit, der es dem SDK for Java 2.x ermöglicht, auf temporäre Anmeldeinformationen zuzugreifen.
### Rufen Sie temporäre Anmeldeinformationen aus dem AWS Zugriffsportal ab
Als Alternative zur Single-Sign-On-Konfiguration von IAM Identity Center können Sie die temporären Anmeldeinformationen, die im AWS Access Portal verfügbar sind, kopieren und verwenden. Sie können die temporären Anmeldeinformationen in einem Profil verwenden oder sie als Werte für Systemeigenschaften und Umgebungsvariablen verwenden.
**Richten Sie eine lokale Anmeldeinformationsdatei für temporäre Anmeldeinformationen ein**
1. [Erstellen Sie eine Datei mit gemeinsamen Anmeldeinformationen](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html)
1. Fügen Sie in die Anmeldeinformationsdatei den folgenden Platzhaltertext ein, bis Sie funktionierende temporäre Anmeldeinformationen einfügen.
```
[default]
aws_access_key_id=
aws_secret_access_key=
aws_session_token=
```
1. Speichern Sie die Datei. Die Datei `~/.aws/credentials` sollte jetzt auf Ihrem lokalen Entwicklungssystem vorhanden sein. Diese Datei enthält das [[Standard] -Profil](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-profile), das das SDK for Java verwendet, wenn kein bestimmtes benanntes Profil angegeben ist.
1. [Melden Sie sich beim AWS Access-Portal an](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtosignin.html)
1. Folgen Sie diesen Anweisungen unter der Überschrift [Manuelle Aktualisierung der Anmeldeinformationen](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtogetcredentials.html#how-to-get-temp-credentials), um die Anmeldeinformationen für die IAM-Rolle aus dem AWS Zugriffsportal zu kopieren.
1. Wählen Sie für Schritt 2 der verlinkten Anweisungen den Namen der IAM-Rolle aus`Access keys`, der den Zugriff für Ihre Entwicklungsanforderungen gewährt. Diese Rolle hat normalerweise einen Namen wie **PowerUserAccess**oder **Developer**.
1. Wählen Sie im modalen Dialogfeld Ihr Betriebssystem aus und kopieren Sie den Inhalt von **Profil hinzufügen in Ihre AWS Anmeldeinformationsdatei**.
1. Fügen Sie die kopierten Anmeldeinformationen in Ihre lokale `credentials` Datei ein und entfernen Sie den generierten Profilnamen. Ihre Datei sollte wie folgt aussehen.
```
[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token=IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE
```
1. Speichern Sie die `credentials`-Datei.
Wenn das SDK for Java einen Service-Client erstellt, greift es auf diese temporären Anmeldeinformationen zu und verwendet sie für jede Anfrage. Die in Schritt 5a ausgewählten Einstellungen für die IAM-Rolle bestimmen, [wie lange die temporären Anmeldeinformationen gültig sind](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtosessionduration.html). Die maximale Dauer beträgt zwölf Stunden.
Wenn die temporären Anmeldeinformationen abgelaufen sind, wiederholen Sie die Schritte 4 bis 7.
# Anbieterkette für Standardanmeldedaten in der AWS SDK for Java 2.x
Die standardmäßige Anbieterkette für AWS Anmeldeinformationen in der sucht AWS SDK for Java 2.x automatisch an einer vordefinierten Reihenfolge von Speicherorten nach Anmeldeinformationen, sodass sich Anwendungen authentifizieren können, AWS-Services ohne dass die Quellen für Anmeldeinformationen explizit angegeben werden müssen.
Die standardmäßige Anbieterkette für Anmeldeinformationen wird von der [DefaultCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/DefaultCredentialsProvider.html)Klasse implementiert. Sie delegiert sequentiell an andere Implementierungen von Anbietern für Anmeldeinformationen, die an verschiedenen Stellen nach der Konfiguration suchen. Der erste Anbieter für Anmeldeinformationen, der alle erforderlichen Konfigurationselemente finden kann, bewirkt das Ende der Kette.
Um die standardmäßige Anbieterkette für Anmeldeinformationen zur Bereitstellung temporärer Anmeldeinformationen zu verwenden, erstellen Sie einen Service Client Builder, geben aber keinen Anbieter für Anmeldeinformationen an. Der folgende Codeausschnitt erstellt einen`DynamoDbClient`, der die standardmäßige Anbieterkette für Anmeldeinformationen verwendet, um Konfigurationseinstellungen zu finden und abzurufen.
```
// Any external Region configuration is overridden.
// The SDK uses the default credentials provider chain because no specific credentials provider is specified.
Region region = Region.US_WEST_2;
DynamoDbClient ddb =
DynamoDbClient.builder()
.region(region)
.build();
```
## Reihenfolge beim Abrufen der Anmeldeinformationseinstellungen
Die Anbieterkette für Standardanmeldedaten des SDK for Java 2.x sucht anhand einer vordefinierten Reihenfolge nach Konfigurationen in Ihrer Umgebung.
1. Java-Systemeigenschaften
+ Das SDK verwendet die [SystemPropertyCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/SystemPropertyCredentialsProvider.html)Klasse, um temporäre Anmeldeinformationen aus den `aws.accessKeyId` `aws.sessionToken` Java-Systemeigenschaften zu laden. `aws.secretAccessKey`
**Anmerkung**
Informationen zum Einstellen von Java-Systemeigenschaften finden Sie im Tutorial [Systemeigenschaften](https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html) auf der offiziellen Website der *Java-Tutorials*.
1. Umgebungsvariablen
+ Das SDK verwendet die [EnvironmentVariableCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/EnvironmentVariableCredentialsProvider.html)Klasse, um temporäre Anmeldeinformationen aus den `AWS_SESSION_TOKEN` Umgebungsvariablen `AWS_ACCESS_KEY_ID``AWS_SECRET_ACCESS_KEY`, und zu laden.
1. Web-Identitätstoken und IAM-Rollen-ARN
+ Das SDK verwendet die [WebIdentityTokenFileCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/WebIdentityTokenFileCredentialsProvider.html)Klasse, um Anmeldeinformationen zu laden, indem es mithilfe eines Web-Identitätstoken eine Rolle annimmt.
+ Der Anbieter für Anmeldeinformationen sucht nach den folgenden Umgebungsvariablen oder JVM-Systemeigenschaften:
+ `AWS_WEB_IDENTITY_TOKEN_FILE or aws.webIdentityTokenFile`
+ `AWS_ROLE_ARN` oder `aws.roleArn`
+ `AWS_ROLE_SESSION_NAME`oder `aws.roleSessionName` (optional)
+ Nachdem das SDK die Werte erfasst hat, ruft es AWS -Security-Token-Service (STS) auf und verwendet die temporären Anmeldeinformationen, die es zurückgibt, um Anfragen zu signieren.
+ Laufzeitumgebungen wie Amazon Elastic Kubernetes Service (EKS) stellen Web-Identitätstoken automatisch zur Verfügung AWS SDKs, sodass Anwendungen temporäre AWS Anmeldeinformationen abrufen können.
1. Die geteilten `credentials` Dateien und Dateien `config`
+ Das SDK verwendet die [ProfileCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ProfileCredentialsProvider.html), um IAM Identity Center Single Sign-On-Einstellungen oder temporäre Anmeldeinformationen aus dem `[default]` Profil in den gemeinsam genutzten `credentials` Dateien zu laden. `config`
Das AWS SDKs Referenzhandbuch zu Tools enthält [detaillierte Informationen](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html#idccredres) darüber, wie das SDK for Java mit dem IAM Identity Center Single Sign-On-Token zusammenarbeitet, um temporäre Anmeldeinformationen abzurufen, die das SDK zum Aufrufen verwendet. AWS-Services
**Anmerkung**
Die `config` Dateien `credentials` und werden von verschiedenen AWS SDKs Tools gemeinsam genutzt. Weitere Informationen finden Sie unter [The. aws/credentials and .aws/config](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html)Dateien im Referenzhandbuch AWS SDKs und im Tools-Referenzhandbuch.
+ Da ein Profil in den geteilten `config` Dateien `credentials` und Dateien viele verschiedene Einstellungen enthalten kann, werden die Benutzer an eine Reihe anderer Anbieter `ProfileCredentialsProvider` delegiert, um unter dem `[default]` Profil nach Einstellungen zu suchen:
+ **Anmeldeinformationen für Web-Identitätstoken** (Klasse`WebIdentityTokenCredentialsProvider`): Wenn das Profil `role_arn` und enthält`web_identity_token_file`.
+ **SSO-Anmeldeinformationen** (Klasse`SsoCredentialsProvider`): Wenn das Profil SSO-bezogene Eigenschaften wie`sso_role_name`, enthält. `sso_account_id`
+ **Rollenbasierte Anmeldeinformationen mit Quellprofil** (Klasse`StsAssumeRoleCredentialsProvider`): Wenn das Profil und enthält. `role_arn` `source_profile`
+ **Rollenbasierte Anmeldeinformationen mit Anmeldeinformationsquelle** (Klasse`StsAssumeRoleWithSourceCredentialsProvider`): Wenn das Profil und enthält. `role_arn` `credential_source`
+ Wann`credential_source = Environment`: Es verwendet eine Kette von und `SystemPropertyCredentialsProvider` `EnvironmentVariableCredentialsProvider`
+ Wann`credential_source = Ec2InstanceMetadata`: Es verwendet `InstanceProfileCredentialsProvider`
+ Wann`credential_source = EcsContainer`: Es verwendet `ContainerCredentialsProvider`
+ **Anmeldeinformationen für die Konsole** (Klasse`LoginCredentialsProvider`): Wenn das Profil Folgendes enthält `login_session`
+ **Prozessanmeldedaten** (Klasse`ProcessCredentialsProvider`): Wenn das Profil enthält`credential_process`.
+ **Sitzungsanmeldedaten** (Klasse`StaticSessionCredentialsProvider`): Wenn das Profil `aws_access_key_id``aws_secret_access_key`, und enthält`aws_session_token`.
+ **Grundlegende Anmeldeinformationen** (Klasse`StaticCredentialsProvider`): Wenn das Profil `aws_access_key_id` und enthält`aws_secret_access_key`.
1. Amazon ECS Anmeldeinformationen für Container
+ Das SDK verwendet die [ContainerCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ContainerCredentialsProvider.html)Klasse, um temporäre Anmeldeinformationen mithilfe der folgenden Umgebungsvariablen zu laden:
1. `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` oder `AWS_CONTAINER_CREDENTIALS_FULL_URI`
1. `AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE` oder `AWS_CONTAINER_AUTHORIZATION_TOKEN`
Der ECS-Container-Agent legt automatisch die `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` Umgebungsvariable fest, die auf den Endpunkt der ECS-Anmeldeinformationen verweist. Die anderen Umgebungsvariablen werden normalerweise in bestimmten Szenarien festgelegt, in denen der standardmäßige Endpunkt für ECS-Anmeldeinformationen nicht verwendet wird.
1. Amazon EC2 Von der IAM-Rolle bereitgestellte Anmeldeinformationen der Instanz
+ Das SDK verwendet die [InstanceProfileCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/InstanceProfileCredentialsProvider.html)Klasse, um temporäre Anmeldeinformationen aus dem Metadatendienst zu laden. Amazon EC2
1. Wenn das SDK die erforderlichen Konfigurationseinstellungen anhand der oben aufgeführten Schritte nicht finden kann, löst es eine Ausnahme mit einer Ausgabe ähnlich der folgenden aus:
```
software.amazon.awssdk.core.exception.SdkClientException: Unable to load credentials from any of the providers
in the chain AwsCredentialsProviderChain(credentialsProviders=[SystemPropertyCredentialsProvider(),
EnvironmentVariableCredentialsProvider(), WebIdentityTokenCredentialsProvider(), ProfileCredentialsProvider(),
ContainerCredentialsProvider(), InstanceProfileCredentialsProvider()])
```
## Verwenden Sie den `DefaultCredentialsProvider` Code
Sie können die standardmäßige Anbieterkette für Anmeldeinformationen explizit in Ihrem Code verwenden. Dies entspricht funktionell der Tatsache, dass Sie überhaupt keinen Anbieter für Anmeldeinformationen angeben, da das SDK `DefaultCredentialsProvider` standardmäßig verwendet. Wenn Sie ihn jedoch explizit verwenden, kann Ihr Code lesbarer und selbstdokumentierender werden. Es zeigt deutlich, dass Sie beabsichtigen, die standardmäßige Anmeldeinformationskette zu verwenden.
```
import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
public class ExplicitDefaultCredentialsExample {
public static void main(String[] args) {
// Explicitly create the DefaultCredentialsProvider.
DefaultCredentialsProvider defaultCredentialsProvider = DefaultCredentialsProvider
.builder().build();
// Use it with any service client.
S3Client s3Client = S3Client.builder()
.region(Region.US_WEST_2)
.credentialsProvider(defaultCredentialsProvider)
.build();
// Now you can use the client with the default credentials chain.
s3Client.listBuckets();
}
}
```
Wenn Sie den Standardanmeldeanmeldeanbieter erstellen, können Sie weitere Konfigurationen bereitstellen:
```
DefaultCredentialsProvider customizedProvider = DefaultCredentialsProvider.builder()
.profileName("custom-profile") // Use a specific profile if the chain gets to the `ProfileCredentialsProvider` stage.
.asyncCredentialUpdateEnabled(true) // Enable async credential updates.
.build();
```
Dieser Ansatz gibt Ihnen mehr Kontrolle und bietet gleichzeitig den Komfort der standardmäßigen Anmeldeinformationskette.
# Zwischenspeichern von Anmeldeinformationen im AWS SDK for Java 2.x
Der AWS SDK for Java 2.x implementiert das Zwischenspeichern von Anmeldeinformationen, um die Leistung zu verbessern und die Anzahl der Aufrufe an Anmeldeinformationsquellen zu reduzieren. In diesem Abschnitt wird erklärt, wie das Zwischenspeichern von Anmeldeinformationen funktioniert und wie Sie es für Ihre Anwendungen konfigurieren können.
## Grundlegendes zum Caching von Anmeldeinformationsanbietern
Anmeldeinformationsanbieter im SDK for Java 2.x verwenden unterschiedliche Caching-Strategien:
+ **Internes Zwischenspeichern von Anmeldeinformationen**: Viele Anbieter speichern Anmeldeinformationen, die sie abrufen.
+ **Automatische Aktualisierung**: Anbieter mit zwischengespeicherten Anmeldeinformationen implementieren Aktualisierungsmechanismen.
### Anbieter mit internem Caching von Anmeldeinformationen
Die folgenden Anbieter von Anmeldeinformationen speichern Anmeldeinformationen intern im Cache, auch wenn Sie neue Instanzen erstellen:
+ **Anbieter von Anmeldeinformationen für Instanzprofile**: Speichert Anmeldeinformationen aus dem Amazon EC2-Metadatenservice im Cache.
+ **Anbieter von Container-Anmeldeinformationen: Speichert** Anmeldeinformationen vom Container-Metadaten-Endpunkt im Cache.
+ **STS-basierte Anbieter**: Zwischenspeichern temporärer Anmeldeinformationen von AWS -Security-Token-Service (STS).
+ **Anbieter von Web-Identitätstoken**: Cache-Anmeldeinformationen, die aus Web-Identitätstoken abgerufen wurden.
+ **Anbieter von Prozessanmeldedaten**: Speichert Anmeldeinformationen von externen Prozessen im Cache.
### Anbieter ohne internes Caching
Die folgenden Anbieter implementieren kein internes Caching:
+ **Anbieter von Anmeldeinformationen für Umgebungsvariablen**
+ **Anbieter von Anmeldeinformationen für Systemeigenschaften**
+ **Anbieter für statische Anmeldeinformationen**
## Zwischenspeicherung von Anmeldeinformationen konfigurieren
Sie können das Caching-Verhalten beim Erstellen von Anmeldeinformationsanbietern anpassen:
### Stabile Zeit
Steuert, wann Anmeldeinformationen als veraltet gelten und aktualisiert werden müssen:
```
.staleTime(Duration.ofMinutes(2)) // Consider stale 2 minutes before expiration.
```
### Zeit vor dem Abrufen
Legt fest, wann mit der Aktualisierung der Anmeldeinformationen begonnen werden soll, bevor sie ablaufen:
```
.prefetchTime(Duration.ofMinutes(10)) // Start refresh 10 minutes before expiration.
```
### Asynchrone Updates
Aktiviert die Aktualisierung von Anmeldeinformationen im Hintergrund:
```
.asyncCredentialUpdateEnabled(true) // Refresh credentials in background thread.
```
### Sitzungsdauer
Steuert für STS-basierte Anbieter, wie lange temporäre Anmeldeinformationen gültig bleiben:
```
.refreshRequest(r -> r.durationSeconds(3600)) // 1 hour session.
```
## Konfigurationsbeispiel für das Zwischenspeichern von Anmeldeinformationen
Als Beispiel für die Konfiguration des Zwischenspeichers für die Implementierung eines Anbieters für Anmeldeinformationen möchten Sie vielleicht, dass das SDK einen Hintergrundthread verwendet, um Anmeldeinformationen vorab abzurufen (im Voraus abzurufen), bevor sie ablaufen. Auf diese Weise können Sie den blockierenden Aufruf vermeiden, der neue Anmeldeinformationen abruft.
Das folgende Beispiel zeigt ein Beispiel, `[StsAssumeRoleCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/auth/StsAssumeRoleCredentialsProvider.html)` das einen erstellt, der einen Hintergrundthread verwendet, um Anmeldeinformationen vorab abzurufen, indem die `[asyncCredentialUpdateEnabled](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/auth/StsCredentialsProvider.BaseBuilder.html#asyncCredentialUpdateEnabled(java.lang.Boolean))` Eigenschaft im Builder `true` auf gesetzt wird:
```
StsAssumeRoleCredentialsProvider provider = StsAssumeRoleCredentialsProvider.builder()
.refreshRequest(r -> r
.roleArn("arn:aws:iam::111122223333:role/example-role")
.roleSessionName("example-session")
.durationSeconds(3600)) // 1 hour session
.staleTime(Duration.ofMinutes(5)) // Consider stale 5 minutes before expiration
.prefetchTime(Duration.ofMinutes(10)) // Start refresh 10 minutes before expiration
.asyncCredentialUpdateEnabled(true) // Refresh in background
.build();
S3Client s3 = S3Client.builder()
.credentialsProvider(provider)
.build();
```
Wenn Sie einen Vorgang `s3Client` zum ersten Mal aufrufen, `[AssumeRoleRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/model/AssumeRoleRequest.html)` wird ein an den AWS -Security-Token-Service (STS) gesendet. STS gibt temporäre Anmeldeinformationen zurück, die für 15 Minuten (900 Sekunden) gültig sind. Die `s3Client` Instanz verwendet die zwischengespeicherten Anmeldeinformationen, bis sie vor Ablauf der 15 Minuten aktualisiert werden müssen. Standardmäßig versucht das SDK, zwischen 5 Minuten und 1 Minute vor Ablauf der aktuellen Sitzung neue Anmeldeinformationen für eine neue Sitzung abzurufen. Das Pre-Fetch-Fenster kann mithilfe der Eigenschaften `[prefetchTime](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/auth/StsCredentialsProvider.BaseBuilder.html#prefetchTime(java.time.Duration))` und `[staleTime](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/auth/StsCredentialsProvider.BaseBuilder.html#staleTime(java.time.Duration))` konfiguriert werden.
Sie können die folgenden Anbieter für sitzungsbasierte Anmeldeinformationen auf ähnliche Weise konfigurieren:
+ `StsWebIdentityTokenFileCredentialsProvider`
+ `StsGetSessionTokenCredentialsProvider`
+ `StsGetFederationTokenCredentialsProvider`
+ `StsAssumeRoleWithWebIdentityCredentialsProvider`
+ `StsAssumeRoleWithSamlCredentialsProvider`
+ `StsAssumeRoleCredentialsProvider`
+ `DefaultCredentialsProvider`(wenn es an einen Anbieter für Anmeldeinformationen delegiert, der Sitzungen verwendet)
+ `ProcessCredentialsProvider`
+ `WebIdentityTokenFileCredentialsProvider`
+ `ContainerCredentialsProvider`
+ `InstanceProfileCredentialsProvider`
Wenn Sie das Zwischenspeichern von Anmeldeinformationen verstehen, können Sie die Leistung und Zuverlässigkeit Ihrer Anwendung bei der Arbeit mit optimieren. AWS-Services
# Geben Sie einen bestimmten Anbieter für Anmeldeinformationen in der AWS SDK for Java 2.x
Die standardmäßige Anbieterkette für Anmeldeinformationen ist zwar für viele Szenarien praktisch, aber die explizite Angabe von Anbietern für Anmeldeinformationen gibt Ihnen mehr Kontrolle über das Authentifizierungsverhalten, die Leistung und die Sicherheit.
Zu den Gründen, aus denen Sie möglicherweise einen Anbieter für Anmeldeinformationen angeben sollten, gehören:
+ Die Standardanbieterkette überprüft mehrere Quellen nacheinander, was die Latenz erhöhen kann:
```
// The default provider chain checks might check multiple sources until it finds
// sufficient configuration.
S3Client s3Client = S3Client.builder().build();
// You can specify exactly where to look.
S3Client optimizedClient = S3Client.builder()
.credentialsProvider(InstanceProfileCredentialsProvider.create())
.build();
```
+ Sie müssen nicht standardmäßige Speicherorte für den Zugriff auf die Konfiguration der Anmeldeinformationen verwenden:
```
// Use configuration from a custom file location.
S3Client s3Client = S3Client.builder()
.credentialsProvider(ProfileCredentialsProvider.builder()
.profileFile(ProfileFile.builder()
.content(Paths.get("/custom/path/to/configuration/file"))
.type(ProfileFile.Type.CONFIGURATION) // Expects all non-default profiles to be prefixed with "profile".
.build())
.profileName("custom")
.build())
.build();
```
+ Verwenden Sie unterschiedliche Anmeldeinformationen für verschiedene Service-Clients. Wenn Ihre Anwendung beispielsweise auf mehrere AWS Konten zugreifen oder unterschiedliche Berechtigungen für verschiedene Dienste verwenden muss:
```
// S3 client using one set of credentials.
S3Client s3Client = S3Client.builder()
.credentialsProvider(ProfileCredentialsProvider.create("s3-readonly"))
.build();
// DynamoDB client using different credentials.
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.credentialsProvider(ProfileCredentialsProvider.create("dynamodb-admin"))
.build();
```
+ Steuern Sie das Verhalten bei der Aktualisierung von Anmeldeinformationen:
```
// Create a provider with custom refresh behavior.
StsAssumeRoleCredentialsProvider customRefreshProvider =
StsAssumeRoleCredentialsProvider.builder()
.refreshRequest(AssumeRoleRequest.builder()
.roleArn("arn:aws:iam::123456789012:role/my-role")
.roleSessionName("custom-session")
.build())
.stsClient(StsClient.create())
.asyncCredentialUpdateEnabled(true) // Use a background thread to prefetch credentials.
.build();
S3Client s3Client = S3Client.builder()
.credentialsProvider(customRefreshProvider)
.build();
```
# Verwenden Sie AWS gemeinsam genutzte Konfigurationsprofile in AWS SDK for Java 2.x
Mithilfe von Shared `config` und `credentials` File können Sie mehrere Profile einrichten. Dadurch kann Ihre Anwendung mehrere Konfigurationssätze für Anmeldeinformationen verwenden. Das `[default]` Profil wurde bereits erwähnt. Das SDK verwendet die [ProfileCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ProfileCredentialsProvider.html)Klasse, um Einstellungen aus Profilen zu laden, die in der gemeinsam genutzten `credentials` Datei definiert sind.
Der folgende Codeausschnitt zeigt, wie ein Dienstclient erstellt wird, der die Einstellungen verwendet, die als Teil des genannten Profils definiert sind. `my_profile`
```
Region region = Region.US_WEST_2;
DynamoDbClient ddb = DynamoDbClient.builder()
.region(region)
.credentialsProvider(ProfileCredentialsProvider.create("my_profile"))
.build();
```
## Legen Sie ein anderes Profil als Standard fest
Um ein anderes Profil als das `[default]` Profil als Standard für Ihre Anwendung festzulegen, setzen Sie die `AWS_PROFILE` Umgebungsvariable auf den Namen Ihres benutzerdefinierten Profils.
Um diese Variable unter Linux, macOS oder Unix festzulegen, verwenden Sie`export`:
```
export AWS_PROFILE="other_profile"
```
In Windows können Sie die Variablen mit `set` festlegen:
```
set AWS_PROFILE="other_profile"
```
Alternativ können Sie die `aws.profile` Java-Systemeigenschaft auf den Namen des Profils setzen.
## Laden Sie die Profilanmeldedaten neu
Sie können jeden Anmeldeinformationsanbieter konfigurieren, dessen Builder über eine `profileFile()` Methode zum erneuten Laden von Profilanmeldedaten verfügt. Diese Profilklassen für Anmeldeinformationen sind:`ProfileCredentialsProvider`, `DefaultCredentialsProvider``InstanceProfileCredentialsProvider`, und `ProfileTokenProvider.`
**Anmerkung**
Das erneute Laden von Profilanmeldeinformationen funktioniert nur mit den folgenden Einstellungen in der Profildatei: `aws_access_key_id``aws_secret_access_key`, und. `aws_session_token`
Einstellungen wie`region`, `sso_session``sso_account_id`, und `source_profile` werden ignoriert.
Um einen unterstützten Anbieter für Anmeldeinformationen zum erneuten Laden von Profileinstellungen zu konfigurieren, stellen Sie eine Instanz von für die `profileFile()` Builder-Methode [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/profiles/ProfileFileSupplier.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/profiles/ProfileFileSupplier.html)bereit. Das folgende Codebeispiel zeigt eine`ProfileCredentialsProvider`, die Anmeldeinformationen aus dem Profil neu lädt. `[default]`
```
ProfileCredentialsProvider provider = ProfileCredentialsProvider
.builder()
.profileFile(ProfileFileSupplier.defaultSupplier())
.build();
// Set up a service client with the provider instance.
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.region(Region.US_EAST_1)
.credentialsProvider(provider)
.build();
/*
Before dynamoDbClient makes a request, it reloads the credentials settings
by calling provider.resolveCredentials().
*/
```
Wenn `ProfileCredentialsProvider.resolveCredentials()` es aufgerufen wird, lädt das SDK for Java die Einstellungen neu. `ProfileFileSupplier.defaultSupplier()`ist eine von [mehreren praktischen Implementierungen](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/profiles/ProfileFileSupplier.html), die vom `ProfileFileSupplier` SDK bereitgestellt werden. Wenn Ihr Anwendungsfall dies erfordert, können Sie Ihre eigene Implementierung bereitstellen.
Das folgende Beispiel zeigt die Verwendung der `ProfileFileSupplier.reloadWhenModified()` Convenience-Methode. `reloadWhenModified()`verwendet einen `Path` Parameter, der Ihnen Flexibilität bei der Festlegung der Quelldatei für die Konfiguration bietet und nicht den Standardspeicherort `~/.aws/credentials` (oder`config`).
Die Einstellungen werden beim Aufruf nur dann neu geladen, wenn `resolveCredentials()` das SDK feststellt, dass der Inhalt der Datei geändert wurde.
```
Path credentialsFilePath = ...
ProfileCredentialsProvider provider = ProfileCredentialsProvider
.builder()
.profileFile(ProfileFileSupplier.reloadWhenModified(credentialsFilePath, ProfileFile.Type.CREDENTIALS))
.profileName("my-profile")
.build();
/*
A service client configured with the provider instance calls provider.resolveCredential()
before each request.
*/
```
Die `ProfileFileSupplier.aggregate()` Methode führt den Inhalt mehrerer Konfigurationsdateien zusammen. Sie entscheiden, ob eine Datei per Aufruf neu geladen wird `resolveCredentials()` oder ob die Einstellungen einer Datei zum Zeitpunkt des ersten Lesens festgelegt sind.
Das folgende Beispiel zeigt a`DefaultCredentialsProvider`, das die Einstellungen von zwei Dateien zusammenführt, die Profileinstellungen enthalten. Das SDK lädt die Einstellungen in der Datei, auf die die `credentialsFilePath` Variable verweist, bei jedem Aufruf `resolveCredentials()` neu, wenn die Einstellungen geändert wurden. Die Einstellungen des `profileFile` Objekts bleiben unverändert.
```
Path credentialsFilePath = ...;
ProfileFile profileFile = ...;
DefaultCredentialsProvider provider = DefaultCredentialsProvider
.builder()
.profileFile(ProfileFileSupplier.aggregate(
ProfileFileSupplier.reloadWhenModified(credentialsFilePath, ProfileFile.Type.CREDENTIALS),
ProfileFileSupplier.fixedProfileFile(profileFile)))
.profileName("my-profile")
.build();
/*
A service client configured with the provider instance calls provider.resolveCredential()
before each request.
*/
```
# Laden Sie Anmeldeinformationen von einem externen Prozess mit dem AWS SDK for Java 2.x
**Warnung**
Im Folgenden wird eine Methode zur Beschaffung temporärer Anmeldeinformationen aus einem externen Prozess beschrieben. Dies kann potenziell gefährlich sein, gehen Sie also vorsichtig vor. Wir empfehlen, dass Sie, wenn möglich, andere Anbieter von Anmeldeinformationen verwenden. Wenn Sie diese Option verwenden, empfehlen wir Ihnen, sicherzustellen, dass die `config` Datei so gesperrt wie möglich ist. Verwenden Sie dabei die bewährten Sicherheitsmethoden für Ihr Betriebssystem.
Stellen Sie sicher, dass Ihr Tool für benutzerdefinierte Anmeldeinformationen keine geheimen Informationen in das System schreibt`StdErr`. SDKs und AWS CLI kann solche Informationen erfassen und protokollieren, wodurch sie möglicherweise unbefugten Benutzern zugänglich gemacht werden.
Mit dem SDK for Java 2.x können Sie temporäre Anmeldeinformationen von einem externen Prozess für benutzerdefinierte Anwendungsfälle abrufen. Es gibt zwei Möglichkeiten, diese Funktionalität zu konfigurieren.
## Verwenden Sie die `credential_process` Einstellung
Wenn Sie über eine Methode verfügen, die temporäre Anmeldeinformationen bereitstellt, können Sie sie integrieren, indem Sie die `credential_process` Einstellung als Teil einer Profildefinition in der `config` Datei hinzufügen. Der von Ihnen angegebene Wert muss den vollständigen Pfad zur Befehlsdatei enthalten. Wenn der Dateipfad Leerzeichen enthält, müssen Sie ihn in Anführungszeichen setzen.
Das SDK ruft den Befehl genau wie angegeben auf und liest dann JSON-Daten aus`stdout`.
Die folgenden Beispiele zeigen die Verwendung dieser Einstellung für Dateipfade ohne Leerzeichen und Dateipfade mit Leerzeichen.
------
#### [ Linux/macOS ]
**Keine Leerzeichen im Dateipfad**
```
[profile process-credential-profile]
credential_process = /path/to/credential/file/credential_file.sh --custom-command custom_parameter
```
**Leerzeichen im Dateipfad**
```
[profile process-credential-profile]
credential_process = "/path/with/space to/credential/file/credential_file.sh" --custom-command custom_parameter
```
------
#### [ Windows ]
**Keine Leerzeichen im Dateipfad**
```
[profile process-credential-profile]
credential_process = C:\Path\To\credentials.cmd --custom_command custom_parameter
```
**Leerzeichen im Dateipfad**
```
[profile process-credential-profile]
credential_process = "C:\Path\With Space To\credentials.cmd" --custom_command custom_parameter
```
------
Der folgende Codeausschnitt zeigt, wie ein Dienstclient erstellt wird, der die temporären Anmeldeinformationen verwendet, die als Teil des genannten Profils definiert sind. `process-credential-profile`
```
Region region = Region.US_WEST_2;
S3Client s3Client = S3Client.builder()
.region(region)
.credentialsProvider(ProfileCredentialsProvider.create("process-credential-profile"))
.build();
```
Ausführliche Informationen zur Verwendung eines externen Prozesses als Quelle für temporäre Anmeldeinformationen finden Sie im [Abschnitt Prozessanmeldeinformationen im Referenzhandbuch](https://docs.aws.amazon.com/sdkref/latest/guide/feature-process-credentials.html) AWS SDKs und im Tools-Referenzhandbuch.
## Verwenden Sie ein `ProcessCredentialsProvider`
Als Alternative zur Verwendung von Einstellungen in der `config` Datei können Sie die SDKs verwenden, `[ProcessCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ProcessCredentialsProvider.html)` um temporäre Anmeldeinformationen mithilfe von Java zu laden.
Die folgenden Beispiele zeigen verschiedene Versionen der Spezifizierung eines externen Prozesses mithilfe von `ProcessCredentialsProvider` und der Konfiguration eines Service-Clients, der die temporären Anmeldeinformationen verwendet.
------
#### [ Linux/macOS ]
**Keine Leerzeichen im Dateipfad**
```
ProcessCredentialsProvider credentials =
ProcessCredentialsProvider
.builder()
.command("/path/to/credentials.sh optional_param1 optional_param2")
.build();
S3Client s3 = S3Client.builder()
.region(Region.US_WEST_2)
.credentialsProvider(credentials)
.build();
```
**Leerzeichen im Dateipfad**
```
ProcessCredentialsProvider credentials =
ProcessCredentialsProvider
.builder()
.command("/path\\ with\\ spaces\\ to/credentials.sh optional_param1 optional_param2")
.build();
S3Client s3 = S3Client.builder()
.region(Region.US_WEST_2)
.credentialsProvider(credentials)
.build();
```
------
#### [ Windows ]
**Keine Leerzeichen im Dateipfad**
```
ProcessCredentialsProvider credentials =
ProcessCredentialsProvider
.builder()
.command("C:\\Path\\To\\credentials.exe optional_param1 optional_param2")
.build();
S3Client s3 = S3Client.builder()
.region(Region.US_WEST_2)
.credentialsProvider(credentials)
.build();
```
**Leerzeichen im Dateipfad**
```
ProcessCredentialsProvider credentials =
ProcessCredentialsProvider
.builder()
.command("\"C:\\Path\\With Spaces To\\credentials.exe\" optional_param1 optional_param2")
.build();
S3Client s3 = S3Client.builder()
.region(Region.US_WEST_2)
.credentialsProvider(credentials)
.build();
```
------
## Verwenden Sie IAM Roles Anywhere für die Authentifizierung
Mit [IAM Roles Anywhere](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/introduction.html) können Sie temporäre AWS Anmeldeinformationen für Workloads abrufen, die außerhalb von ausgeführt werden. AWS-Service AWS Es ermöglicht den sicheren Zugriff auf AWS Ressourcen aus lokalen oder anderen Cloud-Umgebungen.
Bevor Sie Anfragen mit IAM Roles Anywhere authentifizieren können, müssen Sie zunächst die erforderlichen Informationen sammeln und das [Credential](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/credential-helper.html) Helper-Tool herunterladen. Folgen Sie den Anweisungen „[Erste Schritte](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/getting-started.html)“ im IAM Roles Anywhere-Benutzerhandbuch, um die erforderlichen Artefakte zu erstellen.
Das SDK for Java verfügt nicht über einen speziellen Anbieter für Anmeldeinformationen, um temporäre Anmeldeinformationen von IAM Roles Anywhere abzurufen. Sie können jedoch das Credential Helper-Tool zusammen mit einer der Optionen verwenden, um [Anmeldeinformationen von einem externen Prozess abzurufen](#credentials-process).
### Verwenden Sie die `credential_process` Einstellung in einem Profil
Der folgende Ausschnitt in der gemeinsam genutzten AWS Konfigurationsdatei zeigt ein Profil mit dem Namen`roles_anywhere`, das die Einstellung verwendet: `credential_process`
```
[profile roles_anywhere]
credential_process = ./aws_signing_helper credential-process \
--certificate /path/to/certificate \
--private-key /path/to/private-key \
--trust-anchor-arn arn:aws:rolesanywhere:region:account:trust-anchor/TA_ID \
--profile-arn arn:aws:rolesanywhere:region:account:profile/PROFILE_ID \
--role-arn arn:aws:iam::account:role/role-name-with-path
```
Sie müssen den rot angezeigten Text durch Ihre Werte ersetzen, nachdem Sie alle Artefakte zusammengestellt haben. Das erste Element in der Einstellung,`aws_signing_helper`, ist die ausführbare Datei des Credential Helper-Tools und `credential-process` ist der Befehl.
Wenn Sie einen Service-Client für die Verwendung des `roles_anywhere` Profils konfigurieren (wie im folgenden Code gezeigt), speichert das SDK die temporären Anmeldeinformationen im Cache und aktualisiert sie, bevor sie ablaufen:
```
S3Client s3Client = S3Client.builder()
.credentialsProvider(ProfileCredentialsProvider.builder()
.profileName("roles_anywhere").build())
.build();
```
### Konfigurieren Sie ein `ProcessCredentialsProvider`
Wie im Folgenden gezeigt, können Sie einen reinen Code-Ansatz mit folgenden `ProcessCredentialsProvider` Profileinstellungen verwenden:
```
ProcessCredentialsProvider processCredentialsProvider = ProcessCredentialsProvider.builder()
.command("""
./aws_signing_helper credential-process \
--certificate /path/to/certificate \
--private-key /path/to/private-key \
--trust-anchor-arn arn:aws:rolesanywhere:region:account:trust-anchor/TA_ID \
--profile-arn arn:aws:rolesanywhere:region:account:profile/PROFILE_ID \
--role-arn arn:aws:iam::account:role/role-name-with-path
""").build();
S3Client s3Client = S3Client.builder()
.credentialsProvider(processCredentialsProvider)
.build();
```
Ersetzen Sie den rot angezeigten Text durch Ihre Werte, nachdem Sie alle Artefakte zusammengestellt haben.
# Geben Sie die Anmeldeinformationen im Code ein, indem Sie AWS SDK for Java 2.x
Wenn die standardmäßige Anmeldeinformationskette oder ein bestimmter oder benutzerdefinierter Anbieter oder eine Anbieterkette für Ihre Anwendung nicht funktioniert, können Sie temporäre Anmeldeinformationen direkt im Code angeben. Dabei kann es sich um [Anmeldeinformationen für die IAM-Rolle handeln](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtogetcredentials.html), wie [oben beschrieben](credentials-temporary.md#credentials-temporary-from-portal), oder um temporäre Anmeldeinformationen, die von AWS -Security-Token-Service ()AWS STS abgerufen wurden. Wenn Sie temporäre Anmeldeinformationen mit abgerufen haben AWS STS, stellen Sie sie einem AWS-Service Client zur Verfügung, wie im folgenden Codebeispiel gezeigt.
1. Nehmen Sie eine Rolle an, indem Sie anrufen`StsClient.assumeRole()`.
1. Erstellen Sie ein [StaticCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/StaticCredentialsProvider.html)Objekt und versorgen Sie es mit dem `AwsSessionCredentials` Objekt.
1. Konfigurieren Sie den Service Client Builder mit dem `StaticCredentialsProvider` und erstellen Sie den Client.
Das folgende Beispiel erstellt einen Amazon S3-Serviceclient mit temporären Anmeldeinformationen, die von AWS STS für eine von IAM angenommene Rolle zurückgegeben wurden.
```
// The AWS IAM Identity Center identity (user) who executes this method does not have permission to list buckets.
// The identity is configured in the [default] profile.
public static void assumeRole(String roleArn, String roleSessionName) {
// The IAM role represented by the 'roleArn' parameter can be assumed by identities in two different accounts
// and the role permits the user to only list buckets.
// The SDK's default credentials provider chain will find the single sign-on settings in the [default] profile.
// The identity configured with the [default] profile needs permission to call AssumeRole on the STS service.
try {
Credentials tempRoleCredentials;
try (StsClient stsClient = StsClient.create()) {
AssumeRoleRequest roleRequest = AssumeRoleRequest.builder()
.roleArn(roleArn)
.roleSessionName(roleSessionName)
.build();
AssumeRoleResponse roleResponse = stsClient.assumeRole(roleRequest);
tempRoleCredentials = roleResponse.credentials();
}
// Use the following temporary credential items for the S3 client.
String key = tempRoleCredentials.accessKeyId();
String secKey = tempRoleCredentials.secretAccessKey();
String secToken = tempRoleCredentials.sessionToken();
// List all buckets in the account associated with the assumed role
// by using the temporary credentials retrieved by invoking stsClient.assumeRole().
StaticCredentialsProvider staticCredentialsProvider = StaticCredentialsProvider.create(
AwsSessionCredentials.create(key, secKey, secToken));
try (S3Client s3 = S3Client.builder()
.credentialsProvider(staticCredentialsProvider)
.build()) {
List buckets = s3.listBuckets().buckets();
for (Bucket bucket : buckets) {
System.out.println("bucket name: " + bucket.name());
}
}
} catch (StsException | S3Exception e) {
logger.error(e.getMessage());
System.exit(1);
}
}
```
## Berechtigungssatz
Der folgende in definierte Berechtigungssatz AWS IAM Identity Center ermöglicht es der Identität (dem Benutzer), die folgenden zwei Operationen auszuführen
1. Der `GetObject` Betrieb des Amazon Simple Storage Service.
1. Der `AssumeRole` Betrieb des AWS -Security-Token-Service.
Ohne Übernahme der Rolle würde die im Beispiel gezeigte `s3.listBuckets()` Methode fehlschlagen.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"sts:AssumeRole"
],
"Resource": [
"*"
]
}
]
}
```
------
## Angenommene Rolle
### Vorausgesetzte Richtlinie für Rollenberechtigungen
Die folgende Berechtigungsrichtlinie ist an die Rolle angehängt, die im vorherigen Beispiel angenommen wurde. Diese Berechtigungsrichtlinie ermöglicht es, alle Buckets in demselben Konto wie die Rolle aufzulisten.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListAllMyBuckets"
],
"Resource": [
"*"
]
}
]
}
```
------
### Vertrauensrichtlinie für übernommene Rollen
Die folgende Vertrauensrichtlinie ist der Rolle zugeordnet, die im vorherigen Beispiel übernommen wurde. Die Richtlinie ermöglicht die Übernahme der Rolle durch Identitäten (Benutzer) in zwei Konten.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:root",
"arn:aws:iam::555555555555:root"
]
},
"Action": "sts:AssumeRole",
"Condition": {}
}
]
}
```
------
# Lesen Sie die Anmeldeinformationen für IAM-Rollen auf Amazon EC2 mithilfe des SDK for Java 2.x
Sie können eine IAM-Rolle verwenden, um temporäre Anmeldeinformationen für Anwendungen zu verwalten, die auf einer EC2-Instance ausgeführt werden und API-Anfragen stellen AWS CLI . AWS Das ist eher zu empfehlen, als Zugriffsschlüssel innerhalb der EC2-Instance zu speichern. Um einer EC2-Instance eine AWS Rolle zuzuweisen und sie all ihren Anwendungen zur Verfügung zu stellen, erstellen Sie ein Instance-Profil, das an die Instance angehängt ist. Ein Instanzprofil enthält die Rolle und ermöglicht Programmen, die auf der EC2-Instance ausgeführt werden, temporäre Anmeldeinformationen abzurufen. Weitere Informationen finden Sie unter [Verwenden einer IAM-Rolle zum Erteilen von Berechtigungen für Anwendungen, die auf Amazon-EC2-Instances ausgeführt werden](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html) im *IAM-Benutzerhandbuch*.
Dieses Thema enthält Informationen darüber, wie Sie Ihre Java-Anwendung so einrichten, dass sie auf einer EC2-Instance ausgeführt wird, und wie Sie es ermöglichen, AWS SDK for Java 2.x IAM Rollenanmeldedaten abzurufen.
## Erwerben Sie IAM-Rollenanmeldedaten aus der Umgebung
Wenn Ihre Anwendung mithilfe der `create` Methode (oder `builder().build()` Methoden) einen AWS Dienstclient erstellt, verwendet das SDK for Java die *standardmäßige Anbieterkette für Anmeldeinformationen*. Die Anbieterkette für Standardanmeldedaten durchsucht die Ausführungsumgebung nach Konfigurationselementen, die das SDK gegen temporäre Anmeldeinformationen eintauschen kann. In [Anbieterkette für Standardanmeldedaten in der AWS SDK for Java 2.x](credentials-chain.md) diesem Abschnitt wird der vollständige Suchvorgang beschrieben.
Der letzte Schritt in der Standardanbieterkette ist nur verfügbar, wenn Ihre Anwendung auf einer Amazon EC2 Instance ausgeführt wird. In diesem Schritt verwendet das SDK eine, `InstanceProfileCredentialsProvider` um die im EC2-Instanzprofil definierte IAM-Rolle zu lesen. Das SDK ruft dann temporäre Anmeldeinformationen für diese IAM-Rolle ab.
Diese Anmeldeinformationen sind zwar temporär und würden irgendwann ablaufen, werden aber `InstanceProfileCredentialsProvider` regelmäßig für Sie aktualisiert, sodass Sie weiterhin darauf zugreifen können. AWS
## Erwerben Sie die Anmeldeinformationen für die IAM-Rolle programmgesteuert
Als Alternative zur standardmäßigen Anbieterkette für Anmeldeinformationen, die eventuell einen `InstanceProfileCredentialsProvider` auf EC2 verwendet, können Sie einen Service-Client explizit mit einem konfigurieren. `InstanceProfileCredentialsProvider` Dieser Ansatz wird im folgenden Codeausschnitt dargestellt.
```
S3Client s3 = S3Client.builder()
.credentialsProvider(InstanceProfileCredentialsProvider.create())
.build();
```
## Besorgen Sie sich auf sichere Weise Anmeldeinformationen für IAM-Rollen
Standardmäßig führen EC2-Instances [IMDS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html) (Instance Metadata Service) aus, das es den SDKs ermöglicht`InstanceProfileCredentialsProvider`, auf Informationen wie die konfigurierte IAM-Rolle zuzugreifen. EC2-Instances führen standardmäßig zwei Versionen von IMDS aus:
+ Instance Metadata Service Version 1 (IMDSv1) — eine Methode request/response
+ Instanz-Metadatendienst Version 2 (IMDSv2) — eine sitzungsorientierte Methode
[IMDSv2 ist ein sichererer Ansatz](https://aws.amazon.com/blogs/security/defense-in-depth-open-firewalls-reverse-proxies-ssrf-vulnerabilities-ec2-instance-metadata-service/) als. IMDSv1
Standardmäßig versucht IMDSv2 das Java SDK zuerst, die IAM-Rolle abzurufen, aber wenn das fehlschlägt, versucht IMDSv1 es es. Da IMDSv1 es jedoch weniger sicher ist, AWS empfiehlt es, IMDSv2 nur das SDK zu verwenden und das SDK daran zu hindern, es zu versuchen IMDSv1.
Um den sichereren Ansatz zu verwenden, deaktivieren Sie die Verwendung des SDK, IMDSv1 indem Sie eine der folgenden Einstellungen mit dem Wert von angeben`true`.
+ Umgebungsvariable: `AWS_EC2_METADATA_V1_DISABLED`
+ JVM-Systemeigenschaft: aws. `disableEc2MetadataV1`
+ Einstellung für gemeinsam genutzte Konfigurationsdatei: `ec2_metadata_v1_disabled`
Wenn eine dieser Einstellungen auf gesetzt ist`true`, lädt das SDK keine IMDS-Rollenanmeldedaten, IMDSv1 wenn der erste IMDSv2 Aufruf fehlschlägt.
# Konfigurieren Sie das Wiederholungsverhalten in der AWS SDK for Java 2.x
Aufrufe von AWS-Services können gelegentlich aus unerwarteten Gründen fehlschlagen. Bestimmte Fehler, wie Drosselung (Rate überschritten) oder vorübergehende Fehler, können erfolgreich sein, wenn der Anruf erneut versucht wird. Der AWS SDK for Java 2.x verfügt über einen integrierten Mechanismus zur Erkennung solcher Fehler und zur automatischen Wiederholung des Anrufs, der standardmäßig für alle Clients aktiviert ist.
Auf dieser Seite wird beschrieben, wie das funktioniert, wie die verschiedenen Modi konfiguriert und das Wiederholungsverhalten angepasst werden.
## Strategien für Wiederholungsversuche
Eine Wiederholungsstrategie ist ein Mechanismus, der im SDK zur Implementierung von Wiederholungsversuchen verwendet wird. Jeder SDK-Client verfügt über eine Wiederholungsstrategie, die zum Zeitpunkt der Erstellung erstellt wurde und die nach dem Erstellen des Clients nicht mehr geändert werden kann.
Die Wiederholungsstrategie hat die folgenden Aufgaben.
+ Klassifizieren Sie Ausnahmen als wiederholbar oder nicht.
+ Berechne die vorgeschlagene Verzögerung, um bis zum nächsten Versuch zu warten.
+ Pflegen Sie einen [Token-Bucket](https://en.wikipedia.org/wiki/Token_bucket), der einen Mechanismus zum Stoppen von Wiederholungsversuchen bereitstellt, wenn ein großer Prozentsatz der Anfragen fehlschlägt und Wiederholungen erfolglos sind.
**Anmerkung**
Vor der Veröffentlichung von *Wiederholungsstrategien* mit Version 2.26.0 des SDK stellten *Wiederholungsrichtlinien* den Wiederholungsmechanismus im SDK zur Verfügung. *Die API *für Wiederholungsrichtlinien* besteht aus der [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/RetryPolicy.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/RetryPolicy.html)Kernklasse im `software.amazon.awssdk.core.retry` Paket, wohingegen das Paket die API-Elemente für `[software.amazon.awssdk.retries](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/package-summary.html)` Wiederholungsstrategien enthält.*
Die API für Wiederholungsstrategien wurde im Rahmen der AWS umfassenden Bemühungen eingeführt, die Schnittstellen und das Verhalten der Kernkomponenten von zu vereinheitlichen. SDKs
Das SDK for Java 2.x verfügt über drei integrierte Wiederholungsstrategien: Standard, Legacy und Adaptive. Alle drei Wiederholungsstrategien sind so vorkonfiguriert, dass sie es bei einer Reihe von Ausnahmen erneut versuchen können. Beispiele für Fehler, die wiederholt werden können, sind Socket-Timeouts, dienstseitige Drosselung, gleichzeitige oder optimistische Sperren sowie vorübergehende Servicefehler.
### Standardstrategie für Wiederholungsversuche
Die [standardmäßige Wiederholungsstrategie](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/StandardRetryStrategy.html) ist die empfohlene `RetryStrategy` Implementierung für normale Anwendungsfälle. Im Gegensatz zu ist die Standardstrategie im Allgemeinen für alle Anwendungsfälle mit Wiederholungsversuchen nützlich. `AdaptiveRetryStrategy`
Standardmäßig führt die Standardstrategie für Wiederholungsversuche Folgendes aus.
+ Wiederholt die Versuche unter den Bedingungen, die zum Zeitpunkt der Erstellung konfiguriert wurden. Sie können dies mit `[StandardRetryStrategy.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/StandardRetryStrategy.Builder.html)#retryOnException` anpassen.
+ Wiederholt es zweimal, also insgesamt 3 Versuche. Sie können dies mit `StandardRetryStrategy.Builder#maxAttempts(int)` anpassen.
+ Für Ausnahmen ohne Drosselung wird die `[BackoffStrategy](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/api/BackoffStrategy.html)#exponentialDelay` Backoff-Strategie mit einer Basisverzögerung von 100 Millisekunden und einer maximalen Verzögerung von 20 Sekunden verwendet. Sie `StandardRetryStrategy.Builder#backoffStrategy` können dies mit anpassen.
+ Für Drosselungsausnahmen wird die `BackoffStrategy#exponentialDelay` Backoff-Strategie mit einer Basisverzögerung von 1 Sekunde und einer maximalen Verzögerung von 20 Sekunden verwendet. Sie können dies mit anpassen. `StandardRetryStrategy.Builder#throttlingBackoffStrategy`
+ Führt bei vielen Downstream-Ausfällen eine Unterbrechung durch (Deaktivierung von Wiederholungsversuchen). Der erste Versuch wird immer ausgeführt, nur Wiederholungsversuche sind deaktiviert. Passen Sie an mit`StandardRetryStrategy.Builder#circuitBreakerEnabled`.
### Legacy-Wiederholungsstrategie
Die [alte Wiederholungsstrategie](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/LegacyRetryStrategy.html) ist `RetryStrategy` für normale Anwendungsfälle vorgesehen, sie ist jedoch zugunsten der veraltet. `StandardRetryStrategy` Dies ist die standardmäßige Wiederholungsstrategie, die von Clients verwendet wird, wenn Sie keine andere Strategie angeben.
Sie zeichnet sich dadurch aus, dass Ausnahmen mit und ohne Drosselung unterschiedlich behandelt werden. Bei Ausnahmen ohne Drosselung ist die Basisverzögerung für den Backoff größer (500 ms) als die Basisverzögerung für Ausnahmen ohne Drosselung (100 ms), und Drosselungsausnahmen wirken sich nicht auf den Status des Token-Buckets aus.
Die Erfahrung mit dieser Strategie in großem Umfang hat gezeigt, dass sie nicht besonders besser ist als die Standardstrategie für Wiederholungen. AWS Darüber hinaus schützt sie nachgelagerte Dienste nicht vor Wiederholungsversuchen und kann zu einer Verknappung der Ressourcen auf Kundenseite führen.
Standardmäßig funktioniert die alte Wiederholungsstrategie wie folgt.
+ Wiederholt die Versuche unter den Bedingungen, die zum Zeitpunkt der Erstellung konfiguriert wurden. Sie können dies mit `[LegacyRetryStrategy.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/LegacyRetryStrategy.Builder.html)#retryOnException` anpassen.
+ Wiederholt es dreimal, insgesamt also 4 Versuche. Sie können dies mit `LegacyRetryStrategy.Builder#maxAttempts(int)` anpassen.
+ Für Ausnahmen ohne Drosselung wird die `BackoffStrategy#exponentialDelay` Backoff-Strategie mit einer Basisverzögerung von 100 Millisekunden und einer maximalen Verzögerung von 20 Sekunden verwendet. Sie können dies anpassen mit `LegacyRetryStrategy.Builder#backoffStrategy.`
+ Für die Drosselung von Ausnahmen wird die `BackoffStrategy#exponentialDelay` Backoff-Strategie mit einer Basisverzögerung von 500 Millisekunden und einer maximalen Verzögerung von 20 Sekunden verwendet. Sie `LegacyRetryStrategy.Builder#throttlingBackoffStrategy` können dies mit anpassen.
+ Führt bei vielen Downstream-Ausfällen eine Unterbrechung durch (Deaktivierung von Wiederholungsversuchen). Ein Stromausfall verhindert niemals einen erfolgreichen ersten Versuch. Sie können dieses Verhalten mit anpassen`LegacyRetryStrategy.Builder#circuitBreakerEnabled`.
+ Der Status des Schutzschalters wird durch Drosselungsausnahmen nicht beeinflusst.
### Adaptive Wiederholungsstrategie
Die [Strategie zur adaptiven Wiederholung](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/AdaptiveRetryStrategy.html) eignet sich `RetryStrategy` für Anwendungsfälle mit einem hohen Maß an Ressourcenbeschränkungen.
Die adaptive Wiederholungsstrategie umfasst alle Funktionen der Standardstrategie und fügt einen clientseitigen Ratenbegrenzer hinzu, der die Rate gedrosselter Anfragen im Vergleich zu Anfragen ohne Drosselung misst. Die Strategie verwendet diese Messung, um die Anfragen zu verlangsamen und dabei zu versuchen, innerhalb einer sicheren Bandbreite zu bleiben, was idealerweise zu keinerlei Drosselungsfehlern führt.
Die Strategie der adaptiven Wiederholung führt standardmäßig Folgendes aus.
+ Wiederholt die Versuche unter den Bedingungen, die zum Zeitpunkt der Erstellung konfiguriert wurden. Sie können dies mit `[AdaptiveRetryStrategy.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/AdaptiveRetryStrategy.Builder.html)#retryOnException` anpassen.
+ Wiederholt es zweimal, also insgesamt 3 Versuche. Sie können dies mit `AdaptiveRetryStrategy.Builder#maxAttempts(int)` anpassen.
+ Verwendet eine dynamische Backoff-Verzögerung, die auf der aktuellen Auslastung der Downstream-Ressource basiert.
+ Führt bei einer hohen Anzahl von Downstream-Ausfällen eine Unterbrechung durch (Deaktivierung von Wiederholungsversuchen). Eine Unterbrechung des Stromkreises kann in Ausfallszenarien einen zweiten Versuch verhindern, um den nachgeschalteten Dienst zu schützen.
**Warnung**
Bei der adaptiven Wiederholungsstrategie wird davon ausgegangen, dass der Client mit einer einzelnen Ressource arbeitet (z. B. einer DynamoDB-Tabelle oder einem Amazon S3 S3-Bucket).
Wenn Sie einen einzelnen Client für mehrere Ressourcen verwenden, führen Drosselungen oder Ausfälle im Zusammenhang mit einer Ressource zu erhöhter Latenz und Ausfällen, wenn der Client auf alle anderen Ressourcen zugreift. Wenn Sie die Strategie der adaptiven Wiederholung verwenden, empfehlen wir, für jede Ressource einen einzelnen Client zu verwenden.
Wir empfehlen außerdem, diese Strategie in Situationen zu verwenden, in denen alle Clients die Strategie der adaptiven Wiederholung für die Ressource anwenden.
**Wichtig**
Die Version der Wiederholungsstrategien mit Version 2.26.0 des Java SDK enthält den neuen Aufzählungswert. [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/RetryMode.html#ADAPTIVE_V2](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/retry/RetryMode.html#ADAPTIVE_V2) Der `ADAPTIVE_V2` Modus korrigiert einen Fehler, durch den der erste Versuch nicht verzögert werden konnte, obwohl zuvor Drosselungsfehler festgestellt wurden.
Mit der Version 2.26.0 erhalten Benutzer automatisch das `ADAPTIVE_V2` Modusverhalten, indem sie den Modus wie `adaptive` eine Umgebungsvariable, eine Systemeigenschaft oder eine Profileinstellung festlegen. Für diese Einstellungen gibt es keinen `adaptive_v2` Wert. Im folgenden [Geben Sie eine Strategie an](#retry-strategies-specify) Abschnitt erfahren Sie, wie Sie den Modus einstellen.
Benutzer können das vorherige Verhalten abrufen, indem sie den Modus mithilfe von Code festlegen`RetryMode.ADAPTIVE`.
### Zusammenfassung: Vergleich der Standardwerte der Wiederholungsstrategie
Die folgende Tabelle zeigt die Standardwerte für die Eigenschaften der einzelnen Wiederholungsstrategien.
| Strategie | Maximale Anzahl der Versuche | Basisverzögerung bei Fehlern ohne Drosselung | Basisverzögerung bei Drosselungsfehlern | Größe des Token-Buckets | Token-Kosten pro Wiederholungsversuch ohne Drosselung | Tokenkosten pro wiederholtem Versuch mit Drosselung |
| --- | --- | --- | --- | --- | --- | --- |
| Standard | 3 | 100 ms | 1000 ms | 500 | 5 | 5 |
| Veraltet | 4 | 100 ms | 500 ms | 500 | 5 | 0 |
| Adaptiv | 3 | 100 ms | 100 ms | 500 | 5 | 5 |
**Anmerkung**
DynamoDB-Clients verwenden standardmäßig eine maximale Anzahl von Wiederholungsversuchen von 8 für alle Wiederholungsstrategien, was höher ist als die Werte in der obigen Tabelle für andere Clients. AWS-Service
## Geben Sie eine Strategie an
Sie haben vier Möglichkeiten, eine Strategie für Ihren Servicekunden festzulegen.
### Im Code
Wenn Sie einen Client erstellen, können Sie einen Lambda-Ausdruck mit einer Wiederholungsstrategie konfigurieren. Der folgende Ausschnitt konfiguriert eine standardmäßige Wiederholungsstrategie, die Standardwerte auf einem DynamoDB-Dienstclient verwendet.
```
DynamoDbClient client = DynamoDbClient.builder()
.overrideConfiguration(o -> o.retryStrategy(RetryMode.STANDARD))
.build();
```
Sie können oder anstelle von angeben. `RetryMode.LEGACY` `RetryMode.ADAPTIVE` `RetryMode.STANDARD`
### Als Profileinstellung
`retry_mode`Als Profileinstellung in die [gemeinsam genutzte AWS Konfigurationsdatei](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) aufnehmen. Geben Sie `standard``legacy`, oder `adaptive` als Wert an. Wenn diese Einstellung als Profileinstellung festgelegt ist, verwenden alle Service-Clients, die erstellt werden, während das Profil aktiv ist, die angegebene Wiederholungsstrategie mit Standardwerten. Sie können diese Einstellung überschreiben, indem Sie eine Wiederholungsstrategie im Code konfigurieren, wie zuvor gezeigt.
Mit dem folgenden Profil verwenden alle Service-Clients die standardmäßige Wiederholungsstrategie.
```
[profile dev]
region = us-east-2
retry_mode = standard
```
### Als JVM-Systemeigenschaft
Mithilfe der Systemeigenschaft können Sie eine Wiederholungsstrategie für alle Service-Clients konfigurieren, sofern sie nicht im Code überschrieben wird. `aws.retryMode` Geben Sie`standard`, oder `legacy` als Wert an. `adaptive`
Verwenden Sie den `-D` Schalter, wenn Sie Java aufrufen, wie im folgenden Befehl gezeigt.
```
java -Daws.retryMode=standard ...
```
Sie können auch die Systemeigenschaft im Code festlegen, *bevor Sie* einen Client erstellen, wie im folgenden Codeausschnitt gezeigt.
```
public void main(String[] args) {
// Set the property BEFORE any AWS service clients are created.
System.setProperty("aws.retryMode", "standard");
...
}
```
### Mit einer Umgebungsvariablen
Sie können die `AWS_RETRY_MODE` Umgebungsvariable auch mit dem Wert `standard``legacy`, oder verwenden`adaptive`. Wie bei einer Profileinstellung oder einer JVM-Systemeigenschaft konfiguriert die Umgebungsvariable alle Service-Clients mit dem angegebenen Wiederholungsmodus, sofern Sie keinen Client im Code konfigurieren.
Mit dem folgenden Befehl wird der Wiederholungsmodus `standard` für die aktuelle Shell-Sitzung auf festgelegt.
```
export AWS_RETRY_MODE=standard
```
## Passen Sie eine Strategie an
Sie können jede Wiederholungsstrategie anpassen, indem Sie die maximale Anzahl der Versuche, die Backoff-Strategie und die Ausnahmen, die wiederholt werden können, festlegen. Sie können anpassen, wann Sie eine Wiederholungsstrategie oder einen Client erstellen, indem Sie einen Override-Builder verwenden, der weitere Verfeinerungen der konfigurierten Strategie ermöglicht.
### Passen Sie die Anzahl der Versuche an
Sie können die maximale Anzahl von Versuchen während der Client-Erstellung konfigurieren, wie in der folgenden Anweisung gezeigt. Mit der folgenden Anweisung wird die standardmäßige Wiederholungsstrategie für den Client auf maximal 5 Versuche angepasst — ein erster Versuch plus 4 Wiederholungen.
```
DynamoDbClient client = DynamoDbClient.builder()
.overrideConfiguration(o -> o.retryStrategy(b -> b.maxAttempts(5)))
.build();
```
Alternativ können Sie die Strategie erstellen und sie dem Client wie im folgenden Codebeispiel zur Verfügung stellen. Der folgende Code ersetzt die standardmäßigen 3 maximalen Versuche durch 10 und konfiguriert einen DynamoDB-Client mit der benutzerdefinierten Strategie.
```
StandardRetryStrategy strategy = AwsRetryStrategy.standardRetryStrategy()
.toBuilder()
.maxAttempts(10)
.build();
DynamoDbClient client = DynamoDbClient.builder()
.overrideConfiguration(o -> o.retryStrategy(strategy))
.build();
```
**Warnung**
Wir empfehlen, dass Sie jeden Client mit einer eindeutigen Instanz konfigurieren. `RetryStrategy` Wenn eine `RetryStrategy` Instanz gemeinsam genutzt wird, können Fehler auf einem Client das Wiederholungsverhalten auf dem anderen Client beeinflussen.
Sie können auch die maximale Anzahl von Versuchen für alle Clients festlegen, indem Sie [externe Einstellungen](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html) anstelle von Code verwenden. Sie konfigurieren diese Einstellung wie im [Geben Sie eine Strategie an](#retry-strategies-specify) Abschnitt beschrieben.
### Passen Sie Ausnahmen an, die wiederholt werden können
Sie können zusätzliche Ausnahmen konfigurieren, die bei der Client-Erstellung Wiederholungsversuche auslösen. Diese Anpassung ist für Sonderfälle vorgesehen, in denen Ausnahmen ausgelöst werden, die nicht in der Standardgruppe wiederholbarer Ausnahmen enthalten sind.
Die `retryOnExceptionOrCause` Methoden `retryOnException` und **fügen** dem bestehenden Satz wiederholbarer Ausnahmen neue Ausnahmetypen hinzu. Sie ersetzen nicht den Standardsatz. Auf diese Weise können Sie das Wiederholungsverhalten erweitern und gleichzeitig die standardmäßigen Wiederholungsfunktionen des SDK beibehalten.
Die `retryOnExceptionOrCause` Methode fügt eine Ausnahme hinzu, die erneut versucht werden kann, wenn das SDK die direkte Ausnahme auslöst oder wenn die Ausnahme als Ursache in eine andere Ausnahme eingeschlossen ist.
Der folgende Codeausschnitt zeigt die Methoden, mit denen Sie die Wiederholungsausnahmen anpassen: und. `retryOnException` `retryOnExceptionOrCause` Die `retryOnExceptionOrCause` Methode fügt eine Ausnahme hinzu, die erneut versucht werden kann, wenn das SDK die direkte Ausnahme auslöst oder wenn die Ausnahme umschlossen ist.
```
DynamoDbClient client = DynamoDbClient.builder()
.overrideConfiguration(o -> o.retryStrategy(
b -> b.retryOnException(EdgeCaseException.class)
.retryOnExceptionOrCause(WrappedEdgeCaseException.class)))
.build();
```
**Wichtig**
Wiederholungen sind für den asynchronen Kinesis-Client deaktiviert, wenn Sie eine [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kinesis/KinesisAsyncClient.html#subscribeToShard(software.amazon.awssdk.services.kinesis.model.SubscribeToShardRequest,software.amazon.awssdk.services.kinesis.model.SubscribeToShardResponseHandler)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kinesis/KinesisAsyncClient.html#subscribeToShard(software.amazon.awssdk.services.kinesis.model.SubscribeToShardRequest,software.amazon.awssdk.services.kinesis.model.SubscribeToShardResponseHandler))Methode aufrufen, unabhängig von der Konfiguration der Wiederholungsstrategie.
### Passen Sie die Backoff-Strategie an
Sie können die Backoff-Strategie erstellen und sie dem Kunden zur Verfügung stellen.
Der folgende Code erstellt eine`BackoffStrategy`, die die exponentielle Verzögerungs-Backoff-Strategie der Standardstrategie mit exponentieller Verzögerung ersetzt.
```
BackoffStrategy backoffStrategy =
BackoffStrategy.exponentialDelay(Duration.ofMillis(150), // The base delay.
Duration.ofSeconds(15)); // The maximum delay.
DynamoDbClient client = DynamoDbClient.builder()
.overrideConfiguration(o -> o.retryStrategy(
b -> b.backoffStrategy(backoffStrategy)))
.build();
```
## Migration von zu `RetryPolicy` `RetryStrategy`
`RetryPolicy`(die Retry Policy API) wird auf absehbare Zeit unterstützt. Wenn Sie derzeit eine Instanz von verwenden, `RetryPolicy` um Ihren Client zu konfigurieren, wird alles wie zuvor funktionieren. Hinter den Kulissen passt das Java SDK es an eine an`RetryStrategy`. Die neuen Schnittstellen für Wiederholungsstrategien bieten dieselbe Funktionalität wie a, werden `RetryPolicy` jedoch anders erstellt und konfiguriert.
# Timeouts konfigurieren in AWS SDK for Java 2.x
Das AWS SDK for Java 2.x bietet mehrere Ebenen der Timeout-Konfiguration, um Sie bei der Erstellung robuster Anwendungen zu unterstützen. Das SDK bietet verschiedene Arten von Timeouts, die zusammenarbeiten, um die Leistung und Zuverlässigkeit Ihrer Anwendung zu optimieren.
Es gibt zwei Hauptkategorien von Timeouts im SDK:
+ **Service Client Timeouts — Timeouts** auf hoher Ebene, die API-Operationen steuern
+ **HTTP-Client-Timeouts — Niedrige Timeouts**, die die Netzwerkkommunikation steuern
## Timeouts für Service-Clients
Timeouts für Serviceclients funktionieren auf API-Ebene und steuern das Gesamtverhalten von Dienstvorgängen, einschließlich Wiederholungsversuchen und Mehrfachversuchen.
### Timeout bei API-Aufrufen
Das Timeout für API-Aufrufe legt die maximale Zeitdauer für einen gesamten API-Vorgang fest, einschließlich aller Wiederholungsversuche. Dieses Timeout gibt eine feste Grenze dafür, wie lange Ihre Anwendung auf den Abschluss eines vollständigen Vorgangs wartet.
```
S3Client s3Client = S3Client.builder()
.overrideConfiguration(ClientOverrideConfiguration.builder()
.apiCallTimeout(Duration.ofMinutes(2)) // Total time for entire operation, such as when you call the getObject method.
.build())
.build();
```
Wichtigste Merkmale:
+ Beinhaltet alle Wiederholungsversuche.
+ Beinhaltet die Wartezeit zwischen Wiederholungsversuchen.
+ Bietet die absolute maximale Wartezeit.
+ Verhindert, dass Operationen auf unbestimmte Zeit ausgeführt werden.
### Timeout für API-Aufrufversuche
Das Timeout für API-Aufrufversuche legt die maximale Zeit für einen einzelnen Versuch einer API-Operation fest. Wenn dieses Timeout überschritten wird, versucht das SDK den Vorgang erneut (sofern Wiederholungen konfiguriert sind), anstatt den gesamten Aufruf fehlschlagen zu lassen.
```
S3Client s3Client = S3Client.builder()
.overrideConfiguration(ClientOverrideConfiguration.builder()
.apiCallAttemptTimeout(Duration.ofSeconds(30)) // Time for single attempt.
.build())
.build();
```
Wichtigste Merkmale:
+ Gilt nur für einzelne Versuche.
+ Ermöglicht schnelle Fehler und Wiederholungen bei langsamen Anfragen.
+ Muss kürzer als das Timeout für API-Aufrufe sein.
+ Hilft bei der Identifizierung vorübergehender Probleme und bei deren Behebung.
### Konfigurieren Sie Timeouts für den Service-Client
Sie können Service-Client-Timeouts global für alle Operationen oder pro Anfrage konfigurieren:
**Globale Konfiguration:**
```
S3Client s3Client = S3Client.builder()
.overrideConfiguration(b -> b
.apiCallTimeout(Duration.ofSeconds(105L))
.apiCallAttemptTimeout(Duration.ofSeconds(25L)))
.build();
// When you use the s3Client for an API operation, the SDK uses the configured timeout values.
```
**Konfiguration pro Anfrage:**
```
S3Client basicS3Client = S3Client.create();
// The following configuration uses the same settings as shown before, but these settings
// apply to only the `putObject` call. When you use `basicS3Client` in another API call without
// supplying the override configuration, there are no API timeout limits. No timeout limits is the default for the SDK.
AwsRequestOverrideConfiguration overrideConfiguration = AwsRequestOverrideConfiguration.builder()
.apiCallTimeout(Duration.ofSeconds(105L))
.apiCallAttemptTimeout(Duration.ofSeconds(25L))
.build();
basicS3Client.putObject(b -> b
.bucket("amzn-s3-demo-bucket")
.key("example-key")
.overrideConfiguration(overrideConfiguration),
RequestBody.fromString("test"));
```
### Bewährte Methoden für API-Timeouts
Das SDK for Java 2.x legt standardmäßig keine Timeouts für API-Aufrufe oder einzelne API-Aufrufversuche fest. Legen Sie Timeouts sowohl für einzelne Versuche als auch für die gesamte Anfrage fest. Auf diese Weise schlägt Ihre Anwendung schnell fehl, wenn vorübergehende Probleme dazu führen, dass Anforderungsversuche länger dauern, oder wenn schwerwiegende Netzwerkprobleme auftreten.
## Zeitüberschreitungen beim HTTP-Client
HTTP-Client-Timeouts wirken auf Netzwerkebene und steuern verschiedene Aspekte der HTTP-Kommunikation. Diese Timeouts variieren je nachdem, welche HTTP-Client-Implementierung Sie verwenden.
### Verbindungstimeout
Das Verbindungs-Timeout steuert, wie lange gewartet werden muss, wenn eine neue Verbindung zum Endpunkt hergestellt wird AWS-Service .
```
// Available with all HTTP clients.
ApacheHttpClient.builder()
.connectionTimeout(Duration.ofSeconds(5L))
.build();
```
Zweck:
+ Beugt Problemen mit der Netzwerkverbindung vor.
+ Schlägt schnell fehl, wenn Dienste nicht erreichbar sind.
+ Unverzichtbar für Anwendungen, die eine reaktionsschnelle Fehlerbehandlung benötigen.
### Socket-Timeout (Apache und URLConnection Clients)
Das Socket-Timeout steuert, wie lange bei einer bestehenden Verbindung auf Daten gewartet werden soll.
```
ApacheHttpClient.builder()
.socketTimeout(Duration.ofSeconds(30L)) // Time to wait for response data.
.build();
```
### Timeouts für Lese- und Schreibvorgänge (Netty-Client)
Der Netty-Client bietet separate Timeouts für Lese- und Schreibvorgänge:
```
NettyNioAsyncHttpClient.builder()
.readTimeout(Duration.ofSeconds(30L)) // Reading response data.
.writeTimeout(Duration.ofSeconds(30L)) // Writing request data.
.build();
```
### Timeout für TLS-Verhandlungen (Netty-Client)
Steuert die für TLS/SSL den Handshake zulässige Zeit:
```
NettyNioAsyncHttpClient.builder()
.tlsNegotiationTimeout(Duration.ofSeconds(3L))
.build();
```
### Timeouts für den Verbindungspool
Einige HTTP-Clients bieten Timeouts für Verbindungspool-Operationen:
```
ApacheHttpClient.builder()
.connectionAcquisitionTimeout(Duration.ofSeconds(10L)) // Wait for pool connection.
.connectionTimeToLive(Duration.ofMinutes(5L)) // Maximum connection age.
.connectionMaxIdleTime(Duration.ofSeconds(60L)) // Maximum idle time.
.build()
```
Das [Konfigurieren Sie HTTP-Clients](http-configuration.md) enthält weitere Informationen zu HTTP-Clients im AWS SDK for Java 2.x
## Timeout-Interaktionen und Hierarchie
Für eine korrekte Konfiguration ist es entscheidend zu verstehen, wie verschiedene Timeouts interagieren:
### Timeout-Hierarchie
```
API Call Timeout (2 minutes)
├── Retry Attempt 1
│ ├── API Call Attempt Timeout (45 seconds)
│ └── HTTP Client Timeouts
│ ├── Connection Timeout (5 seconds)
│ ├── TLS Negotiation Timeout (3 seconds)
│ └── Read/Write Timeout (30 seconds)
├── Retry Attempt 2
│ └── [Same structure as Attempt 1]
└── Retry Attempt 3
└── [Same structure as Attempt 1]
```
### Regeln für die Konfiguration
Timeout bei API-Aufrufen ≥ Timeout bei API-Aufrufversuchen
```
// Correct configuration.
.apiCallTimeout(Duration.ofMinutes(2)) // 120 seconds.
.apiCallAttemptTimeout(Duration.ofSeconds(30)) // 30 seconds.
```
Zeitlimit für API-Aufrufversuche ≥ Zeitüberschreitungen für HTTP-Clients
```
// HTTP client timeouts must be less than attempt timeout.
.apiCallAttemptTimeout(Duration.ofSeconds(30L)) // 30 seconds.
// HTTP client configuration.
.connectionTimeout(Duration.ofSeconds(5L)) // 5 seconds.
.readTimeout(Duration.ofSeconds(25L)) // 25 seconds (< 30).
```
Konto für mehrere Versuche
```
// If you have 3 retry attempts, each taking up to 30 seconds
// API call timeout must be at least 90 seconds plus overhead.
.apiCallTimeout(Duration.ofMinutes(2L)) // 120 seconds.
.apiCallAttemptTimeout(Duration.ofSeconds(30)) // 30 seconds per attempt.
```
## Verwenden Sie die Standardeinstellungen für intelligente Konfigurationen
Das SDK bietet intelligente Standardeinstellungen, die automatisch die entsprechenden Timeout-Werte konfigurieren:
```
// Enable smart defaults.
S3Client client = S3Client.builder()
.defaultsMode(DefaultsMode.AUTO) // Automatically choose appropriate defaults.
.build();
// Available modes:
// - STANDARD: Balanced defaults
// - IN_REGION: Optimized for same-region calls
// - CROSS_REGION: Optimized for cross-region calls
// - MOBILE: Optimized for mobile applications
// - AUTO: Automatically detect and choose appropriate mode
// - LEGACY: Provides settings that were used before smart defaults existed.
```
Intelligente Standardeinstellungen konfigurieren automatisch:
+ Werte für das Verbindungs-Timeout.
+ Timeout-Werte für TLS-Verhandlungen.
+ Andere Client-Einstellungen.
## Übersicht
Eine effektive Timeout-Konfiguration AWS SDK for Java 2.x erfordert ein Verständnis der Wechselwirkung zwischen Service-Client-Timeouts und HTTP-Client-Timeouts:
1. **Timeouts für Service-Clients** steuern das API-Verhalten auf hoher Ebene.
1. **HTTP-Client-Timeouts** steuern das Netzwerkverhalten auf niedriger Ebene.
1. **Die richtige Hierarchie** stellt sicher, dass Timeouts effektiv zusammenarbeiten.
1. **Intelligente Standardeinstellungen** bieten gute Ausgangspunkte für die meisten Anwendungen.
Konfigurieren Sie Timeouts entsprechend Ihrem Anwendungsfall, um Anwendungen zu erstellen, die sowohl gegen Netzwerkprobleme resistent sind als auch auf Benutzer reagieren.
# Konfiguration von Observability-Funktionen in AWS SDK for Java 2.x
Telemetrie ist die automatisierte Erfassung und Übertragung von Daten aus entfernten Quellen, mit denen Sie das Verhalten Ihres Systems überwachen und analysieren können.
Die Beobachtbarkeit im SDK for Java 2.x bietet Entwicklern umfassende Einblicke in die Interaktion ihrer Java-Anwendungen AWS-Services mithilfe umfangreicher Telemetriedaten, die den gesamten Anforderungszyklus erfassen. Diese Funktionen ermöglichen es Ihnen, Telemetriesignale wie Metriken, Protokolle und Traces zu sammeln, zu analysieren und zu visualisieren. So können Sie Anforderungsmuster überwachen, Engpässe identifizieren und die AWS Interaktionen Ihrer Anwendung optimieren, um die Zuverlässigkeit und Leistung zu verbessern.
**Topics**
+ [Kennzahlen](metrics.md)
+ [Überwachen](monitoring-overview.md)
+ [Protokollierung](logging-slf4j.md)
# Veröffentlichen Sie SDK-Metriken aus dem AWS SDK for Java 2.x
Mit dem können AWS SDK for Java 2.x Sie Metriken über die Service-Clients und Anfragen in Ihrer Anwendung sammeln, die Ausgabe in Amazon CloudWatch Logs analysieren und dann darauf reagieren.
Standardmäßig ist die Erfassung von Metriken im SDK deaktiviert. Dieses Thema hilft Ihnen dabei, es zu aktivieren und zu konfigurieren.
## Erste Schritte mit SDK-Metriken
Um die Erfassung von Metriken in Ihrer Anwendung zu aktivieren, wählen Sie die für Ihren Anwendungsfall geeignete Implementierung der `[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)` Schnittstelle aus und folgen Sie den detaillierten Anweisungen zur Einrichtung:
**Für Anwendungen mit langer Laufzeit:**
+ Verwenden von `[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)`
+ Vollständige Anweisungen zur Einrichtung, Codebeispiele und Konfigurationsoptionen finden Sie unter [Veröffentlichen von SDK-Metriken von Anwendungen mit langer Laufzeit](metric-pub-impl-cwmp.md).
**Für AWS Lambda Funktionen:**
+ Verwenden von `[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)`
+ Vollständige Setup-Anweisungen, Abhängigkeiten und Lambda-spezifische Konfigurationen finden Sie unter [SDK-Metriken für AWS Lambda Funktionen veröffentlichen](metric-pub-impl-emf.md).
**Zur Fehlerbehebung und zur Konsolenausgabe:**
+ Verwenden von `[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)`
+ Anweisungen [zur Einrichtung, Formatierungsoptionen und Beispiele für lokale Entwicklung und Problembehebung finden Sie unter SDK-Metriken für Entwicklung und Debugging an die Konsole ausgeben](metric-pub-impl-logging.md).
## Schnelle Implementierungsvorschau
So sehen die Aktivierungsmetriken für jeden Anwendungsfall aus:
**Anwendungen mit langer Laufzeit:**
```
MetricPublisher metricsPub = CloudWatchMetricPublisher.create();
DynamoDbClient ddb = DynamoDbClient.builder()
.overrideConfiguration(c -> c.addMetricPublisher(metricsPub))
.build();
```
**Lambda-Funktionen:**
```
EmfMetricLoggingPublisher emfPublisher = EmfMetricLoggingPublisher.builder()
.namespace("MyApp")
.build();
DynamoDbClient dynamoDb = DynamoDbClient.builder()
.overrideConfiguration(c -> c.addMetricPublisher(emfPublisher))
.build();
```
**Entwicklung und Debugging:**
```
MetricPublisher loggingPublisher = LoggingMetricPublisher.create();
S3Client s3 = S3Client.builder()
.overrideConfiguration(c -> c.addMetricPublisher(loggingPublisher))
.build();
```
## Beschränkung der Metriken des AWS CRT-basierten S3-Clients
Der [AWS CRT-basierte S3-Client unterstützt derzeit keine Erfassung](crt-based-s3-client.md) von SDK-Metriken. Der Builder für eine AWS CRT-basierte S3-Client-Instanz bietet keine Methoden zur Konfiguration von [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3CrtAsyncClientBuilder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3CrtAsyncClientBuilder.html)Metrik-Publishern.
## Wann sind Metriken verfügbar?
Metriken sind in der Regel innerhalb von 5-10 Minuten verfügbar, nachdem sie vom SDK for Java ausgegeben wurden. Genaue up-to-date Metriken finden Sie mindestens 10 Minuten nach der Ausgabe der Metriken aus Ihren Java-Anwendungen in Cloudwatch.
## Welche Informationen werden gesammelt?
Die Erfassung von Metriken umfasst Folgendes:
+ Anzahl der API-Anfragen, einschließlich der Frage, ob sie erfolgreich waren oder nicht
+ Informationen über die von AWS-Services Ihnen aufgerufenen API-Anfragen, einschließlich der zurückgegebenen Ausnahmen
+ Die Dauer verschiedener Operationen wie Marshalling, Signierung und HTTP-Anfragen
+ HTTP-Client-Metriken, wie die Anzahl der offenen Verbindungen, die Anzahl der ausstehenden Anfragen und der Name des verwendeten HTTP-Clients
**Anmerkung**
Die verfügbaren Metriken variieren je nach HTTP-Client.
Eine vollständige Liste finden Sie unter [Service-Client-Metriken](metrics-list.md).
## Wie kann ich diese Informationen verwenden?
Sie können die vom SDK gesammelten Metriken verwenden, um die Service-Clients in Ihrer Anwendung zu überwachen. Sie können sich allgemeine Nutzungstrends ansehen, Anomalien identifizieren, zurückgegebene Service-Client-Ausnahmen überprüfen oder sich ein bestimmtes Problem genauer ansehen. Mithilfe von Amazon CloudWatch Logs können Sie auch Alarme erstellen, die Sie benachrichtigen, sobald Ihre Anwendung einen von Ihnen definierten Zustand erreicht.
Weitere Informationen finden Sie unter [Verwenden von Amazon CloudWatch Logs-Metriken](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html) und [Verwenden von Amazon CloudWatch Logs-Alarmen](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) im [Amazon CloudWatch Logs-Benutzerhandbuch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/).
# Veröffentlichen Sie SDK-Metriken von Anwendungen mit langer Laufzeit mithilfe der AWS SDK for Java 2.x
Da die `[CloudWatchMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/cloudwatch/CloudWatchMetricPublisher.html)` Implementierung Metriken aggregiert und regelmäßig verzögert auf Amazon hochlädt, eignet sich ihre Verwendung am besten für Anwendungen CloudWatch mit langer Laufzeit.
Die Standardeinstellungen des Metrik-Publishers sollen den Speicherverbrauch und die CloudWatch Kosten minimieren und gleichzeitig einen nützlichen Einblick in die Metrikdaten bieten.
## Einrichtung
Führen Sie die folgenden Schritte aus`CloudWatchMetricPublisher`, bevor Sie Metriken mithilfe von aktivieren und verwenden können.
### Schritt 1: Fügen Sie die erforderliche Abhängigkeit hinzu
Konfigurieren Sie Ihre Projektabhängigkeiten (z. B. in Ihrer `pom.xml` `build.gradle` OR-Datei) so, dass die Version `2.14.0` oder eine neuere Version von verwendet wird AWS SDK für Java.
Fügen Sie die artifactId `cloudwatch-metric-publisher` mit der Versionsnummer `2.14.0` oder später in die Abhängigkeiten Ihres Projekts ein.
Beispiel:
```
software.amazon.awssdkbom[2.30.11](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)pomimportsoftware.amazon.awssdkcloudwatch-metric-publisher
```
### Schritt 2: Konfigurieren Sie die erforderlichen Berechtigungen
Aktivieren Sie die `cloudwatch:PutMetricData` Berechtigungen für die IAM-Identität, die vom Herausgeber der Metriken verwendet wird, damit das SDK for Java Metriken schreiben kann.
## Aktivieren Sie Metriken für eine bestimmte Anfrage
Die folgende Klasse zeigt, wie Sie den CloudWatch Metrik-Publisher für eine Anfrage an Amazon DynamoDB aktivieren. Es verwendet die Standardkonfiguration für den Metrik-Publisher.
```
import software.amazon.awssdk.metrics.MetricPublisher;
import software.amazon.awssdk.metrics.publishers.cloudwatch.CloudWatchMetricPublisher;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.ListTablesRequest;
public class DefaultConfigForRequest {
// Use one MetricPublisher for your application. It can be used with requests or service clients.
static MetricPublisher metricsPub = CloudWatchMetricPublisher.create();
public static void main(String[] args) {
DynamoDbClient ddb = DynamoDbClient.create();
// Publish metrics the for ListTables operation.
ddb.listTables(ListTablesRequest.builder()
.overrideConfiguration(c -> c.addMetricPublisher(metricsPub))
.build());
// Perform more work in your application.
// A MetricsPublisher has its own lifecycle independent of any service client or request that uses it.
// If you no longer need the publisher, close it to free up resources.
metricsPub.close(); // All metrics stored in memory are flushed to CloudWatch.
// Perform more work with the DynamoDbClient instance without publishing metrics.
// Close the service client when you no longer need it.
ddb.close();
}
}
```
**Wichtig**
Stellen Sie sicher, dass Ihre Anwendung die `[MetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/MetricPublisher.html)` Instanz `close` aufruft, wenn der Service Client nicht mehr verwendet wird. Wenn Sie dies nicht tun, können Thread- oder Dateideskriptorlecks auftreten.
## Aktivieren Sie Übersichtsmetriken für einen bestimmten Service-Client
Der folgende Codeausschnitt zeigt, wie Sie einen CloudWatch Metrik-Publisher mit Standardeinstellungen für einen Service Client aktivieren.
```
MetricPublisher metricsPub = CloudWatchMetricPublisher.create();
DynamoDbClient ddb = DynamoDbClient.builder()
.overrideConfiguration(c -> c.addMetricPublisher(metricsPub))
.build();
```
## Passen Sie einen Herausgeber für Metriken an CloudWatch
In der folgenden Klasse wird gezeigt, wie Sie eine benutzerdefinierte Konfiguration für den Metrik-Publisher für einen bestimmten Service-Client einrichten. Zu den Anpassungen gehören das Laden eines bestimmten Profils, die Angabe einer AWS Region, in die der Herausgeber der Metriken Anfragen sendet, und die Anpassung, wie oft der Herausgeber Metriken sendet. CloudWatch
```
import software.amazon.awssdk.auth.credentials.ProfileCredentialsProvider;
import software.amazon.awssdk.core.metrics.CoreMetric;
import software.amazon.awssdk.metrics.MetricPublisher;
import software.amazon.awssdk.metrics.publishers.cloudwatch.CloudWatchMetricPublisher;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.cloudwatch.CloudWatchAsyncClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import java.time.Duration;
public class CustomConfigForDDBClient {
// Use one MetricPublisher for your application. It can be used with requests or service clients.
static MetricPublisher metricsPub = CloudWatchMetricPublisher.builder()
.cloudWatchClient(CloudWatchAsyncClient.builder()
.region(Region.US_WEST_2)
.credentialsProvider(ProfileCredentialsProvider.create("cloudwatch"))
.build())
.uploadFrequency(Duration.ofMinutes(5))
.maximumCallsPerUpload(100)
.namespace("ExampleSDKV2Metrics")
.detailedMetrics(CoreMetric.API_CALL_DURATION)
.build();
public static void main(String[] args) {
DynamoDbClient ddb = DynamoDbClient.builder()
.overrideConfiguration(c -> c.addMetricPublisher(metricsPub))
.build();
// Publish metrics for DynamoDB operations.
ddb.listTables();
ddb.describeEndpoints();
ddb.describeLimits();
// Perform more work in your application.
// A MetricsPublisher has its own lifecycle independent of any service client or request that uses it.
// If you no longer need the publisher, close it to free up resources.
metricsPub.close(); // All metrics stored in memory are flushed to CloudWatch.
// Perform more work with the DynamoDbClient instance without publishing metrics.
// Close the service client when you no longer need it.
ddb.close();
}
}
```
Die im vorherigen Snippet gezeigten Anpassungen haben die folgenden Auswirkungen.
+ Mit `cloudWatchClient` dieser Methode können Sie den CloudWatch Client anpassen, der zum Senden von Metriken verwendet wird. In diesem Beispiel verwenden wir eine andere Region als die Standardregion *us-east-1*, in die der Client Metriken sendet. Wir verwenden auch ein anderes benanntes Profil, *cloudwatch*, dessen Anmeldeinformationen zur Authentifizierung von Anfragen verwendet werden. CloudWatch Diese Anmeldeinformationen müssen über die erforderlichen Berechtigungen verfügen. `cloudwatch:PutMetricData`
+ Mit `uploadFrequency` dieser Methode können Sie angeben, wie oft der Herausgeber Metriken hochlädt. CloudWatch Die Standardeinstellung ist einmal pro Minute.
+ Die `maximumCallsPerUpload` Methode begrenzt die Anzahl der Aufrufe pro Upload. Der Standardwert lautet „unbegrenzt“.
+ Standardmäßig veröffentlicht das SDK for Java 2.x Metriken unter dem `AwsSdk/JavaSdk2` Namespace. Sie können die `namespace` Methode verwenden, um einen anderen Wert anzugeben.
+ Standardmäßig veröffentlicht das SDK zusammenfassende Metriken. Übersichtsmetriken bestehen aus Durchschnitt, Minimum, Maximum, Summe und Stichprobenanzahl. Durch die Angabe einer oder mehrerer SDK-Metriken in der `detailedMetrics` Methode veröffentlicht das SDK zusätzliche Daten für jede Metrik. Diese zusätzlichen Daten ermöglichen Perzentilstatistiken wie p90 und p99, die Sie abfragen können. CloudWatch Die detaillierten Metriken sind besonders nützlich für Latenzmetriken wie`APICallDuration`, mit denen die Latenz für SDK-Client-Anfragen gemessen end-to-end wird. Sie können Felder der `[CoreMetric](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/metrics/CoreMetric.html)` Klasse verwenden, um andere gängige SDK-Metriken anzugeben.
**Nächste Schritte:** Wenn Sie auch mit Lambda-Funktionen arbeiten, finden Sie unter [SDK-Metriken veröffentlichen Informationen zu AWS Lambda Funktionen für die](metric-pub-impl-emf.md) Veröffentlichung von EMF-basierten Metriken.
# Veröffentlichen Sie SDK-Metriken für AWS Lambda Funktionen mit dem AWS SDK for Java 2.x
Da Lambda-Funktionen in der Regel Millisekunden bis Minuten lang ausgeführt werden, besteht bei jeder Verzögerung beim Senden der Metriken die Gefahr eines `CloudWatchMetricPublisher` Datenverlusts.
`[EmfMetricLoggingPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.html)`bietet einen geeigneteren Ansatz, indem Metriken sofort als strukturierte Protokolleinträge im [CloudWatch Embedded Metric Format](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Embedded_Metric_Format.html) (EMF) geschrieben werden. `EmfMetricLoggingPublisher`funktioniert in Ausführungsumgebungen mit integrierter Integration mit Amazon CloudWatch Logs wie AWS Lambda Amazon Elastic Container Service.
## Einrichtung
Führen Sie die folgenden Schritte aus`EmfMetricLoggingPublisher`, bevor Sie Metriken mithilfe von aktivieren und verwenden können.
### Schritt 1: Fügen Sie die erforderliche Abhängigkeit hinzu
Konfigurieren Sie Ihre Projektabhängigkeiten (z. B. in Ihrer `pom.xml` `build.gradle` OR-Datei) so, dass die Version `2.30.3` oder eine neuere Version von verwendet wird AWS SDK für Java.
Fügen Sie die artifactId `emf-metric-logging-publisher` mit der Versionsnummer `2.30.3` oder später in die Abhängigkeiten Ihres Projekts ein.
Beispiel:
```
software.amazon.awssdkbom[2.30.11](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)pomimportsoftware.amazon.awssdkemf-metric-logging-publisher
```
### Schritt 2: Konfigurieren Sie die erforderlichen Berechtigungen
Aktivieren Sie die `logs:PutLogEvents` Berechtigungen für die IAM-Identität, die vom Herausgeber der Metriken verwendet wird, damit das SDK for Java Protokolle im EMF-Format schreiben kann.
### Schritt 3: Protokollierung einrichten
Um eine korrekte Erfassung der Messwerte zu gewährleisten, konfigurieren Sie Ihre Protokollierung so, dass sie auf der Konsole oder `INFO` niedriger ausgegeben wird (z. B.`DEBUG`). In Ihrer `log4j2.xml` Datei:
```
```
Weitere Informationen zum Einrichten einer `log4j2.xml` Datei finden Sie im [Thema Protokollierung](logging-slf4j.md) in diesem Handbuch.
## Konfigurieren und verwenden `EmfMetricLoggingPublisher`
Die folgende Lambda-Funktionsklasse erstellt und konfiguriert zunächst eine `EmfMetricLoggingPublisher` Instance und verwendet sie dann mit einem Amazon DynamoDB-Serviceclient:
```
public class GameIdHandler implements RequestHandler, String> {
private final EmfMetricLoggingPublisher emfPublisher;
private final DynamoDbClient dynamoDb;
public GameIdHandler() {
// Build the publisher.
this.emfPublisher = EmfMetricLoggingPublisher.builder()
.namespace("namespace")
.dimensions(CoreMetric.SERVICE_ID,
CoreMetric.OPERATION_NAME)
.build();
// Add the publisher to the client.
this.dynamoDb = DynamoDbClient.builder()
.overrideConfiguration(c -> c.addMetricPublisher(emfPublisher))
.region(Region.of(System.getenv("AWS_REGION")))
.build();
}
@Override
public String handleRequest(Map event, Context context) {
Map gameItem = new HashMap<>();
gameItem.put("gameId", AttributeValue.builder().s(event.get("id")).build());
PutItemRequest putItemRequest = PutItemRequest.builder()
.tableName("games")
.item(gameItem)
.build();
dynamoDb.putItem(putItemRequest);
return "Request handled";
}
}
```
Wenn der DynamoDB-Client die `putItem` Methode ausführt, veröffentlicht er automatisch Metriken in einem CloudWatch Log-Stream im EMF-Format.
### Beispiel für ein EMF-Protokollereignis
Wenn Sie beispielsweise das folgende Ereignis an die GameHandler Lambda-Funktion senden, wobei die Protokollierung wie oben gezeigt konfiguriert ist:
```
{
"id": "23456"
}
```
Nachdem die Funktion das Ereignis verarbeitet hat, finden Sie zwei Protokollereignisse, die dem folgenden Beispiel ähneln. Das JSON-Objekt im zweiten Ereignis enthält die Java SDK-Metrikdaten für den `PutItem` Vorgang mit DynamoDB.
Wenn ein Protokollereignis im EMF-Format CloudWatch empfangen wird, analysiert es automatisch das strukturierte JSON, um Metrikdaten zu extrahieren. CloudWatch erstellt dann entsprechende Metriken und speichert gleichzeitig den ursprünglichen Protokolleintrag in CloudWatch Logs.
```
2025-07-11 15:58:30 [main] INFO org.example.GameIdHandler:39 - Received map: {id=23456}
2025-07-11 15:58:34 [main] INFO software.amazon.awssdk.metrics.publishers.emf.EmfMetricLoggingPublisher:43 -
{
"_aws": {
"Timestamp": 1752249513975,
"LogGroupName": "/aws/lambda/GameId",
"CloudWatchMetrics": [
{
"Namespace": "namespace",
"Dimensions": [
[
"OperationName",
"ServiceId"
]
],
"Metrics": [
{
"Name": "AvailableConcurrency"
},
{
"Name": "PendingConcurrencyAcquires"
},
{
"Name": "ServiceCallDuration",
"Unit": "Milliseconds"
},
{
"Name": "EndpointResolveDuration",
"Unit": "Milliseconds"
},
{
"Name": "MaxConcurrency"
},
{
"Name": "BackoffDelayDuration",
"Unit": "Milliseconds"
},
{
"Name": "MarshallingDuration",
"Unit": "Milliseconds"
},
{
"Name": "LeasedConcurrency"
},
{
"Name": "SigningDuration",
"Unit": "Milliseconds"
},
{
"Name": "ConcurrencyAcquireDuration",
"Unit": "Milliseconds"
},
{
"Name": "ApiCallSuccessful"
},
{
"Name": "RetryCount"
},
{
"Name": "UnmarshallingDuration",
"Unit": "Milliseconds"
},
{
"Name": "ApiCallDuration",
"Unit": "Milliseconds"
},
{
"Name": "CredentialsFetchDuration",
"Unit": "Milliseconds"
}
]
}
]
},
"AvailableConcurrency": 0,
"PendingConcurrencyAcquires": 0,
"OperationName": "PutItem",
"ServiceCallDuration": 1339,
"EndpointResolveDuration": 81,
"MaxConcurrency": 50,
"BackoffDelayDuration": 0,
"ServiceId": "DynamoDB",
"MarshallingDuration": 181,
"LeasedConcurrency": 1,
"SigningDuration": 184,
"ConcurrencyAcquireDuration": 83,
"ApiCallSuccessful": 1,
"RetryCount": 0,
"UnmarshallingDuration": 85,
"ApiCallDuration": 1880,
"CredentialsFetchDuration": 138
}
```
Die [API-Dokumentation](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/publishers/emf/EmfMetricLoggingPublisher.Builder.html) für `EmfMetricLoggingPublisher.Builder` zeigt die Konfigurationsoptionen, die Sie verwenden können.
Sie können die EMF-Metrikprotokollierung auch für eine einzelne Anfrage aktivieren, wie [für gezeigt](metric-pub-impl-cwmp.md#enable-metrics-for-a-specific-request). CloudWatchMetricPublisher
**Nächste Schritte:** Informationen zu Anwendungen mit langer Laufzeit finden Sie unter [Veröffentlichen von SDK-Metriken aus Anwendungen mit langer Laufzeit](metric-pub-impl-cwmp.md) für die Veröffentlichung von CloudWatch basierten Metriken.
# Geben Sie SDK-Metriken auf der Konsole aus, indem Sie AWS SDK for Java 2.x
Die `[LoggingMetricPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/metrics/LoggingMetricPublisher.html)` Implementierung gibt Metriken direkt an die Konsole oder in die Protokolldateien Ihrer Anwendung aus. Dieser Ansatz ist ideal für die Entwicklung, das Debuggen und um zu verstehen, welche Metriken das SDK sammelt, ohne externe Dienste wie Amazon CloudWatch zu benötigen.
Im Gegensatz zu `CloudWatchMetricPublisher` und `EmfMetricLoggingPublisher` `LoggingMetricPublisher` bietet sofortige Ausgabe ohne Verzögerungen oder externe Abhängigkeiten. Dadurch eignet es sich perfekt für lokale Entwicklungs- und Problemlösungsszenarien.
## Wann sollte es verwendet werden LoggingMetricPublisher
Verwenden Sie `LoggingMetricPublisher`, wenn Sie Folgendes benötigen:
+ Erfassung von Metriken während der Entwicklung debuggen
+ Verstehen Sie, welche Metriken das SDK für Ihren Betrieb sammelt
+ Beheben Sie Leistungsprobleme lokal
+ Testen Sie die Erfassung von Metriken ohne Abhängigkeiten von externen Diensten
+ Sehen Sie sich Metriken sofort in Ihrer Konsole oder in Ihren Protokolldateien an
**Anmerkung**
`LoggingMetricPublisher`wird nicht für Produktionsumgebungen empfohlen, in denen Sie persistente Speicher- und Analysefunktionen für Metriken benötigen.
## Richten Sie die Konsolenprotokollierung für Metriken ein
Um die `LoggingMetricPublisher` Ausgabe zu sehen, konfigurieren Sie Ihr Logging-Framework so, dass `INFO` Level-Meldungen angezeigt werden. Die folgende `log4j2.xml` Konfiguration stellt sicher, dass Metriken in Ihrer Konsole angezeigt werden:
```
```
Diese Konfiguration weist das SDK an, Metriken auf der entsprechenden `INFO` Ebene an Ihre Konsole auszugeben. Die `LoggingMetricPublisher` Logger-Konfiguration stellt sicher, dass die Metrikausgabe auch dann angezeigt wird, wenn Ihr Root-Logger eine höhere Ebene wie `WARN` oder verwendet`ERROR`.
## Aktivieren Sie Konsolenmetriken für einen Service-Client
Das folgende Beispiel zeigt, wie Sie einen erstellen `LoggingMetricPublisher` und ihn mit einem Amazon Simple Storage Service-Client verwenden:
```
import software.amazon.awssdk.metrics.LoggingMetricPublisher;
import software.amazon.awssdk.metrics.MetricPublisher;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
// Create a LoggingMetricPublisher with default settings.
MetricPublisher metricPublisher = LoggingMetricPublisher.create();
// Add the publisher to your service client.
S3Client s3Client = S3Client.builder()
.region(Region.US_EAST_1)
.overrideConfiguration(config -> config.addMetricPublisher(metricPublisher))
.build();
// Make requests - metrics will appear in your console.
s3Client.listBuckets();
// Clean up resources.
metricPublisher.close();
s3Client.close();
```
## Wählen Sie das metrische Ausgabeformat
`LoggingMetricPublisher`unterstützt zwei Ausgabeformate:
+ **PLAIN-Format (Standard):** Gibt Metriken als kompakte, einzeilige Einträge aus
+ **PRETTY-Format:** Gibt Metriken in einem mehrzeiligen, für Menschen lesbaren Format aus
Das folgende Beispiel zeigt, wie das PRETTY-Format verwendet wird, um das Lesen während der Entwicklung zu erleichtern:
```
import org.slf4j.event.Level;
import software.amazon.awssdk.metrics.LoggingMetricPublisher;
// Create a LoggingMetricPublisher with PRETTY format.
MetricPublisher prettyMetricPublisher = LoggingMetricPublisher.create(
Level.INFO,
LoggingMetricPublisher.Format.PRETTY
);
// Use with your service client.
S3Client s3Client = S3Client.builder()
.region(Region.US_EAST_1)
.overrideConfiguration(config -> config.addMetricPublisher(prettyMetricPublisher))
.build();
```
## Vollständiges Beispiel
Das folgende Beispiel zeigt die Verwendung `LoggingMetricPublisher` auf zwei Arten:
+ Auf der Ebene des Serviceclients
+ Für eine einzige Anfrage
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.event.Level;
import software.amazon.awssdk.metrics.LoggingMetricPublisher;
import software.amazon.awssdk.metrics.MetricPublisher;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.ListBucketsRequest;
import software.amazon.awssdk.services.s3.model.ListBucketsResponse;
/**
* Demonstrates how to use LoggingMetricPublisher with AWS S3 SDK for Java 2.x.
*
* This demo focuses on the S3 listBuckets operation to show how metrics are collected
* and logged to the console for development and debugging purposes.
*
* LoggingMetricPublisher is ideal for:
* - Development and debugging
* - Console output for troubleshooting
* - Understanding what metrics are being collected
* - Testing metric collection without external dependencies
*/
public class S3LoggingMetricPublisherDemo {
private static final Logger logger = LoggerFactory.getLogger(S3LoggingMetricPublisherDemo.class);
public static void main(String[] args) {
S3LoggingMetricPublisherDemo demo = new S3LoggingMetricPublisherDemo();
demo.demonstrateUsage();
}
/**
* Demonstrates basic usage with S3Client and metrics enabled at the client level.
*/
private void demonstrateUsage() {
// Create a LoggingMetricPublisher with default settings. The SDK logs metrics as text in a single line.
// The default settings are equivalent to using `LoggingMetricPublisher.Format.PLAIN`.
MetricPublisher metricPublisher = LoggingMetricPublisher.create();
// Create an S3 client with metrics enabled.
try (S3Client s3Client = S3Client.builder()
.region(Region.US_EAST_1)
.overrideConfiguration(config -> config.addMetricPublisher(metricPublisher))
.build()) {
// Make the listBuckets request - metrics will be logged to console.
ListBucketsResponse response = s3Client.listBuckets(ListBucketsRequest.builder().build());
// The next block shows the using a different LoggingMetricPublisher with a `PRETTY` format.
// Since the metric publisher is added to the request using the `overrideConfiguration`, this formatting
// applies only to the one request.
try {
s3Client.listBuckets(ListBucketsRequest.builder()
.overrideConfiguration(config -> config
.addMetricPublisher(LoggingMetricPublisher.create(
Level.INFO, LoggingMetricPublisher.Format.PRETTY)))
.build());
} catch (Exception e) {
logger.info("Request failed with metrics logged: {}", e.getMessage());
}
logger.info("Found {} buckets in your AWS account.", response.buckets().size());
} catch (Exception e) {
logger.error("Error during S3 operation: {}", e.getMessage());
logger.info("Note: This is expected if AWS credentials are not configured.");
}
// Close the metric publisher to flush any remaining metrics.
metricPublisher.close();
}
}
```
Der Code protokolliert Folgendes auf der Konsole:
```
INFO LoggingMetricPublisher - Metrics published: MetricCollection(name=ApiCall, metrics=[MetricRecord(metric=MarshallingDuration, value=PT0.005409792S), MetricRecord(metric=RetryCount, value=0), MetricRecord(metric=ApiCallSuccessful, value=true), MetricRecord(metric=OperationName, value=ListBuckets), MetricRecord(metric=EndpointResolveDuration, value=PT0.000068S), MetricRecord(metric=ApiCallDuration, value=PT0.163802958S), MetricRecord(metric=CredentialsFetchDuration, value=PT0.145686542S), MetricRecord(metric=ServiceEndpoint, value=https://s3.amazonaws.com), MetricRecord(metric=ServiceId, value=S3)], children=[MetricCollection(name=ApiCallAttempt, metrics=[MetricRecord(metric=TimeToFirstByte, value=PT0.138816S), MetricRecord(metric=SigningDuration, value=PT0.007803459S), MetricRecord(metric=ReadThroughput, value=165153.96002660287), MetricRecord(metric=ServiceCallDuration, value=PT0.138816S), MetricRecord(metric=AwsExtendedRequestId, value=e13Swj3uwn0qP1Oz+m7II5OGq7jf8xxT8H18iDfRBCQmDg+gU4ek91Xrsl8XxRLROlIzCAPQtsQF0DAAWOb8ntuKCzX2AJdj), MetricRecord(metric=HttpStatusCode, value=200), MetricRecord(metric=BackoffDelayDuration, value=PT0S), MetricRecord(metric=TimeToLastByte, value=PT0.148915667S), MetricRecord(metric=AwsRequestId, value=78AW9BM7SWR6YMGB)], children=[MetricCollection(name=HttpClient, metrics=[MetricRecord(metric=MaxConcurrency, value=50), MetricRecord(metric=AvailableConcurrency, value=0), MetricRecord(metric=LeasedConcurrency, value=1), MetricRecord(metric=ConcurrencyAcquireDuration, value=PT0.002623S), MetricRecord(metric=PendingConcurrencyAcquires, value=0), MetricRecord(metric=HttpClientName, value=Apache)], children=[])])])
INFO LoggingMetricPublisher - [4e6f2bb5] ApiCall
INFO LoggingMetricPublisher - [4e6f2bb5] ┌──────────────────────────────────────────┐
INFO LoggingMetricPublisher - [4e6f2bb5] │ MarshallingDuration=PT0.000063S │
INFO LoggingMetricPublisher - [4e6f2bb5] │ RetryCount=0 │
INFO LoggingMetricPublisher - [4e6f2bb5] │ ApiCallSuccessful=true │
INFO LoggingMetricPublisher - [4e6f2bb5] │ OperationName=ListBuckets │
INFO LoggingMetricPublisher - [4e6f2bb5] │ EndpointResolveDuration=PT0.000024375S │
INFO LoggingMetricPublisher - [4e6f2bb5] │ ApiCallDuration=PT0.018463083S │
INFO LoggingMetricPublisher - [4e6f2bb5] │ CredentialsFetchDuration=PT0.000022334S │
INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceEndpoint=https://s3.amazonaws.com │
INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceId=S3 │
INFO LoggingMetricPublisher - [4e6f2bb5] └──────────────────────────────────────────┘
INFO LoggingMetricPublisher - [4e6f2bb5] ApiCallAttempt
INFO LoggingMetricPublisher - [4e6f2bb5] ┌───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
INFO LoggingMetricPublisher - [4e6f2bb5] │ TimeToFirstByte=PT0.0165575S │
INFO LoggingMetricPublisher - [4e6f2bb5] │ SigningDuration=PT0.000301125S │
INFO LoggingMetricPublisher - [4e6f2bb5] │ ReadThroughput=1195591.792850103 │
INFO LoggingMetricPublisher - [4e6f2bb5] │ ServiceCallDuration=PT0.0165575S │
INFO LoggingMetricPublisher - [4e6f2bb5] │ AwsExtendedRequestId=3QI1eenRuokdszWqZBmBMDUmko6FlSmHkM+CUMNMeLor7gJml4D4lv6QXUZ1zWoTgG+tHbr6yo2vHdz4h1P8PDovvtMFRCeB │
INFO LoggingMetricPublisher - [4e6f2bb5] │ HttpStatusCode=200 │
INFO LoggingMetricPublisher - [4e6f2bb5] │ BackoffDelayDuration=PT0S │
INFO LoggingMetricPublisher - [4e6f2bb5] │ TimeToLastByte=PT0.017952625S │
INFO LoggingMetricPublisher - [4e6f2bb5] │ AwsRequestId=78AVFAF795AAWAXH │
INFO LoggingMetricPublisher - [4e6f2bb5] └───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
INFO LoggingMetricPublisher - [4e6f2bb5] HttpClient
INFO LoggingMetricPublisher - [4e6f2bb5] ┌───────────────────────────────────────┐
INFO LoggingMetricPublisher - [4e6f2bb5] │ MaxConcurrency=50 │
INFO LoggingMetricPublisher - [4e6f2bb5] │ AvailableConcurrency=0 │
INFO LoggingMetricPublisher - [4e6f2bb5] │ LeasedConcurrency=1 │
INFO LoggingMetricPublisher - [4e6f2bb5] │ ConcurrencyAcquireDuration=PT0.00004S │
INFO LoggingMetricPublisher - [4e6f2bb5] │ PendingConcurrencyAcquires=0 │
INFO LoggingMetricPublisher - [4e6f2bb5] │ HttpClientName=Apache │
INFO LoggingMetricPublisher - [4e6f2bb5] └───────────────────────────────────────┘
INFO S3LoggingMetricPublisherDemo - Found 6 buckets in your AWS account.
```
### Zusätzliche Artefakte für das Beispiel
Maven-Datei `pom.xml`
```
4.0.0com.examples3-logging-metric-publisher-demo1.0.0jarAWS S3 LoggingMetricPublisher DemoDemonstrates how to use LoggingMetricPublisher with AWS S3 SDK for Java 2.x1717UTF-82.31.662.24.3software.amazon.awssdkbom${aws.java.sdk.version}pomimportorg.apache.logging.log4jlog4j-bom${log4j.version}pomimportsoftware.amazon.awssdks3org.apache.logging.log4jlog4j-slf4j2-implorg.apache.logging.log4jlog4j-coreorg.apache.maven.pluginsmaven-compiler-plugin3.13.01717
```
`Log4j2.xml` Konfigurationsdatei
```
```
Die Metriken umfassen Zeitinformationen, Servicedetails, Vorgangsnamen und HTTP-Statuscodes, die Ihnen helfen, die AWS API-Nutzungsmuster Ihrer Anwendung zu verstehen.
## Nächste Schritte
Nach der Verwendung `LoggingMetricPublisher` für die Entwicklung und das Debuggen sollten Sie die folgenden Optionen für Produktionsumgebungen in Betracht ziehen:
+ Verwenden Sie für Anwendungen mit langer Laufzeit, [CloudWatchMetricPublisher](metric-pub-impl-cwmp.md)um Metriken CloudWatch zur Analyse und Benachrichtigung an Amazon zu senden
+ Verwenden Sie [EmfMetricLoggingPublisher](metric-pub-impl-emf.md)für AWS Lambda Funktionen die Veröffentlichung von Metriken im CloudWatch eingebetteten metrischen Format
# AWS SDK for Java 2.x: Umfassende Metrik-Referenz
Mit dem AWS SDK for Java 2.x können Sie Metriken von den Service-Clients in Ihrer Anwendung sammeln und diese Metriken dann auf [Amazon](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) veröffentlichen (ausgeben) CloudWatch.
In diesen Tabellen sind die Metriken, die Sie sammeln können, sowie alle Anforderungen für die Nutzung des HTTP-Clients aufgeführt.
Weitere Informationen zur Aktivierung und Konfiguration von Metriken für das SDK finden Sie unter [SDK-Metriken aktivieren](metrics.md).
## Bei jeder Anfrage gesammelte Metriken
| Metrikname | Description | Typ |
| --- | --- | --- |
| ApiCallDuration | Die Dauer des API-Aufrufs. Dies schließt alle unternommenen Anrufversuche ein. | Dauer\$1 |
| ApiCallSuccessful | Wahr, wenn der API-Aufruf erfolgreich war, andernfalls falsch. | Boolesch |
| CredentialsFetchDuration | Die Zeitdauer, die benötigt wird, um die Signaturdaten für den API-Aufruf abzurufen. | Dauer\$1 |
| EndpointResolveDuration | Die Dauer der Auflösung des Endpunkts, der für den API-Aufruf verwendet wurde. | Dauer\$1 |
| MarshallingDuration | Die Zeitdauer, die benötigt wird, um die SDK-Anfrage in eine HTTP-Anfrage umzuwandeln. | Dauer\$1 |
| OperationName | Der Name des aufgerufenen Dienstvorgangs. | Zeichenfolge |
| RetryCount | Die Anzahl der Wiederholungen, die das SDK bei der Ausführung der Anforderung ausgeführt hat. 0 bedeutet, dass die Anfrage beim ersten Mal funktioniert hat und dass keine Wiederholungsversuche unternommen wurden. Weitere Hinweise zur Konfiguration des Wiederholungsverhaltens finden Sie unter. [Strategien für Wiederholungsversuche](retry-strategy.md#retry-strategies) | Ganzzahl |
| ServiceId | Die eindeutige ID für den Dienst. | Zeichenfolge |
| ServiceEndpoint | Der Endpunkt für den Dienst. | URI |
| TokenFetchDuration | Die Dauer des Abrufs der Signaturdaten für den API-Aufruf. | Dauer\$1 |
[\$1 java.time.Duration.](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html)
## Für jeden Anforderungsversuch gesammelte Metriken
Für jeden API-Aufruf sind möglicherweise mehrere Versuche erforderlich, bevor eine Antwort eingeht. Diese Metriken werden für jeden Versuch gesammelt.
### Kernmetriken
| Metrikname | Description | Typ |
| --- | --- | --- |
| AwsExtendedRequestId | Die erweiterte Anfrage-ID der Serviceanfrage. | Zeichenfolge |
| AwsRequestId | Die Anforderungs-ID der Serviceanfrage. | Zeichenfolge |
| BackoffDelayDuration | Die Dauer, während der das SDK auf diesen API-Aufrufversuch gewartet hat. Der Wert basiert auf dem auf dem Client `[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/api/BackoffStrategy.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/api/BackoffStrategy.html)` eingestellten Wert. Weitere Informationen finden Sie im [Strategien für Wiederholungsversuche](retry-strategy.md#retry-strategies) Abschnitt dieses Handbuchs. | Dauer\$1 |
| ErrorType | Die Art des Fehlers, der bei einem Anrufversuch aufgetreten ist. Folgende Werte sind möglich: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/sdk-for-java/latest/developer-guide/metrics-list.html) | Zeichenfolge |
| ReadThroughput | Der Lesedurchsatz des Clients, definiert als. `NumberOfResponseBytesRead / (TTLB - TTFB)` Dieser Wert wird in Byte pro Sekunde angegeben. Beachten Sie, dass diese Metrik nur die Byte misst, die innerhalb von `ResponseTransformer` oder gelesen `AsyncResponseTransformer` werden. Daten, die außerhalb des Transformators gelesen werden — beispielsweise wenn der Antwortstream als Ergebnis des Transformators zurückgegeben wird — sind nicht in der Berechnung enthalten. | Double |
| WriteThroughput | Der Schreibdurchsatz des Clients, definiert als. `RequestBytesWritten / (LastByteWrittenTime - FirstByteWrittenTime)` Dieser Wert wird in Byte pro Sekunde angegeben. Diese Metrik misst die Geschwindigkeit, mit der das SDK den Anforderungstext für den HTTP-Client bereitstellt. Sie schließt den Verbindungsaufbau, die TLS-Handshake-Zeit und die Serververarbeitungszeit aus. Diese Metrik wird nur für Anfragen gemeldet, die einen Streaming-Hauptteil wie S3 haben. PutObject Beachten Sie, dass diese Metrik die Pufferung auf der HTTP-Client-Ebene nicht berücksichtigt. Die tatsächliche Netzwerkübertragungsrate kann niedriger sein, wenn der HTTP-Client Daten vor dem Senden zwischenspeichert. Diese Metrik stellt eine Obergrenze des Netzwerkdurchsatzes dar. | Double |
| ServiceCallDuration | Die Dauer, die benötigt wird, um eine Verbindung mit dem Dienst herzustellen (oder eine Verbindung vom Verbindungspool herzustellen), die serialisierte Anfrage zu senden und die erste Antwort zu empfangen (z. B. HTTP-Statuscode und Header). Dies beinhaltet NICHT die Zeit, die zum Lesen der gesamten Antwort vom Dienst benötigt wird. | Dauer\$1 |
| SigningDuration | Die Zeitdauer für das Signieren der HTTP-Anfrage. | Dauer\$1 |
| TimeToFirstByte | Die Zeitspanne zwischen dem Senden der HTTP-Anfrage (einschließlich des Aufbaus einer Verbindung) an den Dienst und dem Empfangen des ersten Bytes der Header in der Antwort. | Dauer\$1 |
| TimeToLastByte | Die Zeitspanne zwischen dem Senden der HTTP-Anfrage (einschließlich des Aufbaus einer Verbindung) an den Dienst und dem Empfangen des letzten Bytes der Antwort. Beachten Sie, dass APIs sich diese Metrik bei zurückgesendeten Streaming-Antworten über die Zeit erstreckt, bis das `ResponseTransformer` Oder `AsyncResponseTransformer` abgeschlossen ist. | Dauer\$1 |
| UnmarshallingDuration | Die Zeitdauer für das Unmarshalling der HTTP-Antwort auf eine SDK-Antwort. Hinweis: Bei Streaming-Vorgängen beinhaltet dies nicht die Zeit zum Lesen der Antwortnutzdaten. | Dauer\$1 |
[\$1 java.time.Duration.](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html)
### HTTP-Metriken
| Metrikname | Description | Typ | HTTP-Client erforderlich\$1 |
| --- | --- | --- | --- |
| AvailableConcurrency | Die Anzahl zusätzlicher gleichzeitiger Anfragen, die der HTTP-Client unterstützt, ohne dass neue Verbindungen zum Zielserver hergestellt werden. Bei HTTP/1-Vorgängen entspricht dies der Anzahl der inaktiven TCP-Verbindungen, die mit dem Dienst eingerichtet wurden. Bei HTTP/2-Vorgängen entspricht dies der Anzahl der inaktiven Streams. Hinweis: Dieser Wert variiert je nach Implementierung des HTTP-Clients: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/sdk-for-java/latest/developer-guide/metrics-list.html) Der Wert ist auf eine einzelne HTTP-Clientinstanz beschränkt und schließt die Parallelität anderer HTTP-Clients in derselben JVM aus. | Ganzzahl | Apache, Netty, CRT |
| ConcurrencyAcquireDuration | Die Zeitdauer, die benötigt wird, um einen Kanal aus dem Verbindungspool zu beziehen. Bei HTTP/1-Vorgängen entspricht ein Kanal einer TCP-Verbindung. Bei HTTP/2-Operationen entspricht ein Kanal einem HTTP/2-Stream-Kanal. Der Erwerb eines neuen Kanals kann Zeit beinhalten für: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/sdk-for-java/latest/developer-guide/metrics-list.html) | Dauer\$1 | Apache, Netty, CRT |
| HttpClientName | Der Name des für die Anfrage verwendeten HTTPs. | Zeichenfolge | Apache, Netty, CRT |
| HttpStatusCode | Der Statuscode der HTTP-Antwort. | Ganzzahl | Beliebig |
| LeasedConcurrency | Die Anzahl der Anfragen, die der HTTP-Client derzeit ausführt. Bei HTTP/1-Vorgängen entspricht dies der Anzahl der aktiven TCP-Verbindungen mit dem Dienst (ohne inaktive Verbindungen). Bei HTTP/2-Vorgängen entspricht dies der Anzahl der aktiven HTTP-Streams mit dem Dienst (ohne Stream-Kapazität im Leerlauf). Hinweis: Dieser Wert variiert je nach Implementierung des HTTP-Clients: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/sdk-for-java/latest/developer-guide/metrics-list.html) Der Wert ist auf eine einzelne HTTP-Clientinstanz beschränkt und schließt die Parallelität anderer HTTP-Clients in derselben JVM aus. | Ganzzahl | Apache, Netty, CRT |
| LocalStreamWindowSize | Die lokale HTTP/2-Fenstergröße in Byte für den Stream, der diese Anforderung ausführt. | Ganzzahl | Netty |
| MaxConcurrency | Die maximale Anzahl gleichzeitiger Anfragen, die der HTTP-Client unterstützt. Bei HTTP/1-Vorgängen entspricht dies der maximalen Anzahl von TCP-Verbindungen, die der HTTP-Client bündeln kann. Bei HTTP/2-Vorgängen entspricht dies der maximalen Anzahl von Streams, die der HTTP-Client bündeln kann. Hinweis: Dieser Wert variiert je nach Implementierung des HTTP-Clients: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/sdk-for-java/latest/developer-guide/metrics-list.html) Der Wert ist auf eine einzelne HTTP-Clientinstanz beschränkt und schließt die Parallelität anderer HTTP-Clients in derselben JVM aus. | Ganzzahl | Apache, Netty, CRT |
| PendingConcurrencyAcquires | Die Anzahl der Anfragen, die auf Parallelität vom HTTP-Client warten. Bei HTTP/1-Vorgängen entspricht dies der Anzahl der Anfragen, die darauf warten, dass eine TCP-Verbindung hergestellt wird oder aus dem Verbindungspool zurückkehrt. Bei HTTP/2-Operationen entspricht dies der Anzahl der Anfragen, die auf einen neuen Stream (und möglicherweise eine neue HTTP/2-Verbindung) aus dem Verbindungspool warten. Hinweis: Dieser Wert variiert je nach Implementierung des HTTP-Clients: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/sdk-for-java/latest/developer-guide/metrics-list.html) Der Wert ist auf eine einzelne HTTP-Clientinstanz beschränkt und schließt die Parallelität anderer HTTP-Clients in derselben JVM aus. | Ganzzahl | Apache, Netty, CRT |
| RemoteStreamWindowSize | Die Größe des Remote-HTTP/2-Fensters in Byte für den Stream, der diese Anforderung ausführt. | Ganzzahl | Netty |
\$1 [java.time.Duration](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/time/Duration.html).
Die in der Spalte verwendeten Begriffe bedeuten:
+ Apache: der Apache-basierte HTTP-Client () `[ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html)`
+ Netty: der Netty-basierte HTTP-Client () `[NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)`
+ CRT: der AWS CRT-basierte HTTP-Client () `[AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html)`
+ Beliebig: Die Erfassung von Metrikdaten hängt nicht vom HTTP-Client ab. Dazu gehört auch der URLConnection basierte HTTP-Client () `[UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)`
# AWS SDK for Java 2.x Anwendungen überwachen
Die Überwachung ist ein wichtiger Bestandteil der Aufrechterhaltung der Zuverlässigkeit, Verfügbarkeit und Leistung von Anwendungen, die das AWS SDK for Java 2.x verwenden. AWS bietet die folgenden Überwachungstools, um das SDK for Java 2.x zu beobachten, zu melden, wenn etwas nicht stimmt, und gegebenenfalls automatische Maßnahmen zu ergreifen:
+ *Amazon CloudWatch* überwacht Ihre AWS Ressourcen und die Anwendungen, auf denen Sie laufen, AWS in Echtzeit. Sie können Kennzahlen erfassen und verfolgen, benutzerdefinierte Dashboards erstellen und Alarme festlegen, die Sie benachrichtigen oder Maßnahmen ergreifen, wenn eine bestimmte Metrik einen von Ihnen festgelegten Schwellenwert erreicht. Sie können beispielsweise die CPU-Auslastung oder andere Kennzahlen Ihrer EC2 Amazon-Instances CloudWatch verfolgen und bei Bedarf automatisch neue Instances starten. Weitere Informationen finden Sie im [ CloudWatch Amazon-Benutzerhandbuch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/).
+ Mit *Amazon CloudWatch Logs* können Sie Ihre Protokolldateien von EC2 Amazon-Instances und anderen Quellen überwachen CloudTrail, speichern und darauf zugreifen. CloudWatch Logs kann Informationen in den Protokolldateien überwachen und Sie benachrichtigen, wenn bestimmte Schwellenwerte erreicht werden. Sie können Ihre Protokolldaten auch in einem sehr robusten Speicher archivieren. Weitere Informationen finden Sie im [Amazon CloudWatch Logs-Benutzerhandbuch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/).
+ *AWS CloudTrail*erfasst API-Aufrufe und zugehörige Ereignisse, die von oder im Namen Ihres AWS Kontos getätigt wurden, und übermittelt die Protokolldateien an einen von Ihnen angegebenen Amazon S3 S3-Bucket. Sie können feststellen, welche Benutzer und Konten angerufen wurden AWS, von welcher Quell-IP-Adresse aus die Anrufe getätigt wurden und wann die Aufrufe erfolgten. Weitere Informationen finden Sie im [AWS CloudTrail -Benutzerhandbuch](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/).
# Loggen mit dem SDK for Java 2.x
Das AWS SDK for Java 2.x verwendet [SLF4J](https://www.slf4j.org/manual.html), eine Abstraktionsschicht, die die Verwendung eines beliebigen von mehreren Protokollierungssystemen zur Laufzeit ermöglicht.
Zu den unterstützten Protokollierungssystemen gehören unter anderem das Java Logging Framework und Apache [Log4j 2.](https://logging.apache.org/log4j/2.x/) In diesem Thema erfahren Sie, wie Sie Log4j 2 als Protokollierungssystem für die Arbeit mit dem SDK verwenden.
## Log4j 2-Konfigurationsdatei
In der Regel verwenden Sie eine Konfigurationsdatei `log4j2.xml` mit dem Namen Log4j 2. Beispiel-Konfigurationsdateien werden nachfolgend angezeigt. Weitere Informationen über die Werte in der Konfigurationsdatei finden Sie im [Handbuch für die Log4j-Konfiguration](https://logging.apache.org/log4j/2.x/manual/configuration.html).
Die `log4j2.xml` Datei muss sich beim Start Ihrer Anwendung im Klassenpfad befinden. Für ein Maven-Projekt legen Sie die Datei in das Verzeichnis. `/src/main/resources`
Die `log4j2.xml` Konfigurationsdatei spezifiziert Eigenschaften wie die [Protokollierungsebene](https://logging.apache.org/log4j/2.x/manual/configuration.html#Loggers), an die die Protokollausgabe gesendet wird (z. B. [an eine Datei oder an die Konsole](https://logging.apache.org/log4j/2.x/manual/appenders.html)), und das [Format der Ausgabe](https://logging.apache.org/log4j/2.x/manual/layouts.html). Die Protokollierungsebene gibt den Detaillierungsgrad an, den Log4j 2 ausgibt. [https://logging.apache.org/log4j/2.x/manual/architecture.html#](https://logging.apache.org/log4j/2.x/manual/architecture.html#) Die Protokollierungsebene wird für jede Hierarchie separat festgelegt. Die Hauptprotokollierungshierarchie, die Sie mit dem verwenden, ist. AWS SDK for Java 2.x `software.amazon.awssdk`
## Protokollierungsabhängigkeit hinzufügen
Verwenden Sie Folgendes, um die Log4J 2-Bindung für SLF4 J in Ihrer Build-Datei zu konfigurieren.
------
#### [ Maven ]
Fügen Sie Ihrer Datei die folgenden Elemente hinzu`pom.xml`.
```
...
org.apache.logging.log4jlog4j-slf4j2-implVERSION
...
```
------
#### [ Gradle–Kotlin DSL ]
Fügen Sie Ihrer `build.gradle.kts` Datei Folgendes hinzu.
```
...
dependencies {
...
implementation("org.apache.logging.log4j:log4j-slf4j2-impl:VERSION")
...
}
...
```
------
Verwenden Sie `2.20.0` für die Mindestversion des `log4j-slf4j2-impl` Artefakts. Verwenden Sie für die neueste Version die in [Maven](https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-slf4j2-impl) Central veröffentlichte Version. Ersetzen Sie sie *VERSION* durch die Version, die Sie verwenden werden.
## SDK-spezifische Fehler und Warnungen
Wir empfehlen, die Logger-Hierarchie von „software.amazon.awssdk“ immer auf „WARN“ gesetzt zu lassen, um wichtige Nachrichten aus den SDK-Clientbibliotheken abzufangen. Wenn der Amazon S3 S3-Client beispielsweise feststellt, dass Ihre Anwendung nicht ordnungsgemäß geschlossen wurde `InputStream` und möglicherweise Ressourcen verloren gehen, meldet der S3-Client dies in Form einer Warnmeldung an die Protokolle. Dadurch wird auch sichergestellt, dass Nachrichten protokolliert werden, wenn der Client Schwierigkeiten bei der Verarbeitung von Anforderungen oder Antworten hat.
In der folgenden `log4j2.xml` Datei wird das `rootLogger` auf „WARN“ gesetzt, was dazu führt, dass Warnmeldungen und Meldungen auf Fehlerebene von allen Loggern in der Anwendung ausgegeben werden, *einschließlich* der Logger in der Hierarchie „software.amazon.awssdk“. Alternativ können Sie die Logger-Hierarchie „software.amazon.awssdk“ explizit auf „WARN“ setzen, falls sie verwendet wird. ``
**Beispiel für eine Konfigurationsdatei Log4j2.xml**
Diese Konfiguration protokolliert Meldungen auf den Ebenen „ERROR“ und „WARN“ auf der Konsole für alle Logger-Hierarchien.
```
```
## Protokollierung der Zusammenfassung von Anforderungen/Antworten
Jede Anfrage an eine AWS-Service generiert eine eindeutige AWS Anfrage-ID, die nützlich ist, wenn Sie auf ein Problem mit der Bearbeitung einer AWS-Service Anfrage stoßen. AWS Anfragen IDs sind programmgesteuert über [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/exception/SdkServiceException.html#requestId()](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/exception/SdkServiceException.html#requestId())Objekte im SDK für jeden fehlgeschlagenen Serviceabruf zugänglich und können auch über die Protokollebene „DEBUG“ des Loggers „software.amazon.awssdk.request“ gemeldet werden.
Die folgende Datei bietet eine Zusammenfassung der Anfragen und Antworten. `log4j2.xml`
```
```
Hier finden Sie ein Beispiel für die Protokollausgabe:
```
2022-09-23 16:02:08 [main] DEBUG software.amazon.awssdk.request:85 - Sending Request: DefaultSdkHttpFullRequest(httpMethod=POST, protocol=https, host=dynamodb.us-east-1.amazonaws.com, encodedPath=/, headers=[amz-sdk-invocation-id, Content-Length, Content-Type, User-Agent, X-Amz-Target], queryParameters=[])
2022-09-23 16:02:08 [main] DEBUG software.amazon.awssdk.request:85 - Received successful response: 200, Request ID: QS9DUMME2NHEDH8TGT9N5V53OJVV4KQNSO5AEMVJF66Q9ASUAAJG, Extended Request ID: not available
```
Wenn Sie nur an der Anfrage-ID interessiert sind, verwenden Sie``.
## SDK-Protokollierung auf Debug-Ebene
Wenn Sie weitere Informationen darüber benötigen, was das SDK tut, können Sie die Protokollierungsebene des `software.amazon.awssdk` Loggers auf einstellen. `DEBUG` Auf dieser Ebene gibt das SDK eine große Menge an Details aus. Wir empfehlen daher, diese Stufe festzulegen, um Fehler mithilfe von Integrationstests zu beheben.
Auf dieser Protokollierungsebene protokolliert das SDK Informationen zur Konfiguration, zur Auflösung von Anmeldeinformationen, zur Ausführung von Interceptoren, TLS-Aktivitäten auf hoher Ebene, zur Signierung von Anfragen und vieles mehr.
Im Folgenden finden Sie eine Auswahl von Anweisungen, die vom SDK auf `DEBUG` Ebene eines `S3Client#listBuckets()` Anrufs ausgegeben werden.
```
DEBUG s.a.a.r.p.AwsRegionProviderChain:57 - Unable to load region from software.amazon.awssdk.regions.providers.SystemSettingsRegionProvider@324dcd31:Unable to load region from system settings. Region must be specified either via environment variable (AWS_REGION) or system property (aws.region).
DEBUG s.a.a.c.i.h.l.ClasspathSdkHttpServiceProvider:85 - The HTTP implementation loaded is software.amazon.awssdk.http.apache.ApacheSdkHttpService@a23a01d
DEBUG s.a.a.c.i.ExecutionInterceptorChain:85 - Creating an interceptor chain that will apply interceptors in the following order: [software.amazon.awssdk.core.internal.interceptor.HttpChecksumValidationInterceptor@69b2f8e5, software.amazon.awssdk.awscore.interceptor.HelpfulUnknownHostExceptionInterceptor@6331250e, software.amazon.awssdk.awscore.eventstream.EventStreamInitialRequestInterceptor@a10c1b5, software.amazon.awssdk.awscore.interceptor.TraceIdExecutionInterceptor@644abb8f, software.amazon.awssdk.services.s3.auth.scheme.internal.S3AuthSchemeInterceptor@1a411233, software.amazon.awssdk.services.s3.endpoints.internal.S3ResolveEndpointInterceptor@70325d20, software.amazon.awssdk.services.s3.endpoints.internal.S3RequestSetEndpointInterceptor@7c2327fa, software.amazon.awssdk.services.s3.internal.handlers.StreamingRequestInterceptor@4d847d32, software.amazon.awssdk.services.s3.internal.handlers.CreateBucketInterceptor@5f462e3b, software.amazon.awssdk.services.s3.internal.handlers.CreateMultipartUploadRequestInterceptor@3d7fa3ae, software.amazon.awssdk.services.s3.internal.handlers.DecodeUrlEncodedResponseInterceptor@58065f0c, software.amazon.awssdk.services.s3.internal.handlers.GetBucketPolicyInterceptor@3605c4d3, software.amazon.awssdk.services.s3.internal.handlers.S3ExpressChecksumInterceptor@585c13de, software.amazon.awssdk.services.s3.internal.handlers.AsyncChecksumValidationInterceptor@187eb9a8, software.amazon.awssdk.services.s3.internal.handlers.SyncChecksumValidationInterceptor@726a6b94, software.amazon.awssdk.services.s3.internal.handlers.EnableTrailingChecksumInterceptor@6ad11a56, software.amazon.awssdk.services.s3.internal.handlers.ExceptionTranslationInterceptor@522b2631, software.amazon.awssdk.services.s3.internal.handlers.GetObjectInterceptor@3ff57625, software.amazon.awssdk.services.s3.internal.handlers.CopySourceInterceptor@1ee29c84, software.amazon.awssdk.services.s3.internal.handlers.ObjectMetadataInterceptor@7c8326a4]
DEBUG s.a.a.u.c.CachedSupplier:85 - (SsoOidcTokenProvider()) Cached value is stale and will be refreshed.
...
DEBUG s.a.a.c.i.ExecutionInterceptorChain:85 - Creating an interceptor chain that will apply interceptors in the following order: [software.amazon.awssdk.core.internal.interceptor.HttpChecksumValidationInterceptor@51351f28, software.amazon.awssdk.awscore.interceptor.HelpfulUnknownHostExceptionInterceptor@21618fa7, software.amazon.awssdk.awscore.eventstream.EventStreamInitialRequestInterceptor@15f2eda3, software.amazon.awssdk.awscore.interceptor.TraceIdExecutionInterceptor@34cf294c, software.amazon.awssdk.services.sso.auth.scheme.internal.SsoAuthSchemeInterceptor@4d7aaca2, software.amazon.awssdk.services.sso.endpoints.internal.SsoResolveEndpointInterceptor@604b1e1d, software.amazon.awssdk.services.sso.endpoints.internal.SsoRequestSetEndpointInterceptor@62566842]
...
DEBUG s.a.a.request:85 - Sending Request: DefaultSdkHttpFullRequest(httpMethod=GET, protocol=https, host=portal.sso.us-east-1.amazonaws.com, encodedPath=/federation/credentials, headers=[amz-sdk-invocation-id, User-Agent, x-amz-sso_bearer_token], queryParameters=[role_name, account_id])
DEBUG s.a.a.c.i.h.p.s.SigningStage:85 - Using SelectedAuthScheme: smithy.api#noAuth
DEBUG s.a.a.h.a.i.c.SdkTlsSocketFactory:366 - Connecting socket to portal.sso.us-east-1.amazonaws.com/18.235.195.183:443 with timeout 2000
...
DEBUG s.a.a.requestId:85 - Received successful response: 200, Request ID: bb4f40f4-e920-4b5c-8648-58f26e7e08cd, Extended Request ID: not available
DEBUG s.a.a.request:85 - Received successful response: 200, Request ID: bb4f40f4-e920-4b5c-8648-58f26e7e08cd, Extended Request ID: not available
DEBUG s.a.a.u.c.CachedSupplier:85 - (software.amazon.awssdk.services.sso.auth.SsoCredentialsProvider@b965857) Successfully refreshed cached value. Next Prefetch Time: 2024-04-25T22:03:10.097Z. Next Stale Time: 2024-04-25T22:05:30Z
DEBUG s.a.a.c.i.ExecutionInterceptorChain:85 - Interceptor 'software.amazon.awssdk.services.s3.endpoints.internal.S3RequestSetEndpointInterceptor@7c2327fa' modified the message with its modifyHttpRequest method.
...
DEBUG s.a.a.c.i.h.p.s.SigningStage:85 - Using SelectedAuthScheme: aws.auth#sigv4
...
DEBUG s.a.a.a.s.Aws4Signer:85 - AWS4 Canonical Request: GET
...
DEBUG s.a.a.h.a.a.i.s.DefaultV4RequestSigner:85 - AWS4 String to sign: AWS4-HMAC-SHA256
20240425T210631Z
20240425/us-east-1/s3/aws4_request
aafb7784627fa7a49584256cb746279751c48c2076f813259ef767ecce304d64
DEBUG s.a.a.h.a.i.c.SdkTlsSocketFactory:366 - Connecting socket to s3.us-east-1.amazonaws.com/52.217.41.86:443 with timeout 2000
...
```
Die folgende `log4j2.xml` Datei konfiguriert die vorherige Ausgabe.
```
```
## Aktivieren Sie die Kabelprotokollierung
Es kann nützlich sein, die genauen Anfragen und Antworten zu sehen, die das SDK for Java 2.x sendet und empfängt. Wenn Sie Zugriff auf diese Informationen benötigen, können Sie sie vorübergehend aktivieren, indem Sie je nach dem vom Service-Client verwendeten HTTP-Client die erforderliche Konfiguration hinzufügen.
Standardmäßig verwenden synchrone Dienstclients, wie der [S3Client](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3Client.html), einen zugrunde liegenden Apache, und asynchrone Dienstclients HttpClient, wie der [S3 AsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3AsyncClient.html), verwenden einen nicht blockierenden Netty-HTTP-Client.
Im Folgenden finden Sie eine Aufschlüsselung der HTTP-Clients, die Sie für die beiden Kategorien von Service-Clients verwenden können:
| Synchrone HTTP-Clients | Asynchrone HTTP-Clients |
| --- | --- |
| [ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html) (Standard) | [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html) (Standard) |
| [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html) | [AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html) |
| [AwsCrtHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.html) | |
| [Apache 5 HttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache5/Apache5HttpClient.html) |
Auf der entsprechenden Registerkarte unten finden Sie die Konfigurationseinstellungen, die Sie je nach dem zugrunde liegenden HTTP-Client hinzufügen müssen.
**Warnung**
Wir empfehlen Ihnen, die Übertragungsprotokollierung ausschließlich für Debugging-Zwecke zu verwenden. Deaktivieren Sie sie in Produktionsumgebungen, da sie sensible Daten aufzeichnen kann. Sie protokolliert die gesamte Anfrage oder Antwort ohne Verschlüsselung, auch bei einem HTTPS-Aufruf. Bei umfangreichen Anfragen (z. B. zum Hochladen einer Datei Amazon S3) oder Antworten kann die ausführliche Kabelprotokollierung auch die Leistung Ihrer Anwendung erheblich beeinträchtigen.
------
#### [ ApacheHttpClient ]
Fügen Sie der `log4j2.xml` Konfigurationsdatei den Logger „org.apache.http.wire“ hinzu und setzen Sie den Level auf „DEBUG“.
Die folgende `log4j2.xml` Datei aktiviert das Full-Wire-Logging für den Apache. HttpClient
```
```
Für das Wire Logging mit Apache ist eine zusätzliche Maven-Abhängigkeit vom `log4j-1.2-api` Artefakt erforderlich, da 1.2 unter der Haube verwendet wird.
Der vollständige Satz der Maven-Abhängigkeiten für log4j 2, einschließlich der Drahtprotokollierung für den Apache HTTP-Client, ist in den folgenden Ausschnitten aus der Build-Datei dargestellt.
**Maven**
```
...
...
org.apache.logging.log4jlog4j-bomVERSIONpomimport
...
org.apache.logging.log4jlog4j-slf4j2-implorg.apache.logging.log4jlog4j-1.2-api
...
```
**Gradle-Kotlin DSL**
```
...
dependencies {
...
implementation(platform("org.apache.logging.log4j:log4j-bom:VERSION"))
implementation("org.apache.logging.log4j:log4j-slf4j2-impl")
implementation("org.apache.logging.log4j:log4j-1.2-api")
}
...
```
Wird `2.20.0` für die Mindestversion des Artefakts verwendet. `log4j-bom` Verwenden Sie für die neueste Version die in [Maven](https://central.sonatype.com/artifact/org.apache.logging.log4j/log4j-bom) Central veröffentlichte Version. Ersetzen Sie sie *VERSION* durch die Version, die Sie verwenden werden.
------
#### [ Apache5HttpClient ]
Fügen Sie den Logger „org.apache.hc.client5.http.wire“ zur Konfigurationsdatei hinzu und setzen Sie den `log4j2.xml` Level auf „DEBUG“.
Die folgende Datei aktiviert das Full-Wire-Logging für den Apache5. `log4j2.xml` HttpClient
```
```
------
#### [ UrlConnectionHttpClient ]
Um Details für Service-Clients zu protokollieren, die das verwenden`UrlConnectionHttpClient`, erstellen Sie zunächst eine `logging.properties` Datei mit dem folgenden Inhalt:
```
handlers=java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level=FINEST
sun.net.www.protocol.http.HttpURLConnection.level=ALL
```
Stellen Sie die folgende JVM-Systemeigenschaft mit dem vollständigen Pfad von ein: `logging.properties`
```
-Djava.util.logging.config.file=/full/path/to/logging.properties
```
Diese Konfiguration protokolliert nur die Header der Anfrage und Antwort, zum Beispiel:
```
FINE: sun.net.www.MessageHeader@35a9782c11 pairs: {GET /fileuploadtest HTTP/1.1: null}{amz-sdk-invocation-id: 5f7e707e-4ac5-bef5-ba62-00d71034ffdc}{amz-sdk-request: attempt=1; max=4}{Authorization: AWS4-HMAC-SHA256 Credential=/20220927/us-east-1/s3/aws4_request, SignedHeaders=amz-sdk-invocation-id;amz-sdk-request;host;x-amz-content-sha256;x-amz-date;x-amz-te, Signature=e367fa0bc217a6a65675bb743e1280cf12fbe8d566196a816d948fdf0b42ca1a}{User-Agent: aws-sdk-java/2.17.230 Mac_OS_X/12.5 OpenJDK_64-Bit_Server_VM/25.332-b08 Java/1.8.0_332 vendor/Amazon.com_Inc. io/sync http/UrlConnection cfg/retry-mode/legacy}{x-amz-content-sha256: UNSIGNED-PAYLOAD}{X-Amz-Date: 20220927T133955Z}{x-amz-te: append-md5}{Host: tkhill-test1.s3.amazonaws.com}{Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2}{Connection: keep-alive}
FINE: sun.net.www.MessageHeader@70a36a6611 pairs: {null: HTTP/1.1 200 OK}{x-amz-id-2: sAFeZDOKdUMsBbkdjyDZw7P0oocb4C9KbiuzfJ6TWKQsGXHM/dFuOvr2tUb7Y1wEHGdJ3DSIxq0=}{x-amz-request-id: P9QW9SMZ97FKZ9X7}{Date: Tue, 27 Sep 2022 13:39:57 GMT}{Last-Modified: Tue, 13 Sep 2022 14:38:12 GMT}{ETag: "2cbe5ad4a064cedec33b452bebf48032"}{x-amz-transfer-encoding: append-md5}{Accept-Ranges: bytes}{Content-Type: text/plain}{Server: AmazonS3}{Content-Length: 67}
```
Um die request/response Textkörper zu sehen, fügen Sie `-Djavax.net.debug=all` sie den JVM-Eigenschaften hinzu. Diese zusätzliche Eigenschaft protokolliert eine Vielzahl von Informationen, einschließlich aller SSL-Informationen.
Suchen Sie in der Protokollkonsole oder der Protokolldatei nach dem Abschnitt des Protokolls, der die tatsächlichen Anfragen und Antworten enthält, `"GET"` oder `"POST"` wechseln Sie schnell zu diesem Abschnitt. `"Plaintext before ENCRYPTION"`Suchen Sie nach Anfragen und `"Plaintext after DECRYPTION"` Antworten, um den vollständigen Text der Überschriften und Textteile zu sehen.
------
#### [ NettyNioAsyncHttpClient ]
Wenn Ihr asynchroner Service-Client den Standard verwendet`NettyNioAsyncHttpClient`, fügen Sie Ihrer `log4j2.xml` Datei zwei zusätzliche Logger hinzu, um HTTP-Header und Anforderungs-/Antworttexte zu protokollieren.
```
```
Hier ist ein vollständiges Beispiel: `log4j2.xml`
```
```
Diese Einstellungen protokollieren alle Header-Details und request/response Textkörper.
------
#### [ AwsCrtAsyncHttpClient/AwsCrtHttpClient ]
Wenn Sie Ihren Service-Client so konfiguriert haben, dass er eine Instanz eines AWS CRT-basierten HTTP-Clients verwendet, können Sie Details protokollieren, indem Sie die JVM-Systemeigenschaften festlegen oder programmgesteuert.
| |
| --- |
| Log to a file at "Debug" level |
| Mithilfe von Systemeigenschaften:
// Execute this statement before constructing the SDK service client. Log.initLoggingToStdout(Log.LogLevel.Trace);
|
Aus Sicherheitsgründen protokollieren die AWS CRT-basierten HTTP-Clients auf der „Trace“ -Ebene nur Antwortheader. Anforderungsheader, Anforderungstexte und Antworttexte werden nicht protokolliert.
------
# Konfiguration von Client-Endpunkten in der AWS SDK for Java 2.x
Das SDK for Java 2.x bietet mehrere Möglichkeiten, Dienstendpunkte zu konfigurieren. Ein Endpunkt ist die URL, die das SDK für API-Aufrufe verwendet. AWS-Services Standardmäßig bestimmt das SDK automatisch den geeigneten Endpunkt für jeden Dienst auf der Grundlage des von AWS-Region Ihnen konfigurierten. Es gibt jedoch Szenarien, in denen Sie diese Endpunkte möglicherweise anpassen oder überschreiben müssen:
+ Arbeiten mit lokalen Dienstimplementierungen oder Dienstimplementierungen von Drittanbietern (z. B. LocalStack
+ Verbindung AWS-Services über einen Proxy- oder VPC-Endpunkt herstellen
+ Testen mit Service-Endpunkten in der Beta- oder Vorabversion
## Optionen für die Konfiguration von Endpunkten
Das AWS SDK for Java 2.x bietet mehrere Möglichkeiten zur Konfiguration von Endpunkten:
+ Code-interne Konfiguration mithilfe des Service Client Builders
+ Externe Konfiguration mit Umgebungsvariablen
+ Externe Konfiguration mit JVM-Systemeigenschaften
+ Externe Konfiguration mit gemeinsam genutzter AWS Konfigurationsdatei
## Code-interne Endpunktkonfiguration
### Verwenden von `endpointOverride`
Der direkteste Weg, einen Endpunkt zu konfigurieren, ist die Verwendung der `endpointOverride` Methode im Service Client Builder. Diese Methode akzeptiert ein `URI` Objekt, das die benutzerdefinierte Endpunkt-URL darstellt.
**Example Einen benutzerdefinierten Endpunkt für einen Amazon S3 S3-Client einrichten**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import java.net.URI;
S3Client s3 = S3Client.builder()
.region(Region.US_WEST_2)
.endpointOverride(URI.create("https://my-custom-s3-endpoint.example.com"))
.build();
```
Bei der Verwendung `endpointOverride` müssen Sie immer noch eine Region für den Client angeben, auch wenn der Endpunkt explizit festgelegt ist. Die Region wird zum Signieren von Anfragen verwendet.
### Endpunkterkennung
Einige AWS-Services unterstützen die Endpunkterkennung, bei der das SDK automatisch den optimalen zu verwendenden Endpunkt ermitteln kann. Sie können diese Funktion mithilfe der `endpointDiscoveryEnabled` Methode im Service Client Builder aktivieren oder deaktivieren.
**Example Aktivieren der Endpunkterkennung für einen DynamoDB-Client**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
DynamoDbClient dynamoDb = DynamoDbClient.builder()
.region(Region.US_WEST_2)
.endpointDiscoveryEnabled(true)
.build();
```
## Endpunktkonfiguration auf Anforderungsebene
In einigen Fällen müssen Sie möglicherweise den Endpunkt für eine bestimmte Anfrage überschreiben, während Sie denselben Client für andere Anfragen mit dem Standardendpunkt verwenden. Der AWS SDK for Java 2.x unterstützt dies durch das Überschreiben von Anfragen.
**Example Den Endpunkt für eine bestimmte Anfrage überschreiben**
```
import software.amazon.awssdk.core.SdkRequest;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.GetObjectRequest;
import software.amazon.awssdk.http.SdkHttpRequest;
S3Client s3 = S3Client.builder()
.region(Region.US_WEST_2)
.build();
// Create a request
GetObjectRequest getObjectRequest = GetObjectRequest.builder()
.bucket("amzn-s3-demo-bucket")
.key("my-key")
.overrideConfiguration(c -> c.putHeader("Host", "custom-endpoint.example.com"))
.build();
// Execute the request with the custom endpoint
s3.getObject(getObjectRequest);
```
Beachten Sie, dass das Überschreiben von Endpunkten auf Anforderungsebene begrenzt ist und möglicherweise nicht für alle Dienste oder Szenarien funktioniert. In den meisten Fällen wird empfohlen, die Endpunktkonfiguration auf Client-Ebene zu verwenden.
## Konfiguration externer Endgeräte
### Verwenden von -Umgebungsvariablen
Sie können Endpunkte mithilfe von Umgebungsvariablen konfigurieren. Das SDK unterstützt die dienstspezifische Endpunktkonfiguration mithilfe von Umgebungsvariablen im Format`AWS_ENDPOINT_URL_[SERVICE]`, in dem die Service-ID in Großbuchstaben `[SERVICE]` steht.
**Example Einen S3-Endpunkt mithilfe von Umgebungsvariablen einrichten**
```
# For Linux/macOS
export AWS_ENDPOINT_URL_S3=https://my-custom-s3-endpoint.example.com
# For Windows
set AWS_ENDPOINT_URL_S3=https://my-custom-s3-endpoint.example.com
```
Sie können auch ein globales Endpunkt-URL-Präfix oder -Suffix mithilfe der folgenden Umgebungsvariablen festlegen:
+ `AWS_ENDPOINT_URL`- Legt einen globalen Endpunkt für alle Dienste fest
+ `AWS_ENDPOINT_URL_PREFIX`- Fügt allen Dienstendpunkten ein Präfix hinzu
+ `AWS_ENDPOINT_URL_SUFFIX`- Fügt allen Dienstendpunkten ein Suffix hinzu
### Verwendung von JVM-Systemeigenschaften
Sie können Endpoints auch mithilfe der JVM-Systemeigenschaften konfigurieren. Das Format ähnelt Umgebungsvariablen, verwendet jedoch eine andere Namenskonvention.
**Example Einen S3-Endpunkt mithilfe der JVM-Systemeigenschaften einrichten**
```
java -Daws.endpointUrl.s3=https://my-custom-s3-endpoint.example.com -jar your-application.jar
```
Die globale Endpunktkonfiguration ist auch über die Systemeigenschaften verfügbar:
+ `aws.endpointUrl`- Legt einen globalen Endpunkt für alle Dienste fest
+ `aws.endpointUrl.prefix`- Fügt allen Dienstendpunkten ein Präfix hinzu
+ `aws.endpointUrl.suffix`- Fügt allen Dienstendpunkten ein Suffix hinzu
### Verwenden Sie die gemeinsam genutzte Konfigurationsdatei AWS
Das unterstützt AWS SDK for Java 2.x auch die Endpunktkonfiguration über die gemeinsam genutzte AWS Konfigurationsdatei, die sich normalerweise unter `~/.aws/config` (Linux/macOS) oder `%USERPROFILE%\.aws\config` (Windows) befindet. Informationen und Beispiele finden Sie im Referenzhandbuch [AWS SDKs und im Tools-Referenzhandbuch](https://docs.aws.amazon.com/sdkref/latest/guide/feature-ss-endpoints.html#ss-endpoints-config).
## Vorrang bei der Konfiguration
Wenn mehrere Endpunktkonfigurationen vorhanden sind, folgt das SDK dieser Rangfolge (von der höchsten zur niedrigsten):
1. Überschreibungen auf Anforderungsebene (falls zutreffend)
1. Konfiguration auf Client-Ebene über `endpointOverride`
1. Umgebungsvariablen
1. JVM-Systemeigenschaften
1. Gemeinsam genutzte AWS Konfigurationsdatei
1. Standardendpunkte basierend auf den konfigurierten AWS-Region
## Dienstspezifische Endpunktkonfiguration
Einige AWS-Services bieten zusätzliche Optionen für die Endpunktkonfiguration, die für diesen Dienst spezifisch sind. Nachfolgend sind einige Beispiele aufgeführt:
### Amazon S3 S3-Endpunktkonfiguration
Amazon S3 unterstützt mehrere Endpunktkonfigurationen über die `S3Configuration` Klasse:
+ `dualstackEnabled`- Aktiviert die IPv6 Unterstützung
+ `accelerateModeEnabled`- Aktiviert die S3-Übertragungsbeschleunigung
+ `pathStyleAccessEnabled`- Verwendet den Zugriff im Pfadstil anstelle des Zugriffs im virtuell gehosteten Stil
+ `useArnRegionEnabled`- Verwendet die Region aus einem ARN für regionsübergreifende Anfragen
+ `fipsModeEnabled`- Leitet Anfragen an FIPS-konforme Endpunkte weiter
**Example Konfiguration von S3-spezifischen Endpunktoptionen**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.S3Configuration;
S3Client s3 = S3Client.builder()
.region(Region.US_WEST_2)
.serviceConfiguration(S3Configuration.builder()
.accelerateModeEnabled(true)
.dualstackEnabled(true)
.pathStyleAccessEnabled(false)
.fipsModeEnabled(true)
.build())
.build();
```
### DynamoDB-Endpunktkonfiguration
Für DynamoDB möchten Sie vielleicht Endpoint Discovery verwenden oder zu Testzwecken eine lokale Verbindung zu [DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html) herstellen:
**Example Lokale Verbindung zu DynamoDB herstellen**
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import java.net.URI;
DynamoDbClient dynamoDb = DynamoDbClient.builder()
.endpointOverride(URI.create("http://localhost:8000"))
// The region is meaningless for DynamoDB local but required for the client builder.
.region(Region.US_WEST_2)
.build();
```
DynamoDB unterstützt auch die Verwendung von [kontobasierten Endpunkten](https://docs.aws.amazon.com/sdkref/latest/guide/feature-account-endpoints.html), die Sie im Code oder mithilfe externer Einstellungen konfigurieren können. *Das folgende Beispiel zeigt, wie Sie die Verwendung von kontobasierten Endpunkten im Code deaktivieren können, wenn Sie den Client erstellen (die Standardeinstellungen werden bevorzugt):*
```
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.region(Region.US_EAST_1)
.accountIdEndpointMode(AccountIdEndpointMode.DISABLED)
.build();
```
## Bewährte Methoden
Beachten Sie bei der Konfiguration von Endpunkten im die folgenden AWS SDK for Java 2.x bewährten Methoden:
+ *Externe Konfiguration für umgebungsspezifische Endpunkte* verwenden — Verwenden Sie Umgebungsvariablen, Systemeigenschaften oder die AWS Konfigurationsdatei für Endpunkte, die sich je nach Umgebung unterscheiden (Entwicklung, Test, Produktion).
+ *Verwenden Sie die In-Code-Konfiguration für anwendungsspezifische Endpunkte* — Verwenden Sie die `endpointOverride` Methode des Client Builders für Endpunkte, die für das Design Ihrer Anwendung spezifisch sind.
+ *Immer eine Region angeben* — Geben Sie auch beim Überschreiben von Endpunkten immer eine Region an, die für das Signieren von Anfragen verwendet wird.
+ *Seien Sie vorsichtig mit globalen Endpunktüberschreibungen* — Die Verwendung globaler Endpunktüberschreibungen kann sich auf alle Dienste auswirken, was möglicherweise nicht Ihren Vorstellungen entspricht.
+ *Bedenken Sie die Auswirkungen auf die Sicherheit* — Achten Sie bei der Verwendung benutzerdefinierter Endgeräte darauf, dass diese über angemessene Sicherheitsmaßnahmen verfügen, insbesondere für Produktionsworkloads.
# Konfigurieren Sie HTTP-Clients in der AWS SDK for Java 2.x
Sie können den HTTP-Client ändern, der für Ihren Service-Client verwendet werden soll, sowie die Standardkonfiguration für HTTP-Clients mit dem ändern AWS SDK for Java 2.x. In diesem Abschnitt werden HTTP-Clients und Einstellungen für das SDK beschrieben.
## HTTP-Clients sind im SDK for Java verfügbar
### Synchrone Clients
Synchrone HTTP-Clients im SDK for Java implementieren die [SdkHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/SdkHttpClient.html)Schnittstelle. Ein synchroner Dienstclient, wie der `S3Client` oder der`DynamoDbClient`, erfordert die Verwendung eines synchronen HTTP-Clients. Der AWS SDK für Java bietet drei synchrone HTTP-Clients.
**ApacheHttpClient (Standard)**
[ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html)ist der Standard-HTTP-Client für synchrone Service-Clients. Hinweise zur Konfiguration von finden Sie `ApacheHttpClient` unter[Den Apache-basierten HTTP-Client konfigurieren](http-configuration-apache.md).
**AwsCrtHttpClient**
[AwsCrtHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.html)bietet hohen Durchsatz und blockierungsfreie I/O. Es basiert auf dem AWS Common Runtime (CRT) Http Client. Hinweise zur Konfiguration `AwsCrtHttpClient` und Verwendung mit Service-Clients finden Sie unter[AWS CRT-basierte HTTP-Clients konfigurieren](http-configuration-crt.md).
**UrlConnectionHttpClient**
Um die Anzahl der von Ihrer Anwendung verwendeten JAR-Dateien und Bibliotheken von Drittanbietern zu minimieren, können Sie die verwenden [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html). Hinweise zur Konfiguration von finden `UrlConnectionHttpClient` Sie unter[Den URLConnection basierten HTTP-Client konfigurieren](http-configuration-url.md).
**Apache 5 HttpClient**
[Apache5 HttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache5/Apache5HttpClient.html) *ist eine aktualisierte Version davon, die auf dem Apache `ApacheHttpClient` 5.x basiert. HttpClient Version 5.x* ist die Version, die aktiv von Apache betreut wird. Sie verbessert die vorherige Version, `ApacheHttpClient` indem sie die Kompatibilität mit dem modernen Java-Ökosystem bietet, einschließlich virtueller Thread-Unterstützung für Java 21 und verbesserter Logging-Flexibilität durch SLF4 J., der in einer future Version des AWS SDK for Java 2.x `ApacheHttpClient` als standardmäßigen synchronen Client ersetzt `Apache5HttpClient` wird. Sie verfügt über eine identische API und identische Funktionen, sodass sie sich ideal als Drop-In-Ersatz eignet. Informationen zur Konfiguration von finden Sie `Apache5HttpClient` unter[Konfigurieren Sie den Apache 5.x-basierten HTTP-Client](http-configuration-apache5.md).
### Asynchrone Clients
Asynchrone HTTP-Clients im SDK for Java implementieren die [SdkAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/async/SdkAsyncHttpClient.html)Schnittstelle. Ein asynchroner Dienstclient, wie der `S3AsyncClient` oder der`DynamoDbAsyncClient`, erfordert die Verwendung eines asynchronen HTTP-Clients. Der AWS SDK für Java bietet zwei asynchrone HTTP-Clients.
**NettyNioAsyncHttpClient (Standard)**
[NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)ist der Standard-HTTP-Client, der von asynchronen Clients verwendet wird. Hinweise zur Konfiguration von finden Sie `NettyNioAsyncHttpClient` unter[Den Netty-basierten HTTP-Client konfigurieren](http-configuration-netty.md).
**AwsCrtAsyncHttpClient**
Der [AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html)basiert auf dem AWS Common Runtime (CRT) -HTTP-Client. Hinweise zur Konfiguration von finden Sie `AwsCrtAsyncHttpClient` unter[AWS CRT-basierte HTTP-Clients konfigurieren](http-configuration-crt.md).
## Empfehlungen für HTTP-Clients
Bei der Auswahl einer HTTP-Client-Implementierung spielen mehrere Faktoren eine Rolle. Verwenden Sie die folgenden Informationen als Entscheidungshilfe.
### Flussdiagramm für Empfehlungen
Das folgende Flussdiagramm enthält allgemeine Hinweise, anhand derer Sie bestimmen können, welcher HTTP-Client verwendet werden soll.
![\[Flussdiagramm der HTTP-Client-Empfehlungen.\]](http://docs.aws.amazon.com/de_de/sdk-for-java/latest/developer-guide/images/JavaDevGuide-HTTPflowchart-DI.png)
### Vergleich von HTTP-Clients
Die folgende Tabelle enthält detaillierte Informationen für jeden HTTP-Client.
| HTTP-Client | Synchronisieren oder asynchron | Wann sollte dies verwendet werden? | Einschränkung/Nachteil |
| --- | --- | --- | --- |
| Apache-basierter HTTP-Client *(Standard-Synchronisierungs-HTTP-Client)* | Synchronisierung | Verwenden Sie ihn, wenn Sie eine niedrige Latenz einem hohen Durchsatz vorziehen | Langsamere Startzeit im Vergleich zu anderen HTTP-Clients |
| URLConnection-basierter HTTP-Client | Synchronisierung | Verwenden Sie es, wenn Sie unbedingt die Abhängigkeiten von Drittanbietern einschränken möchten | Unterstützt nicht die HTTP-PATCH-Methode, die für einige APIS wie Amazon APIGateway Update-Operationen erforderlich ist |
| AWS CRT-basierter Sync-HTTP-Client 1 | Synchronisierung | • Verwenden Sie es, wenn Ihre Anwendung in läuft AWS Lambda • Verwenden Sie es, wenn Sie einen hohen Durchsatz einer niedrigen Latenz vorziehen • Verwenden Sie es, wenn Sie SDK-Clients synchronisieren möchten | Die folgenden Java-Systemeigenschaften werden nicht unterstützt: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/sdk-for-java/latest/developer-guide/http-configuration.html) |
| Netty-basierter HTTP-Client *(standardmäßiger asynchroner HTTP-Client)* | Asynchron | • Verwenden Sie es, wenn Ihre Anwendung Aufrufe aufruft APIs , für die HTTP/2-Unterstützung erforderlich ist, z. B. die Kinesis-API [SubscribeToShard](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_SubscribeToShard.html) | Langsamere Startzeit im Vergleich zu anderen HTTP-Clients |
| AWS CRT-basierter asynchroner HTTP-Client 1 | Asynchron | • Verwenden Sie es, wenn Ihre Anwendung in läuft AWS Lambda• Verwenden Sie es, wenn Sie einen hohen Durchsatz einer niedrigen Latenz vorziehen• Verwenden Sie es, wenn Sie asynchrone SDK-Clients bevorzugen | • Unterstützt keine Service-Clients, die HTTP/2-Unterstützung benötigen, wie und `KinesisAsynClient` `TranscribeStreamingAsyncClient` Die folgenden Java-Systemeigenschaften werden nicht unterstützt: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/de_de/sdk-for-java/latest/developer-guide/http-configuration.html) |
1 Aufgrund ihrer zusätzlichen Vorteile empfehlen wir, wenn möglich die AWS CRT-basierten HTTP-Clients zu verwenden.
## Standardeinstellungen für die intelligente Konfiguration
Die AWS SDK for Java 2.x (Version 2.17.102 oder höher) bietet eine Funktion für intelligente Standardeinstellungen für Konfigurationen. Diese Funktion optimiert zwei HTTP-Client-Eigenschaften zusammen mit anderen Eigenschaften, die den HTTP-Client nicht beeinflussen.
Die Standardeinstellungen der intelligenten Konfiguration legen sinnvolle Werte für die `tlsNegotiationTimeoutInMillis` Eigenschaften `connectTimeoutInMillis` und fest, die auf einem von Ihnen angegebenen Standardmoduswert basieren. Sie wählen den Standardmoduswert auf der Grundlage der Eigenschaften Ihrer Anwendung.
Weitere Informationen zu den Standardeinstellungen für intelligente Konfigurationen und zur Auswahl des Standardmoduswerts, der für Ihre Anwendungen am besten geeignet ist, finden Sie im Referenzhandbuch [AWS SDKs und im Tools-Referenzhandbuch](https://docs.aws.amazon.com/sdkref/latest/guide/feature-smart-config-defaults.html).
Im Folgenden finden Sie vier Möglichkeiten, den Standardmodus für Ihre Anwendung festzulegen.
------
#### [ Service client ]
Verwenden Sie den Service Client Builder, um den Standardmodus direkt auf dem Service Client zu konfigurieren. Im folgenden Beispiel wird der Standardmodus `auto` für den auf festgelegt. `DynamoDbClient`
```
DynamoDbClient ddbClient = DynamoDbClient.builder()
.defaultsMode(DefaultsMode.AUTO)
.build();
```
------
#### [ System property ]
Sie können die `aws.defaultsMode` Systemeigenschaft verwenden, um den Standardmodus anzugeben. Wenn Sie die Systemeigenschaft in Java festlegen, müssen Sie die Eigenschaft festlegen, bevor Sie einen Service-Client initialisieren.
Das folgende Beispiel zeigt Ihnen, wie Sie den Standardmodus so einstellen, dass er eine in `auto` Java festgelegte Systemeigenschaft verwendet.
```
System.setProperty("aws.defaultsMode", "auto");
```
Das folgende Beispiel zeigt, wie Sie den Standardmodus `auto` mithilfe einer `-D` Option des Befehls auf „Standardmodus“ festlegen. `java`
```
java -Daws.defaultsMode=auto
```
------
#### [ Environment variable ]
Geben Sie einen Wert für die Umgebungsvariable ein`AWS_DEFAULTS_MODE`, um den Standardmodus für Ihre Anwendung auszuwählen.
Die folgenden Informationen zeigen den Befehl, der ausgeführt werden muss, um den Wert für den Standardmodus auf die `auto` Verwendung einer Umgebungsvariablen festzulegen.
| Betriebssystem | Befehl zum Setzen von Umgebungsvariablen |
| --- | --- |
| Linux, macOS oder Unix | export AWS\$1DEFAULTS\$1MODE=auto |
| Windows | set AWS\$1DEFAULTS\$1MODE=auto |
------
#### [ AWS config file ]
Sie können der gemeinsam genutzten AWS `config` Datei eine `defaults_mode` Konfigurationseigenschaft hinzufügen, wie das folgende Beispiel zeigt.
```
[default]
defaults_mode = auto
```
------
Wenn Sie den Standardmodus global mit der Systemeigenschaft, der Umgebungsvariablen oder der AWS Konfigurationsdatei festlegen, können Sie die Einstellungen beim Erstellen eines HTTP-Clients überschreiben.
Wenn Sie mit `httpClientBuilder()` dieser Methode einen HTTP-Client erstellen, gelten die Einstellungen nur für die Instanz, die Sie gerade erstellen. Ein Beispiel dafür wird [hier](http-configuration-netty.md#http-config-netty-one-client) gezeigt. Der Netty-basierte HTTP-Client in diesem Beispiel überschreibt alle global für und festgelegten Standardmoduswerte. `connectTimeoutInMillis` `tlsNegotiationTimeoutInMillis`
# Den Apache-basierten HTTP-Client konfigurieren
Synchrone Service-Clients AWS SDK for Java 2.x verwenden standardmäßig einen Apache-basierten HTTP-Client. [ApacheHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html) Die SDKs basieren auf dem `ApacheHttpClient` Apache. [HttpClient](https://hc.apache.org/httpcomponents-client-4.5.x/index.html)
Das SDK bietet auch das [UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html), das schneller geladen wird, aber weniger Funktionen hat. Hinweise zur Konfiguration von finden `UrlConnectionHttpClient` Sie unter[Den URLConnection basierten HTTP-Client konfigurieren](http-configuration-url.md).
Alle verfügbaren Konfigurationsoptionen für finden Sie unter [ApacheHttpClient.Builder und [ProxyConfiguration.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ProxyConfiguration.Builder.html)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.Builder.html). `ApacheHttpClient`
## Greifen Sie auf `ApacheHttpClient`
In den meisten Situationen verwenden Sie die `ApacheHttpClient` ohne explizite Konfiguration. Sie deklarieren Ihre Service-Clients und das SDK konfiguriert sie `ApacheHttpClient` mit Standardwerten für Sie.
Wenn Sie den explizit konfigurieren `ApacheHttpClient` oder ihn mit mehreren Service-Clients verwenden möchten, müssen Sie ihn für die Konfiguration verfügbar machen.
### Keine Konfiguration erforderlich
Wenn Sie in Maven eine Abhängigkeit von einem Service-Client deklarieren, fügt das SDK eine *Laufzeitabhängigkeit* von dem `apache-client` Artefakt hinzu. Dadurch steht die `ApacheHttpClient` Klasse Ihrem Code zur Laufzeit zur Verfügung, aber nicht zur Kompilierzeit. Wenn Sie den Apache-basierten HTTP-Client nicht konfigurieren, müssen Sie dafür keine Abhängigkeit angeben.
Im folgenden XML-Snippet einer `pom.xml` Maven-Datei wird durch die mit deklarierte Abhängigkeit `s3` automatisch der Apache-basierte HTTP-Client eingebunden. Sie müssen keine spezielle Abhängigkeit dafür deklarieren.
```
software.amazon.awssdkbom2.27.21pomimportsoftware.amazon.awssdks3
```
Mit diesen Abhängigkeiten können Sie keine expliziten Änderungen an der HTTP-Konfiguration vornehmen, da sich die `ApacheHttpClient` Bibliothek nur im Laufzeit-Klassenpfad befindet.
### Konfiguration erforderlich
*Um das zu konfigurieren`ApacheHttpClient`, müssen Sie bei der Kompilierung eine Abhängigkeit von der `apache-client` Bibliothek hinzufügen.*
Sehen Sie sich das folgende Beispiel für eine `pom.xml` Maven-Datei an, um die `ApacheHttpClient` zu konfigurieren.
```
software.amazon.awssdkbom2.27.21pomimportsoftware.amazon.awssdks3software.amazon.awssdkapache-client
```
## Verwenden und konfigurieren Sie den `ApacheHttpClient`
Sie können eine Instanz von `ApacheHttpClient` konfigurieren und gleichzeitig einen Service Client erstellen, oder Sie können eine einzelne Instanz so konfigurieren, dass sie von mehreren Service Clients gemeinsam genutzt wird.
Bei beiden Ansätzen verwenden Sie den, `[ApacheHttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.Builder.html)` um die Eigenschaften für den Apache-basierten HTTP-Client zu konfigurieren.
### Bewährtes Verfahren: Weisen Sie einem Service-Client eine `ApacheHttpClient` Instanz zu
Wenn Sie eine Instanz von konfigurieren müssen, empfehlen wir Ihnen`ApacheHttpClient`, die dedizierte `ApacheHttpClient` Instanz zu 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 `ApacheHttpClient` Instanz nicht geschlossen wird, wenn sie nicht mehr benötigt wird.
Im folgenden Beispiel wird eine `S3Client` eingebettete Instanz von `ApacheHttpClient` with `maxConnections` and `connectionTimeout` values erstellt und konfiguriert. Die HTTP-Instanz wird mit der `httpClientBuilder` Methode von `S3Client.Builder` erstellt.
**Importe**
```
import software.amazon.awssdk.http.apache.ApacheHttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```
**Code**
```
S3Client s3Client = S3Client // Singleton: Use the s3Client for all requests.
.builder()
.httpClientBuilder(ApacheHttpClient.builder()
.maxConnections(100)
.connectionTimeout(Duration.ofSeconds(5))
).build();
// Perform work with the s3Client.
s3Client.close(); // Requests completed: Close all service clients.
```
### Alternativer Ansatz: Eine `ApacheHttpClient` Instanz teilen
Um den Ressourcen- und Speicherverbrauch für Ihre Anwendung zu senken, können Sie eine konfigurieren `ApacheHttpClient` und sie von mehreren Service-Clients gemeinsam nutzen. Der HTTP-Verbindungspool wird gemeinsam genutzt, was die Ressourcennutzung senkt.
**Anmerkung**
Wenn eine `ApacheHttpClient` 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 ein Apache-basierter HTTP-Client konfiguriert, der von zwei Service-Clients verwendet wird. Die konfigurierte `ApacheHttpClient` Instanz wird an die `httpClient` Methode jedes Builders übergeben. Wenn die Service-Clients und der HTTP-Client nicht mehr benötigt werden, werden sie durch den Code explizit geschlossen. Der Code schließt den HTTP-Client zuletzt.
**Importe**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.apache.ApacheHttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
```
**Code**
```
SdkHttpClient apacheHttpClient = ApacheHttpClient.builder()
.maxConnections(100).build();
// Singletons: Use the s3Client and dynamoDbClient for all requests.
S3Client s3Client =
S3Client.builder()
.httpClient(apacheHttpClient).build();
DynamoDbClient dynamoDbClient =
DynamoDbClient.builder()
.httpClient(apacheHttpClient).build();
// Perform work with the s3Client and dynamoDbClient.
// Requests completed: Close all service clients.
s3Client.close();
dynamoDbClient.close();
apacheHttpClient.close(); // Explicitly close apacheHttpClient.
```
## Beispiel für eine Proxykonfiguration
Der folgende Codeausschnitt verwendet den [Proxykonfigurationsgenerator für den Apache HTTP-Client](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ProxyConfiguration.Builder.html).
```
SdkHttpClient apacheHttpClient = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.endpoint(URI.create("http://example.com:1234"))
.username("username")
.password("password")
.addNonProxyHost("localhost")
.addNonProxyHost("host.example.com")
.build())
.build();
```
Die entsprechenden Java-Systemeigenschaften für die Proxykonfiguration werden im folgenden Befehlszeilenausschnitt angezeigt.
```
$ java -Dhttp.proxyHost=example.com -Dhttp.proxyPort=1234 -Dhttp.proxyUser=username \
-Dhttp.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App
```
Das äquivalente Setup, das Umgebungsvariablen verwendet, ist:
```
// Set the following environment variables.
// $ export HTTP_PROXY="http://username:password@example.com:1234"
// $ export NO_PROXY="localhost|host.example.com"
// Set the 'useSystemPropertyValues' to false on the proxy configuration.
SdkHttpClient apacheHttpClient = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build();
// Run the application.
// $ java -cp ... App
```
**Anmerkung**
Der Apache HTTP-Client unterstützt derzeit keine HTTPS-Proxy-Systemeigenschaften oder die Umgebungsvariable HTTPS\$1PROXY.
# Den URLConnection basierten HTTP-Client konfigurieren
Der AWS SDK for Java 2.x bietet im Vergleich zum Standard einen leichteren `[UrlConnectionHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html)` HTTP-Client. `ApacheHttpClient` Der `UrlConnectionHttpClient` basiert auf dem von Java. `[URLConnection](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/net/URLConnection.html)`
Der `UrlConnectionHttpClient` wird schneller geladen als der Apache-basierte HTTP-Client, hat aber weniger Funktionen. Da er schneller geladen wird, ist er eine [gute Lösung](lambda-optimize-starttime.md) für Java-Funktionen. AWS Lambda
Das `UrlConnectionHttpClient` hat mehrere [konfigurierbare Optionen](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.Builder.html), auf die Sie zugreifen können.
**Anmerkung**
Der `UrlConnectionHttpClient` unterstützt die HTTP-PATCH-Methode nicht.
Für eine Handvoll AWS API-Operationen sind PATCH-Anfragen erforderlich. Diese Operationsnamen beginnen normalerweise mit`Update*`. Im Folgenden finden Sie einige Beispiele.
[Verschiedene `Update*` Operationen](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_Operations.html) in der AWS Security Hub CSPM API und auch die [BatchUpdateFindings](https://docs.aws.amazon.com/securityhub/1.0/APIReference/API_BatchUpdateFindings.html)Operation
Alle [`Update*`API-Operationen](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html) von Amazon API Gateway
Wenn Sie die verwenden könnten`UrlConnectionHttpClient`, lesen Sie zunächst in der API-Referenz nach AWS-Service , die Sie verwenden. Prüfen Sie, ob die Operationen, die Sie benötigen, den PATCH-Vorgang verwenden.
## Greifen Sie auf `UrlConnectionHttpClient`
Um das zu konfigurieren und zu verwenden`UrlConnectionHttpClient`, deklarieren Sie eine Abhängigkeit vom `url-connection-client` Maven-Artefakt in Ihrer `pom.xml` Datei.
Im Gegensatz zu `UrlConnectionHttpClient` wird das nicht automatisch zu Ihrem Projekt hinzugefügt, daher muss es von use ausdrücklich deklariert werden. `ApacheHttpClient`
Das folgende Beispiel einer `pom.xml` Datei zeigt die Abhängigkeiten, die für die Verwendung und Konfiguration des HTTP-Clients erforderlich sind.
```
software.amazon.awssdkbom2.27.21pomimportsoftware.amazon.awssdkurl-connection-client
```
## Verwenden und konfigurieren Sie `UrlConnectionHttpClient`
Sie können eine Instanz von `UrlConnectionHttpClient` konfigurieren und gleichzeitig einen Service Client erstellen, oder Sie können eine einzelne Instanz so konfigurieren, dass sie von mehreren Service Clients gemeinsam genutzt wird.
Bei beiden Ansätzen verwenden Sie den [UrlConnectionHttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.Builder.html), um die Eigenschaften für den URLConnection basierten HTTP-Client zu konfigurieren.
### Bewährtes Verfahren: Dedizieren Sie eine `UrlConnectionHttpClient` Instanz einem Service-Client
Wenn Sie eine Instanz von konfigurieren müssen, empfehlen wir Ihnen`UrlConnectionHttpClient`, die dedizierte `UrlConnectionHttpClient` Instanz zu 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 `UrlConnectionHttpClient` Instanz nicht geschlossen wird, wenn sie nicht mehr benötigt wird.
Im folgenden Beispiel wird eine `S3Client` eingebettete Instanz von `UrlConnectionHttpClient` with `socketTimeout` and `proxyConfiguration` values erstellt und konfiguriert. Die `proxyConfiguration` Methode verwendet einen Java-Lambda-Ausdruck vom Typ. ` Consumer<[ProxyConfiguration.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/ProxyConfiguration.Builder.html)>`
**Importe**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
import java.net.URI;
import java.time.Duration;
```
**Code**
```
// Singleton: Use the s3Client for all requests.
S3Client s3Client =
S3Client.builder()
.httpClientBuilder(UrlConnectionHttpClient.builder()
.socketTimeout(Duration.ofMinutes(5))
.proxyConfiguration(proxy -> proxy.endpoint(URI.create("http://proxy.mydomain.net:8888"))))
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.build();
// Perform work with the s3Client.
s3Client.close(); // Requests completed: Close the s3client.
```
### Alternativer Ansatz: Eine `UrlConnectionHttpClient` Instanz teilen
Um den Ressourcen- und Speicherverbrauch für Ihre Anwendung zu senken, können Sie eine konfigurieren `UrlConnectionHttpClient` und sie von mehreren Service-Clients gemeinsam nutzen. Der HTTP-Verbindungspool wird gemeinsam genutzt, was die Ressourcennutzung senkt.
**Anmerkung**
Wenn eine `UrlConnectionHttpClient` 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 ein URLConnection basierter HTTP-Client konfiguriert, der von zwei Dienstclients verwendet wird. Die konfigurierte `UrlConnectionHttpClient` Instanz wird an die `httpClient` Methode jedes Builders übergeben. Wenn die Service-Clients und der HTTP-Client nicht mehr benötigt werden, werden sie durch den Code explizit geschlossen. Der Code schließt den HTTP-Client zuletzt.
**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.urlconnection.ProxyConfiguration;
import software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.net.URI;
import java.time.Duration;
```
**Code**
```
SdkHttpClient urlHttpClient = UrlConnectionHttpClient.create();
// Singletons: Use the s3Client and dynamoDbClient for all requests.
S3Client s3Client =
S3Client.builder()
.httpClient(urlHttpClient)
.defaultsMode(DefaultsMode.IN_REGION)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.build();
DynamoDbClient dynamoDbClient =
DynamoDbClient.builder()
.httpClient(urlHttpClient)
.defaultsMode(DefaultsMode.IN_REGION)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.build();
// Perform work with the s3Client and dynamoDbClient.
// Requests completed: Close all service clients.
s3Client.close();
dynamoDbClient.close();
urlHttpClient.close();
```
#### Verwenden Sie `URLConnectionHttpClient` und `ApacheHttpClient` zusammen
Wenn Sie das `UrlConnectionHttpClient` in Ihrer Anwendung verwenden, müssen Sie jedem Service-Client entweder eine `URLConnectionHttpClient` Instanz oder eine `ApacheHttpClient` Instanz mithilfe der `httpClientBuilder` Methode des Service Client Builders zur Verfügung stellen.
Eine Ausnahme tritt auf, wenn Ihr Programm mehrere Service-Clients verwendet und beide der folgenden Bedingungen zutreffen:
+ Ein Dienstclient ist für die Verwendung einer `UrlConnectionHttpClient` Instanz konfiguriert
+ Ein anderer Dienstclient verwendet den Standard, `ApacheHttpClient` ohne ihn explizit mit den `httpClientBuilder()` Methoden `httpClient()` oder zu erstellen
Die Ausnahme besagt, dass im Klassenpfad mehrere HTTP-Implementierungen gefunden wurden.
Der folgende Beispielcodeausschnitt führt zu einer Ausnahme.
```
// The dynamoDbClient uses the UrlConnectionHttpClient
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.httpClient(UrlConnectionHttpClient.create())
.build();
// The s3Client below uses the ApacheHttpClient at runtime, without specifying it.
// An SdkClientException is thrown with the message that multiple HTTP implementations were found on the classpath.
S3Client s3Client = S3Client.create();
// Perform work with the s3Client and dynamoDbClient.
dynamoDbClient.close();
s3Client.close();
```
Vermeiden Sie die Ausnahme, indem Sie das explizit `S3Client` mit einem konfigurieren. `ApacheHttpClient`
```
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.httpClient(UrlConnectionHttpClient.create())
.build();
S3Client s3Client = S3Client.builder()
.httpClient(ApacheHttpClient.create()) // Explicitly build the ApacheHttpClient.
.build();
// Perform work with the s3Client and dynamoDbClient.
dynamoDbClient.close();
s3Client.close();
```
**Anmerkung**
Um das explizit zu erstellen`ApacheHttpClient`, müssen Sie Ihrer Maven-Projektdatei [eine Abhängigkeit vom `apache-client` Artefakt hinzufügen](http-configuration-apache.md#http-apache-dependency).
## Beispiel für eine Proxy-Konfiguration
Der folgende Codeausschnitt verwendet den [Proxykonfigurationsgenerator für den URL-Verbindungs-HTTP-Client](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/ProxyConfiguration.Builder.html).
```
SdkHttpClient urlHttpClient = UrlConnectionHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.endpoint(URI.create("http://example.com:1234"))
.username("username")
.password("password")
.addNonProxyHost("localhost")
.addNonProxyHost("host.example.com")
.build())
.build();
```
Die entsprechenden Java-Systemeigenschaften für die Proxykonfiguration werden im folgenden Befehlszeilenausschnitt angezeigt.
```
$ java -Dhttp.proxyHost=example.com -Dhttp.proxyPort=1234 -Dhttp.proxyUser=username \
-Dhttp.proxyPassword=password -Dhttp.nonProxyHosts=localhost|host.example.com -cp ... App
```
Das äquivalente Setup, das Umgebungsvariablen verwendet, ist:
```
// Set the following environment variables.
// $ export HTTP_PROXY="http://username:password@example.com:1234"
// $ export NO_PROXY="localhost|host.example.com"
// Set the 'useSystemPropertyValues' to false on the proxy configuration.
SdkHttpClient apacheHttpClient = UrlConnectionHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build();
// Run the application.
// $ java -cp ... App
```
**Anmerkung**
Der URLConnection basierte HTTP-Client unterstützt derzeit weder die HTTPS-Proxy-Systemeigenschaften noch die Umgebungsvariable HTTPS\$1PROXY.
# Den Netty-basierten HTTP-Client konfigurieren
Der Standard-HTTP-Client für asynchrone Operationen in der AWS SDK for Java 2.x ist der [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)Netty-basierte. [Der Netty-basierte Client basiert auf dem asynchronen, ereignisgesteuerten Netzwerk-Framework des Netty-Projekts.](https://netty.io/)
[Als alternativen HTTP-Client können Sie den neuen CRT-basierten HTTP-Client verwenden.AWS](http-configuration-crt.md) In diesem Thema erfahren Sie, wie Sie den konfigurieren. `NettyNioAsyncHttpClient`
## Greifen Sie auf `NettyNioAsyncHttpClient`
In den meisten Situationen verwenden Sie die `NettyNioAsyncHttpClient` ohne explizite Konfiguration in asynchronen Programmen. Sie deklarieren Ihre asynchronen Service-Clients und das SDK konfiguriert sie `NettyNioAsyncHttpClient` mit Standardwerten für Sie.
Wenn Sie den explizit konfigurieren `NettyNioAsyncHttpClient` oder ihn mit mehreren Service-Clients verwenden möchten, müssen Sie ihn für die Konfiguration verfügbar machen.
### Keine Konfiguration erforderlich
Wenn Sie in Maven eine Abhängigkeit von einem Service-Client deklarieren, fügt das SDK eine *Laufzeitabhängigkeit* von dem `netty-nio-client` Artefakt hinzu. Dadurch steht die `NettyNioAsyncHttpClient` Klasse Ihrem Code zur Laufzeit zur Verfügung, aber nicht zur Kompilierzeit. Wenn Sie den Netty-basierten HTTP-Client nicht konfigurieren, müssen Sie dafür keine Abhängigkeit angeben.
Im folgenden XML-Snippet einer `pom.xml` Maven-Datei bezieht die mit `dynamodb-enhanced` transitiv deklarierte Abhängigkeit den Netty-basierten HTTP-Client mit ein. Sie müssen keine spezielle Abhängigkeit dafür deklarieren.
```
software.amazon.awssdkbom2.27.21pomimportsoftware.amazon.awssdkdynamodb-enhanced
```
Mit diesen Abhängigkeiten können Sie keine Änderungen an der HTTP-Konfiguration vornehmen, da sich die `NettyNioAsyncHttpClient` Bibliothek nur im Laufzeit-Klassenpfad befindet.
### Konfiguration erforderlich
*Um das zu konfigurieren`NettyNioAsyncHttpClient`, müssen Sie bei der Kompilierung eine Abhängigkeit vom `netty-nio-client` Artefakt hinzufügen.*
Sehen Sie sich das folgende Beispiel für eine `pom.xml` Maven-Datei an, um die zu konfigurieren. `NettyNioAsyncHttpClient`
```
software.amazon.awssdkbom2.27.21pomimportsoftware.amazon.awssdkdynamodb-enhancedsoftware.amazon.awssdknetty-nio-client
```
## Verwenden und konfigurieren Sie den `NettyNioAsyncHttpClient`
Sie können eine Instanz von `NettyNioAsyncHttpClient` konfigurieren und gleichzeitig einen Service Client erstellen, oder Sie können eine einzelne Instanz so konfigurieren, dass sie von mehreren Service Clients gemeinsam genutzt wird.
Bei beiden Ansätzen verwenden Sie den [NettyNioAsyncHttpClient.Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.Builder.html), um die Eigenschaften für die Netty-basierte HTTP-Client-Instanz zu konfigurieren.
### Bewährtes Verfahren: Dedizieren Sie eine `NettyNioAsyncHttpClient` Instanz einem Service-Client
Wenn Sie eine Instanz von konfigurieren müssen, empfehlen wir Ihnen`NettyNioAsyncHttpClient`, eine dedizierte `NettyNioAsyncHttpClient` Instanz zu 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 `NettyNioAsyncHttpClient` Instanz nicht geschlossen wird, wenn sie nicht mehr benötigt wird.
Im folgenden Beispiel wird eine `DynamoDbAsyncClient` Instanz erstellt, die von einer `DynamoDbEnhancedAsyncClient` Instanz verwendet wird. Die `DynamoDbAsyncClient` Instanz enthält die `NettyNioAsyncHttpClient` Instanz mit den `maxConcurrency` Werten `connectionTimeout` und. Die HTTP-Instanz wird mit der `httpClientBuilder` Methode von erstellt`DynamoDbAsyncClient.Builder`.
**Importe**
```
import software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider;
import software.amazon.awssdk.awscore.defaultsmode.DefaultsMode;
import software.amazon.awssdk.enhanced.dynamodb.DynamoDbEnhancedAsyncClient;
import software.amazon.awssdk.enhanced.dynamodb.extensions.AutoGeneratedTimestampRecordExtension;
import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
import java.time.Duration;
```
**Code**
```
// DynamoDbAsyncClient is the lower-level client used by the enhanced client.
DynamoDbAsyncClient dynamoDbAsyncClient =
DynamoDbAsyncClient
.builder()
.httpClientBuilder(NettyNioAsyncHttpClient.builder()
.connectionTimeout(Duration.ofMillis(5_000))
.maxConcurrency(100)
.tlsNegotiationTimeout(Duration.ofMillis(3_500)))
.defaultsMode(DefaultsMode.IN_REGION)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.build();
// Singleton: Use dynamoDbAsyncClient and enhancedClient for all requests.
DynamoDbEnhancedAsyncClient enhancedClient =
DynamoDbEnhancedAsyncClient
.builder()
.dynamoDbClient(dynamoDbAsyncClient)
.extensions(AutoGeneratedTimestampRecordExtension.create())
.build();
// Perform work with the dynamoDbAsyncClient and enhancedClient.
// Requests completed: Close dynamoDbAsyncClient.
dynamoDbAsyncClient.close();
```
### Alternativer Ansatz: Eine `NettyNioAsyncHttpClient` Instanz teilen
Um den Ressourcen- und Speicherverbrauch für Ihre Anwendung zu senken, können Sie eine konfigurieren `NettyNioAsyncHttpClient` und sie von mehreren Service-Clients gemeinsam nutzen. Der HTTP-Verbindungspool wird gemeinsam genutzt, was die Ressourcennutzung senkt.
**Anmerkung**
Wenn eine `NettyNioAsyncHttpClient` 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 ein Netty-basierter HTTP-Client konfiguriert, der von zwei Dienstclients verwendet wird. Die konfigurierte `NettyNioAsyncHttpClient` Instanz wird an die `httpClient` Methode jedes Builders übergeben. Wenn die Service-Clients und der HTTP-Client nicht mehr benötigt werden, werden sie durch den Code explizit geschlossen. Der Code schließt den HTTP-Client zuletzt.
**Importe**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.apache.ApacheHttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
```
**Code**
```
// Create a NettyNioAsyncHttpClient shared instance.
SdkAsyncHttpClient nettyHttpClient = NettyNioAsyncHttpClient.builder().maxConcurrency(100).build();
// Singletons: Use the s3AsyncClient, dbAsyncClient, and enhancedAsyncClient for all requests.
S3AsyncClient s3AsyncClient =
S3AsyncClient.builder()
.httpClient(nettyHttpClient)
.build();
DynamoDbAsyncClient dbAsyncClient =
DynamoDbAsyncClient.builder()
.httpClient(nettyHttpClient)
.defaultsMode(DefaultsMode.IN_REGION)
.credentialsProvider(EnvironmentVariableCredentialsProvider.create())
.build();
DynamoDbEnhancedAsyncClient enhancedAsyncClient =
DynamoDbEnhancedAsyncClient.builder()
.dynamoDbClient(dbAsyncClient)
.extensions(AutoGeneratedTimestampRecordExtension.create())
.build();
// Perform work with s3AsyncClient, dbAsyncClient, and enhancedAsyncClient.
// Requests completed: Close all service clients.
s3AsyncClient.close();
dbAsyncClient.close()
nettyHttpClient.close(); // Explicitly close nettyHttpClient.
```
## Konfigurieren Sie die ALPN-Protokollaushandlung
ALPN (Application-Layer Protocol Negotiation) ist eine TLS-Erweiterung, mit der die Anwendungsebene aushandeln kann, welches Protokoll über eine sichere Verbindung ausgeführt werden soll, sodass zusätzliche Roundtrips vermieden werden und eine bessere Leistung erzielt wird.
Um dem Netty-basierten HTTP-Client die Verwendung von ALPN zu ermöglichen, rufen Sie die Builder-Methoden auf, wie im folgenden Codeausschnitt gezeigt:
```
import software.amazon.awssdk.http.Protocol;
import software.amazon.awssdk.http.ProtocolNegotiation;
import software.amazon.awssdk.http.async.SdkAsyncHttpClient;
import software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient;
import software.amazon.awssdk.services.transcribestreaming.TranscribeStreamingAsyncClient;
// Configure the Netty-based HTTP client to use the ALPN protocol.
SdkAsyncHttpClient nettyClient = NettyNioAsyncHttpClient.builder()
.protocol(Protocol.HTTP2)
.protocolNegotiation(ProtocolNegotiation.ALPN)
.build();
// Use the Netty-based HTTP client with a service client.
TranscribeStreamingAsyncClient transcribeClient = TranscribeStreamingAsyncClient.builder()
.httpClient(nettyClient)
.build();
```
Die ALPN-Protokollaushandlung funktioniert derzeit nur mit dem HTTP/2-Protokoll, wie im vorherigen Codeausschnitt gezeigt.
## Beispiel für eine Proxykonfiguration
Der folgende Codeausschnitt verwendet den [Proxykonfigurationsgenerator für den Netty](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/ProxyConfiguration.Builder.html) HTTP-Client.
```
SdkAsyncHttpClient nettyHttpClient = NettyNioAsyncHttpClient.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 nettyHttpClient = NettyNioAsyncHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build();
// Run the application.
// $ java -cp ... App
```
# AWS CRT-basierte HTTP-Clients konfigurieren
Zu den AWS CRT-basierten HTTP-Clients gehören synchrone und asynchrone [AwsCrtHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.html)Clients. [AwsCrtAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.html) Die AWS CRT-basierten HTTP-Clients bieten die folgenden Vorteile für HTTP-Clients:
+ Schnellere SDK-Startup-Zeiten
+ Geringeren Speicherbedarf
+ Reduzierte Latenzzeit
+ Verbindungsgesundheitsverwaltung
+ DNS-Load Balancing
**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](crt-based-s3-client.md)** ist eine Implementierung der [AsyncClientS3-Schnittstelle](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3AsyncClient.html) 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](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html) verwenden, verwenden die AWS CRT-basierten HTTP-Clients die [aws-c-s3-Bibliothek](https://github.com/awslabs/aws-c-s3) nicht und unterstützen auch nicht die API-Funktionen für [mehrteilige Uploads von S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html). 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.
Verwenden Sie eine der folgenden Optionen, um Ihre Maven-Datei einzurichten. `pom.xml`
**Anmerkung**
Sie können die *plattformspezifische JAR-Option* verwenden, wenn Sie die Größe der Laufzeitabhängigkeiten verringern müssen, z. B. wenn Ihre Anwendung in einer Funktion ausgeführt wird. AWS Lambda
------
#### [ Uber-jar option ]
Standardmäßig `aws-crt-client` verwendet der ein Uber-Jar mit AWS CRT-Artefakten, das Binärdateien für verschiedene Plattformen enthält, darunter Linux, Windows und macOS.
```
2.29.10*software.amazon.awssdkbom${aws.sdk.version}pomimportsoftware.amazon.awssdkaws-crt-client
```
\$1Ersetzen Sie die rot dargestellte Version durch die Version des Java-SDK, die Sie verwenden möchten. Finden Sie die neuesten Informationen auf [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).
------
#### [ Platform-specific jar option ]
*Um die Java-Laufzeit auf eine plattformspezifische Version der AWS CRT-Bibliothek zu beschränken, nehmen Sie die folgenden Änderungen an der Uber-JAR-Option vor.*
+ Fügen Sie dem Artefakt `exclusions` des SDK ein Element hinzu. `aws-crt-client` Dieser Ausschluss verhindert, dass das SDK das AWS CRT-Uber-JAR transitiv verwendet.
+ Fügen Sie ein Abhängigkeitselement für die spezifische AWS CRT-Plattformversion hinzu, die Sie benötigen. In den **folgenden Schritten zur Bestimmung der AWS CRT-Artefaktversion** erfahren Sie, wie Sie die richtige Version ermitteln können.
```
2.29.101software.amazon.awssdkbom${aws.sdk.java.version}pomimportsoftware.amazon.awssdkaws-crt-clientsoftware.amazon.awssdk.crtaws-crtsoftware.amazon.awssdk.crtaws-crt0.31.32linux-x86_643
```
1 Ersetzen Sie die rot dargestellte Version durch die Version des Java-SDK, die Sie verwenden möchten. Finden Sie die neuesten Informationen auf [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).
2 Ersetzen Sie die Version`software.amazon.awssdk.crt:aws-crt`, die durch die *Uber-JAR-Option* bereitgestellt würde. Sehen Sie sich die folgenden **Schritte an, um die Version des AWS CRT-Artefakts zu ermitteln**.
3 Ersetzen Sie den `classifier` Wert durch einen Wert für Ihre Plattform. Eine [Liste der verfügbaren Werte finden Sie auf der GitHub ](https://github.com/awslabs/aws-crt-java?tab=readme-ov-file#platform-specific-jars) Seite AWS CRT for Java.
**Schritte zur Bestimmung der Version des AWS CRT-Artefakts**
Verwenden Sie die folgenden Schritte, um die AWS CRT-Artefaktversion zu ermitteln, die mit der Version des SDK for Java kompatibel ist, die Sie verwenden.
1. Richten Sie Ihre `pom.xml` Datei wie in der *Uber-JAR-Option* gezeigt ein. Mit diesem Setup können Sie sehen, welche Version `software.amazon.awssdk.crt:aws-crt` des SDK standardmäßig enthalten ist.
1. Führen Sie im Stammverzeichnis des Projekts (im selben Verzeichnis wie die `pom.xml` Datei) den folgenden Maven-Befehl aus:
```
mvn dependency:tree -Dincludes=software.amazon.awssdk.crt:aws-crt
```
Maven führt möglicherweise andere Aktionen aus, aber am Ende sollten Sie die Konsolenausgabe der `software.amazon.awssdk.crt:aws-crt` Abhängigkeit sehen, die das SDK transitiv verwendet. Der folgende Ausschnitt zeigt eine Beispielausgabe, die auf einer SDK-Version von basiert: `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
```
1. Verwenden Sie die Version, die auf der Konsole für das `software.amazon.awssdk.crt:aws-crt` Artefakt angezeigt wird. In diesem Fall fügen Sie es `0.31.3` zu Ihrer `pom.xml` Datei hinzu.
------
## 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](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtHttpClient.Builder.html).
### 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: Eine Instanz teilen
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 ist`S3AsyncClient`, 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.
```
VERSIONsoftware.amazon.awssdks3${aws.sdk.version}software.amazon.awssdknetty-nio-clientsoftware.amazon.awssdkapache-clientsoftware.amazon.awssdkaws-crt-client
```
Den neuesten Wert finden Sie im zentralen Maven-Repository. [https://central.sonatype.com/artifact/software.amazon.awssdk/bom](https://central.sonatype.com/artifact/software.amazon.awssdk/bom)
**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](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/AwsCrtAsyncHttpClient.Builder.html) für überprüfen. `AwsCrtAsyncHttpClient` Sie können dieselben Optionen für den konfigurieren`AwsCrtHttpClient`.
### 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 [KinesisAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/kinesis/KinesisAsyncClient.html)oder der, sollten Sie in Erwägung ziehen [TranscribeStreamingAsyncClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/transcribestreaming/TranscribeStreamingAsyncClient.html), stattdessen den zu verwenden. [NettyNioAsyncHttpClient](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/nio/netty/NettyNioAsyncHttpClient.html)
## Beispiel für eine Proxykonfiguration
Der folgende Codeausschnitt zeigt die Verwendung der Einstellung [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/ProxyConfiguration.Builder.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/crt/ProxyConfiguration.Builder.html), 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
```
# HTTP-Proxys konfigurieren
Sie können HTTP-Proxys konfigurieren, indem Sie Code verwenden, Java-Systemeigenschaften festlegen oder Umgebungsvariablen festlegen.
## Im Code konfigurieren
Sie konfigurieren Proxys im Code mit einem kundenspezifischen `ProxyConfiguration` Builder, wenn Sie den Service-Client erstellen. Der folgende Code zeigt ein Beispiel für eine Proxykonfiguration für einen Apache-basierten HTTP-Client, der von einem Amazon S3-Serviceclient verwendet wird.
```
SdkHttpClient httpClient1 = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.endpoint(URI.create("http://proxy.example.com"))
.username("username")
.password("password")
.addNonProxyHost("localhost")
.build())
.build();
S3Client s3Client = S3Client.builder()
.httpClient(httpClient)
.build();
```
Der Abschnitt für jeden HTTP-Client in diesem Thema zeigt ein Beispiel für eine Proxykonfiguration.
+ [Apache HTTP-Client](http-configuration-apache.md#http-configuration-apache-proxy-conf-ex)
+ [URLConnectionbasierter HTTP-Client](http-configuration-url.md#http-configuration-url-proxy-conf-ex)
+ [Netty-basierter HTTP-Client](http-configuration-netty.md#http-config-netty-proxy-ex)
+ [AWS CRT-basierter HTTP-Client](http-configuration-crt.md#http-config-crt-proxy-ex)
## Konfigurieren Sie HTTP-Proxys mit externen Einstellungen
Auch wenn Sie nicht explizit einen `ProxyConfiguration` Builder im Code verwenden, sucht das SDK nach externen Einstellungen, um eine Standard-Proxykonfiguration zu konfigurieren.
Standardmäßig sucht das SDK zuerst nach JVM-Systemeigenschaften. Wenn auch nur eine Eigenschaft gefunden wird, verwendet das SDK den Wert und alle anderen Systemeigenschaftswerte. Wenn keine Systemeigenschaften verfügbar sind, sucht das SDK nach Proxy-Umgebungsvariablen.
Das SDK kann die folgenden Java-Systemeigenschaften und Umgebungsvariablen verwenden.
**Java-Systemeigenschaften**
| Systemeigenschaft | Description | Unterstützung für HTTP-Clients |
| --- | --- | --- |
| http.ProxyHost | Hostname des HTTP-Proxyservers | Alle |
| http.ProxyPort | Portnummer des HTTP-Proxyservers | Alle |
| http.ProxyUser | Benutzername für die HTTP-Proxyauthentifizierung | Alle |
| http.ProxyPassword | Passwort für die HTTP-Proxyauthentifizierung | Alle |
| http. nonProxyHosts | Liste der Hosts, die unter Umgehung des Proxys direkt erreicht werden sollen. [Diese Liste ist auch gültig, wenn HTTPS verwendet wird](https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html). | Alle |
| https.proxyHost | Hostname des HTTPS-Proxyservers | Netty, CRT |
| HTTPS.Proxy-Port | Portnummer des HTTPS-Proxyservers | Netty, CRT |
| https.proxyBenutzer | Benutzername für die HTTPS-Proxyauthentifizierung | Netty, CRT |
| https.proxyPasswort | Passwort für die HTTPS-Proxyauthentifizierung | Netty, CRT |
**Umgebungsvariablen**
| Umgebungsvariable | Description | HTTP-Client-Unterstützung |
| --- | --- | --- |
| HTTP\$1PROXY 1 | Eine gültige URL mit dem Schema HTTP | Alle |
| HTTPS\$1PROXY 1 | Eine gültige URL mit dem Schema HTTPS | Netty, CRT |
| KEIN PROXY 2 | Liste der Hosts, die unter Umgehung des Proxys direkt erreicht werden sollen. Die Liste gilt sowohl für HTTP als auch für HTTPS. | Alle |
### Schlüssel und Fußnoten anzeigen
**Alle** — Alle vom SDK angebotenen HTTP-Clients—`UrlConnectionHttpClient`,, `ApacheHttpClient``NettyNioAsyncHttpClient`,`AwsCrtAsyncHttpClient`.
**Netty** — Der Netty-basierte HTTP-Client (). `NettyNioAsyncHttpClient`
**CRT** — Die AWS CRT-basierten HTTP-Clients (und). `AwsCrtHttpClient` `AwsCrtAsyncHttpClient`
1 Die abgefragte Umgebungsvariable, ob `HTTP_PROXY` oder`HTTPS_PROXY`, hängt von der Schemaeinstellung im Client ab. `ProxyConfiguration` Das Standardschema ist HTTP. Der folgende Ausschnitt zeigt, wie Sie das Schema auf HTTPS ändern, das für die Auflösung von Umgebungsvariablen verwendet wird.
```
SdkHttpClient httpClient = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.scheme("https")
.build())
.build();
```
2 Die `NO_PROXY` Umgebungsvariable unterstützt eine Mischung aus „\$1“ und „,“ -Trennzeichen zwischen Hostnamen. Hostnamen können den Platzhalter „\$1“ enthalten.
## Verwenden Sie eine Kombination von Einstellungen
Sie können eine Kombination von HTTP-Proxyeinstellungen in Code, Systemeigenschaften und Umgebungsvariablen verwenden.
**Example — Konfiguration, die durch eine Systemeigenschaft und durch Code bereitgestellt wird**
```
// Command line with the proxy password set as a system property.
$ java -Dhttp.proxyPassword=SYS_PROP_password -cp ... App
// Since the 'useSystemPropertyValues' setting is 'true' (the default), the SDK will supplement
// the proxy configuration in code with the 'http.proxyPassword' value from the system property.
SdkHttpClient apacheHttpClient = ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.endpoint(URI.create("http://localhost:1234"))
.username("username")
.build())
.build();
// Use the apache HTTP client with proxy configuration.
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.httpClient(apacheHttpClient)
.build();
```
Das SDK löst die folgenden Proxyeinstellungen auf.
```
Host = localhost
Port = 1234
Password = SYS_PROP_password
UserName = username
Non ProxyHost = null
```
**Example — Sowohl Systemeigenschaften als auch Umgebungsvariablen sind verfügbar**
Der `ProxyConfiguration` Builder jedes HTTP-Clients bietet Einstellungen mit dem Namen `useSystemPropertyValues` und`useEnvironmentVariablesValues`. Standardmäßig sind beide Einstellungen`true`. Wann `true` verwendet das SDK automatisch Werte aus Systemeigenschaften oder Umgebungsvariablen für Optionen, die nicht vom `ProxyConfiguration` Builder bereitgestellt werden.
Systemeigenschaften haben Vorrang vor Umgebungsvariablen. Wenn eine HTTP-Proxy-Systemeigenschaft gefunden wird, ruft das SDK ***alle*** Werte aus den Systemeigenschaften und keine aus Umgebungsvariablen ab. Wenn Sie Umgebungsvariablen Vorrang vor Systemeigenschaften einräumen möchten, legen Sie den Wert auf fest`useSystemPropertyValues`. `false`
Für dieses Beispiel sind die folgenden Einstellungen zur Laufzeit verfügbar:
```
// System properties
http.proxyHost=SYS_PROP_HOST.com
http.proxyPort=2222
http.password=SYS_PROP_PASSWORD
http.user=SYS_PROP_USER
// Environment variables
HTTP_PROXY="http://EnvironmentUser:EnvironmentPassword@ENV_VAR_HOST:3333"
NO_PROXY="environmentnonproxy.host,environmentnonproxy2.host:1234"
```
Der Service-Client wird mit einer der folgenden Anweisungen erstellt. Keine der Anweisungen legt explizit eine Proxyeinstellung fest.
```
DynamoDbClient client = DynamoDbClient.create();
DynamoDbClient client = DynamoDbClient.builder().build();
DynamoDbClient client = DynamoDbClient.builder()
.httpClient(ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.build())
.build())
.build();
```
Die folgenden Proxyeinstellungen werden vom SDK aufgelöst:
```
Host = SYS_PROP_HOST.com
Port = 2222
Password = SYS_PROP_PASSWORD
UserName = SYS_PROP_USER
Non ProxyHost = null
```
Da der Service Client über Standard-Proxyeinstellungen verfügt, sucht das SDK nach Systemeigenschaften und dann nach Umgebungsvariablen. Da Einstellungen für Systemeigenschaften Vorrang vor Umgebungsvariablen haben, verwendet das SDK nur Systemeigenschaften.
Wenn die Verwendung von Systemeigenschaften `false` wie im folgenden Code gezeigt geändert wird, löst das SDK nur die Umgebungsvariablen auf.
```
DynamoDbClient client = DynamoDbClient.builder()
.httpClient(ApacheHttpClient.builder()
.proxyConfiguration(ProxyConfiguration.builder()
.useSystemPropertyValues(Boolean.FALSE)
.build())
.build())
.build();
```
Die mithilfe von HTTP aufgelösten Proxyeinstellungen sind:
```
Host = ENV_VAR_HOST
Port = 3333
Password = EnvironmentPassword
UserName = EnvironmentUser
Non ProxyHost = environmentnonproxy.host, environmentnonproxy2.host:1234
```
# Konfigurieren Sie den Apache 5.x-basierten HTTP-Client
## Greifen Sie auf den Apache5 zu HttpClient
Um das verwenden zu können, müssen `Apache5HttpClient` Sie eine Abhängigkeit von Ihren Service-Clients hinzufügen **apache5-client** und diese explizit konfigurieren`Apache5HttpClient`.
```
software.amazon.awssdkbom2.41.0*pomimportsoftware.amazon.awssdks3software.amazon.awssdkapache5-client
```
\$1Ersetzen Sie die rot dargestellte Version durch die Version des Java-SDK, die Sie verwenden möchten. Finden Sie die neuesten Informationen auf [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).
### Verwenden und konfigurieren Sie den `Apache5HttpClient`
Sie können eine Instanz von `Apache5HttpClient` konfigurieren und gleichzeitig einen Service Client erstellen, oder Sie können eine einzelne Instanz so konfigurieren, dass sie von mehreren Service Clients gemeinsam genutzt wird.
Bei beiden Ansätzen verwenden Sie den [Apache5 HttpClient .Builder](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache5/Apache5HttpClient.Builder.html), um die Eigenschaften für den Apache 5-basierten HTTP-Client zu konfigurieren.
#### Bewährtes Verfahren: Dedizieren Sie eine Apache5-Instanz einem Service-Client HttpClient
Wenn Sie eine Instanz von konfigurieren müssen, empfehlen wir Ihnen`Apache5HttpClient`, die dedizierte Instanz zu erstellen. `Apache5HttpClient` 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 `Apache5HttpClient` Instanz nicht geschlossen wird, wenn sie nicht mehr benötigt wird.
Im folgenden Beispiel wird ein S3Client erstellt und die eingebettete Instanz von `Apache5HttpClient` mit den Werten MaxConnections und ConnectionTimeout konfiguriert. Die HTTP-Instanz wird mit der Methode von erstellt. `httpClientBuilder` `S3Client.Builder`
**Importe**
```
import software.amazon.awssdk.http.apache5.Apache5HttpClient;
import software.amazon.awssdk.services.s3.S3Client;
import java.time.Duration;
```
**Code**
```
S3Client s3Client = S3Client // Singleton: Use the s3Client for all requests.
.builder()
.httpClientBuilder(Apache5HttpClient.builder()
.maxConnections(100)
.connectionTimeout(Duration.ofSeconds(5))
)
.build();
// Perform work with the s3Client.
s3Client.close(); // Requests completed: Close all service clients.
```
#### Alternativer Ansatz: Eine `Apache5HttpClient` Instanz teilen
Um den Ressourcen- und Speicherverbrauch für Ihre Anwendung zu senken, können Sie eine konfigurieren `Apache5HttpClient` und sie von mehreren Service-Clients gemeinsam nutzen. Der HTTP-Verbindungspool wird gemeinsam genutzt, was die Ressourcennutzung senkt.
**Anmerkung**
Wenn eine `Apache5HttpClient` 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 ein Apache-basierter HTTP-Client konfiguriert, der von zwei Service-Clients verwendet wird. Die konfigurierte `ApacheHttpClient` Instanz wird an die HttpClient-Methode jedes Builders übergeben. Wenn die Service-Clients und der HTTP-Client nicht mehr benötigt werden, werden sie durch den Code explizit geschlossen. Der Code schließt den HTTP-Client zuletzt.
**Importe**
```
import software.amazon.awssdk.http.SdkHttpClient;
import software.amazon.awssdk.http.apache5.Apache5HttpClient;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.s3.S3Client;
```
**Code**
```
SdkHttpClient apache5HttpClient = Apache5HttpClient.builder()
.maxConnections(100).build();
// Singletons: Use the s3Client and dynamoDbClient for all requests.
S3Client s3Client =
S3Client.builder()
.httpClient(apache5HttpClient).build();
DynamoDbClient dynamoDbClient =
DynamoDbClient.builder()
.httpClient(apache5HttpClient).build();
// Perform work with the s3Client and dynamoDbClient.
// Requests completed: Close all service clients.
s3Client.close();
dynamoDbClient.close();
apache5HttpClient.close(); // Explicitly close apache5HttpClient.
```
# Verwenden Sie Execution Interceptors in der AWS SDK for Java 2.x
Interceptoren für die Ausführung in den AWS SDK for Java 2.x Anforderungs- und Antwortlebenszyklus, um in verschiedenen Phasen der Ausführung von API-Aufrufen benutzerdefinierte Logik auszuführen. Verwenden Sie Interzeptoren, um bereichsübergreifende Aufgaben wie Protokollierung, Erfassung von Metriken, Änderung von Anfragen, Debugging und Fehlerbehandlung zu implementieren.
Interceptoren implementieren die [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/interceptor/ExecutionInterceptor.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/interceptor/ExecutionInterceptor.html)Schnittstelle, die Hooks für verschiedene Phasen der Anforderungsausführung bereitstellt.
## Lebenszyklus des Interceptors
Die `ExecutionInterceptor` Schnittstelle stellt Methoden bereit, die an bestimmten Stellen während der Anforderungsausführung aufgerufen werden:
+ `beforeExecution`- Wird aufgerufen, bevor die Anfrage ausgeführt wird
+ `modifyRequest`- Ändert das SDK-Anforderungsobjekt
+ `beforeMarshalling`- Wird aufgerufen, bevor die Anfrage zu HTTP weitergeleitet wird
+ `afterMarshalling`- Wird aufgerufen, nachdem die Anfrage zu HTTP weitergeleitet wurde
+ `modifyHttpRequest`- Ändert die HTTP-Anfrage
+ `beforeTransmission`- Wird aufgerufen, bevor die HTTP-Anfrage gesendet wird
+ `afterTransmission`- Wird aufgerufen, nachdem die HTTP-Antwort empfangen wurde
+ `modifyHttpResponse`- Ändert die HTTP-Antwort
+ `beforeUnmarshalling`- Wird aufgerufen, bevor die HTTP-Antwort das Marshalling beendet
+ `afterUnmarshalling`- Wird aufgerufen, nachdem die HTTP-Antwort den Marshals ausgeführt hat
+ `modifyResponse`- Ändert das SDK-Antwortobjekt
+ `afterExecution`- Wird nach erfolgreicher Ausführung der Anfrage aufgerufen
+ `onExecutionFailure`- Wird aufgerufen, wenn die Ausführung der Anfrage fehlschlägt
## Interzeptoren registrieren
Registrieren Sie Interzeptoren, wenn Sie mit dieser Methode einen Service-Client erstellen. `overrideConfiguration` Sie können mehrere Interzeptoren registrieren, und sie werden in der Reihenfolge ausgeführt, in der Sie sie registrieren.
```
// Register a single interceptor.
SqsClient client = SqsClient.builder()
.overrideConfiguration(c -> c.addExecutionInterceptor(new LoggingInterceptor()))
.build();
// Register multiple interceptors.
S3Client s3Client = S3Client.builder()
.overrideConfiguration(config -> config
.addExecutionInterceptor(new TimingInterceptor())
.addExecutionInterceptor(new LoggingInterceptor())
.addExecutionInterceptor(new RequestModificationInterceptor()))
.build();
```
## Beispiel für einen Interceptor
In der folgenden Klasse wird gezeigt, wie Sie mithilfe von Execution Interceptors bereichsübergreifende Aspekte wie Protokollierung, Leistungsüberwachung und Änderung von Anfragen zu Ihren S3-Vorgängen hinzufügen können, ohne Ihre Kerngeschäftslogik zu ändern.
Dieses Beispiel zeigt Ihnen, wie Sie mehrere Interzeptoren auf einem S3-Client registrieren und sie bei echten API-Aufrufen in Aktion beobachten können. AWS
### Importe
```
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.awscore.exception.AwsServiceException;
import software.amazon.awssdk.core.ApiName;
import software.amazon.awssdk.core.SdkRequest;
import software.amazon.awssdk.core.interceptor.Context;
import software.amazon.awssdk.core.interceptor.ExecutionAttributes;
import software.amazon.awssdk.core.interceptor.ExecutionInterceptor;
import software.amazon.awssdk.http.SdkHttpRequest;
import software.amazon.awssdk.http.SdkHttpResponse;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.HeadBucketRequest;
import software.amazon.awssdk.services.s3.model.ListBucketsResponse;
import java.time.Duration;
import java.time.Instant;
```
```
public class S3InterceptorsDemo {
private static final Logger logger = LoggerFactory.getLogger(S3InterceptorsDemo.class);
public static void main(String[] args) {
logger.info("=== AWS SDK for Java v2 - S3 Interceptors Demo ===");
// Create an S3 client with multiple interceptors.
S3Client s3Client = S3Client.builder()
.overrideConfiguration(config -> config
.addExecutionInterceptor(new TimingInterceptor())
.addExecutionInterceptor(new LoggingInterceptor())
.addExecutionInterceptor(new RequestModificationInterceptor()))
.build();
try {
logger.info("Starting S3 operations with interceptors...");
// Operation 1: List buckets.
logger.info("Operation 1: Listing S3 buckets");
logger.info("----------------------------------------");
ListBucketsResponse listBucketsResponse = s3Client.listBuckets();
logger.info("Found {} buckets", listBucketsResponse.buckets().size());
// Operation 2: Try to access a bucket that likely doesn't exist.
logger.info("Operation 2: Checking non-existent bucket (demonstrating error interceptor)");
logger.info("----------------------------------------");
try {
s3Client.headBucket(HeadBucketRequest.builder()
.bucket("amzn-s3-demo-bucket-that-does-not-exist-1234")
.build());
} catch (Exception e) {
logger.info("Expected error occurred (interceptor should have logged it)");
}
} catch (Exception e) {
logger.error(" Error during S3 operations: {}", e.getMessage(), e);
} finally {
s3Client.close();
logger.info("Demo completed - S3 client closed");
}
}
// Logging interceptor.
private static class LoggingInterceptor implements ExecutionInterceptor {
private static final Logger logger = LoggerFactory.getLogger(LoggingInterceptor.class);
@Override
public void beforeExecution(Context.BeforeExecution context, ExecutionAttributes executionAttributes) {
logger.info("[LOGGING] Starting request: {}", context.request().getClass().getSimpleName());
}
@Override
public void afterExecution(Context.AfterExecution context, ExecutionAttributes executionAttributes) {
logger.info("[LOGGING] Completed request: {}", context.request().getClass().getSimpleName());
}
@Override
public void onExecutionFailure(Context.FailedExecution context, ExecutionAttributes executionAttributes) {
logger.error("[LOGGING] Request failed: {}", context.request().getClass().getSimpleName());
if (context.exception() instanceof AwsServiceException) {
AwsServiceException ase = (AwsServiceException) context.exception();
if (ase.awsErrorDetails().errorCode() != null) {
SdkHttpResponse httpResponse = ase.awsErrorDetails().sdkHttpResponse();
logger.error(" HTTP Status: {}", httpResponse.statusCode());
logger.error(" Error Code: {}", ase.awsErrorDetails().errorCode());
logger.error(" Error Message: {}", ase.awsErrorDetails().errorMessage());
}
}
}
}
// Performance timing interceptor.
private static class TimingInterceptor implements ExecutionInterceptor {
private static final Logger logger = LoggerFactory.getLogger(TimingInterceptor.class);
private Instant startTime;
@Override
public void beforeExecution(Context.BeforeExecution context, ExecutionAttributes executionAttributes) {
startTime = Instant.now();
logger.info("⏱️ [TIMING] Request started at: {}", startTime);
}
@Override
public void afterExecution(Context.AfterExecution context, ExecutionAttributes executionAttributes) {
if (startTime != null) {
Duration duration = Duration.between(startTime, Instant.now());
logger.info("⏱️ [TIMING] Request completed in: {}ms", duration.toMillis());
}
}
@Override
public void onExecutionFailure(Context.FailedExecution context, ExecutionAttributes executionAttributes) {
if (startTime != null) {
Duration duration = Duration.between(startTime, Instant.now());
logger.warn("⏱️ [TIMING] Request failed after: {}ms", duration.toMillis());
}
}
}
// Request modification interceptor
private static class RequestModificationInterceptor implements ExecutionInterceptor {
private static final Logger logger = LoggerFactory.getLogger(RequestModificationInterceptor.class);
@Override
public SdkRequest modifyRequest(Context.ModifyRequest context, ExecutionAttributes executionAttributes) {
SdkRequest originalRequest = context.request();
logger.info("[MODIFY] Modifying request: {}", originalRequest.getClass().getSimpleName());
// For ListBucketsRequest, we can't modify much since it has no settable properties
// For HeadBucketRequest, we can demonstrate modifying the request
if (originalRequest instanceof HeadBucketRequest) {
HeadBucketRequest headRequest = (HeadBucketRequest) originalRequest;
// Create a new request with an API name added.
return HeadBucketRequest.builder()
.bucket(headRequest.bucket())
.overrideConfiguration(b -> b.addApiName(ApiName.builder()
.name("My-API")
.version("1.0")
.build()))
.build();
}
logger.info("Not a HeadBucketRequest, returning original request");
return originalRequest;
}
@Override
public SdkHttpRequest modifyHttpRequest(Context.ModifyHttpRequest context, ExecutionAttributes executionAttributes) {
logger.info("[MODIFY] Adding custom HTTP headers");
return context.httpRequest().toBuilder()
.putHeader("X-Custom-Header", "S3InterceptorDemo")
.putHeader("X-Request-ID", java.util.UUID.randomUUID().toString())
.build();
}
}
}
```
### Maven-Pom-Datei
```
4.0.0org.exampleinterceptors-examples1.0.0jarinterceptors-examplesDemonstration of execution interceptors in AWS SDK for Java v21717UTF-82.31.62org.example.S3InterceptorsDemosoftware.amazon.awssdkbom${aws.java.sdk.version}pomimportorg.apache.logging.log4jlog4j-bom2.23.1pomimportsoftware.amazon.awssdks3org.apache.logging.log4jlog4j-coreorg.slf4jslf4j-api2.0.13org.apache.logging.log4jlog4j-slf4j2-implorg.apache.logging.log4jlog4j-1.2-apiorg.junit.jupiterjunit-jupiter5.10.1testorg.apache.maven.pluginsmaven-compiler-plugin3.11.01717org.apache.maven.pluginsmaven-surefire-plugin3.2.2org.codehaus.mojoexec-maven-plugin3.1.0${exec.mainClass}org.apache.maven.pluginsmaven-shade-plugin3.4.1packageshade${exec.mainClass}false
```
## Bewährte Methoden
+ **Halten Sie Interzeptoren möglichst klein — Interzeptoren** werden bei jeder Anfrage ausgeführt. Vermeiden Sie daher umfangreiche Berechnungen oder Blockierungen von Vorgängen, die sich negativ auf die Leistung auswirken könnten.
+ Gehen Sie **ordnungsgemäß mit Ausnahmen um** — Wenn Ihr Interceptor eine Ausnahme auslöst, schlägt die gesamte Anfrage fehl. Verwenden Sie immer Try-Catch-Blöcke für potenziell fehlgeschlagene Operationen.
+ **Reihenfolge ist wichtig** — Interceptoren werden in der Reihenfolge ausgeführt, in der Sie sie registrieren. Berücksichtigen Sie bei der Registrierung die Abhängigkeiten zwischen Ihren Interceptoren.
+ ** ExecutionAttributes Für den Status verwenden** — Wenn Sie Daten zwischen verschiedenen Interceptormethoden übergeben müssen, verwenden Sie zur Gewährleistung der `ExecutionAttributes` Thread-Sicherheit keine Instanzvariablen.
+ **Achten Sie auf sensible Daten — Achten Sie beim Protokollieren von** Anfragen und Antworten darauf, keine vertraulichen Informationen wie Anmeldeinformationen oder persönliche Daten zu protokollieren.
## Kontextobjekte
Jede Interceptor-Methode erhält ein Kontextobjekt, das Zugriff auf Anfrage- und Antwortinformationen in verschiedenen Ausführungsphasen ermöglicht:
+ `Context.BeforeExecution`- Ermöglicht den Zugriff auf die ursprüngliche SDK-Anfrage
+ `Context.ModifyRequest`- Ändert die SDK-Anfrage
+ `Context.ModifyHttpRequest`- Ändert die HTTP-Anfrage
+ `Context.AfterExecution`- Bietet Zugriff auf Anfrage und Antwort
+ `Context.FailedExecution`- Ermöglicht den Zugriff auf die Anfrage und die aufgetretene Ausnahme