Arbeiten Sie mit Servicekunden zusammen Anfragen stellen Antworten verarbeiten Behandeln Sie Ausnahmen Verwenden Sie Kellner Legen Sie Timeouts fest Interzeptoren für die Ausführung

Benutze die AWS SDK for Java 2.x

Nachdem Sie die Schritte unter Einrichten von abgeschlossen habenSDK, können Sie Anfragen an AWS Dienste wie Amazon S3, DynamoDB IAMEC2, Amazon und mehr stellen.

Arbeiten Sie mit Servicekunden zusammen

Erstellen Sie einen Serviceclient

Um eine Anfrage an zu stellen AWS-Service, müssen Sie zunächst einen Dienstclient für diesen Dienst instanziieren, indem Sie die statische Factory-Methode verwenden,. builder() Die builder() Methode gibt ein builder Objekt zurück, mit dem Sie den Dienstclient anpassen können. Die praktischen Setter-Methoden geben das builder-Objekt zurück. So können Sie die Methodenaufrufe in Reihe schalten, was nicht nur einfacher ist, sondern auch für besser lesbaren Code sorgt. Nachdem Sie die gewünschten Eigenschaften konfiguriert haben, rufen Sie die build() Methode auf, um den Client zu erstellen.

Als Beispiel instanziiert der folgende Codeausschnitt ein Ec2Client Objekt als Service-Client für Amazon. EC2


Region region = Region.US_WEST_2;
Ec2Client ec2Client = Ec2Client.builder()
        .region(region)
        .build();

Anmerkung

Die Service-Clients in sind threadsicher. SDK Um eine optimale Leistung zu erzielen, behandeln Sie sie wie langlebige Objekte. Jeder Client verfügt über seine eigene Verbindungspool-Ressource, die freigegeben wird, wenn der Client von der Speicherbereinigung entfernt wird.

Ein Dienstclientobjekt ist unveränderlich. Sie müssen also für jeden Dienst, an den Sie Anfragen stellen, einen neuen Client erstellen, oder wenn Sie eine andere Konfiguration für Anfragen an denselben Dienst verwenden möchten.

Die Angabe von Region im Service Client Builder ist nicht für alle AWS Dienste erforderlich. Es hat sich jedoch bewährt, die Region für die API Anrufe festzulegen, die Sie in Ihren Anwendungen tätigen. Weitere Informationen finden Sie unter AWS Regionsauswahl.

Standard-Client-Konfiguration

Die Client-Generatoren haben eine weitere Factory-Methode mit dem Namen create(). Diese Methode erstellt einen Service-Client mit der Standard-Konfiguration. Es verwendet die Standardanbieterkette zum Laden von Anmeldeinformationen und der AWS-Region. Wenn die Anmeldeinformationen oder die Region nicht anhand der Umgebung ermittelt werden können, in der die Anwendung ausgeführt wird, schlägt der Aufruf von create fehl. Weitere Informationen darüber, wie die zu verwendenden Anmeldeinformationen und Region SDK bestimmt werden, finden Sie unter Anmeldeinformationen verwenden und Region auswählen.

Der folgende Codeausschnitt instanziiert beispielsweise ein DynamoDbClient Objekt als Service-Client für Amazon DynamoDB:


DynamoDbClient dynamoDbClient = DynamoDbClient.create();

Service-Clients konfigurieren

Verwenden Sie die Einstellungen der builder() Factory-Methode, um die Konfiguration eines Service-Clients anzupassen. Der Einfachheit halber und um besser lesbaren Code zu erstellen, sollten Sie die Methoden verketten, um mehrere Konfigurationsoptionen festzulegen.

Das folgende Beispiel zeigt eineS3Client, die mit mehreren benutzerdefinierten Einstellungen konfiguriert ist.


ClientOverrideConfiguration clientOverrideConfiguration =
    ClientOverrideConfiguration.builder()
                    .apiCallAttemptTimeout(Duration.ofSeconds(1))
                    .retryPolicy(RetryPolicy.builder().numRetries(10).build())
                    .addMetricPublisher(CloudWatchMetricPublisher.create())
                    .build();

Region region = Region.US_WEST_2;
S3Client s3Client = S3Client.builder()
                    .region(region)
                    .credentialsProvider(EnvironmentVariableCredentialsProvider.create())
                    .overrideConfiguration(clientOverrideConfiguration)
                    .httpClientBuilder(ApacheHttpClient.builder()
                        .proxyConfiguration(proxyConfig.build(ProxyConfiguration.builder()))
                        .build())
                    .build();

Schließen Sie den Service-Client

Es hat sich bewährt, während der Lebensdauer einer Anwendung einen API Service-Client für mehrere Serviceeinsätze zu verwenden. Wenn Sie jedoch einen Service Client für eine einmalige Verwendung benötigen oder den Service Client nicht mehr benötigen, schließen Sie ihn.

Rufen Sie die close() Methode auf, wenn der Service-Client nicht mehr benötigt wird, um Ressourcen freizugeben.


ec2Client.close();

Wenn Sie einen Service-Client für den einmaligen Gebrauch benötigen, können Sie den Service-Client als Ressource in einer try -with-resources-Anweisung instanziieren. Service-Clients implementieren die Autoclosable Schnittstelle, sodass sie die close() Methode am Ende der Anweisung JDK automatisch aufrufen.

Das folgende Beispiel zeigt, wie ein Dienstclient für einen einmaligen Anruf verwendet wird. Die DateiStsClient, die anruft, AWS Security Token Service wird geschlossen, nachdem sie die Konto-ID zurückgegeben hat.


import software.amazon.awssdk.services.sts.StsClient;

String getAccountID() {
    try (StsClient stsClient = StsClient.create()) {
       return stsClient.getCallerIdentity().account();
    }
}

Anfragen stellen

Verwenden Sie den Service-Client, um Anfragen an die entsprechenden Personen zu stellen AWS-Service.

Dieser Codeausschnitt zeigt beispielsweise, wie Sie ein RunInstancesRequest Objekt erstellen, um eine neue EC2 Amazon-Instance zu erstellen:


// Create the request by using the fluid setter methods of the request builder.
RunInstancesRequest runInstancesRequest = RunInstancesRequest.builder()
        .imageId(amiId)
        .instanceType(InstanceType.T1_MICRO)
        .maxCount(1)
        .minCount(1)
        .build();

// Use the configured request with the service client.
RunInstancesResponse response = ec2Client.runInstances(runInstancesRequest);

Anstatt eine Anfrage zu erstellen und die Instance weiterzuleiten, SDK bietet das eine FluentAPI, mit der Sie eine Anfrage erstellen können. Mit dem Fluent können API Sie Java-Lambda-Ausdrücke verwenden, um die Anfrage „in-line“ zu erstellen.

Das folgende Beispiel schreibt das vorherige Beispiel neu, indem es die Version der runInstances Methode verwendet, die einen Builder verwendet, um die Anfrage zu erstellen.


// Create the request by using a lambda expression.
RunInstancesResponse response = ec2.runInstances(r -> r
                .imageId(amiId)
                .instanceType(InstanceType.T1_MICRO)
                .maxCount(1)
                .minCount(1));

Verwenden Sie Anfragen, um die Client-Konfiguration zu überschreiben

Obwohl ein Service-Client unveränderlich ist, können Sie viele seiner Einstellungen auf Anforderungsebene überschreiben. Wenn Sie eine Anfrage erstellen, können Sie eine AwsRequestOverrideConfigurationInstanz bereitstellen, um die überschriebenen Einstellungen bereitzustellen. Einige der Methoden, mit denen Sie Client-Einstellungen überschreiben können, sind:

apiCallAttemptTimeout
apiCallTimeout
credentialProvider
compressionConfiguration
putHeader

Gehen Sie als Beispiel für das Überschreiben einer Client-Einstellung mit einer Anfrage davon aus, dass Sie über den folgenden S3-Client verfügen, der Standardeinstellungen verwendet.


S3Client s3Client = S3Client.create();

Sie möchten eine große Datei herunterladen und sicherstellen, dass es bei der Anfrage nicht zu einem Timeout kommt, bevor der Download abgeschlossen ist. Um dies zu erreichen, erhöhen Sie die Timeout-Werte für nur eine einzelne GetObject Anfrage, wie im folgenden Code gezeigt.

Antworten verarbeiten

Das SDK gibt ein Antwortobjekt für die meisten Dienstoperationen zurück. Ihr Code kann die Informationen im Antwortobjekt Ihren Anforderungen entsprechend verarbeiten.

Der folgende Codeausschnitt druckt beispielsweise die erste Instanz-ID aus, die zusammen mit dem RunInstancesResponseObjekt aus der vorherigen Anfrage zurückgegeben wurde.


RunInstancesResponse runInstancesResponse = ec2Client.runInstances(runInstancesRequest);
System.out.println(runInstancesResponse.instances().get(0).instanceId());

Nicht alle Operationen geben jedoch ein Antwortobjekt mit dienstspezifischen Daten zurück. In diesen Situationen können Sie den HTTP Antwortstatus abfragen, um zu erfahren, ob der Vorgang erfolgreich war.

Der Code im folgenden Codeausschnitt überprüft beispielsweise die HTTP Antwort, um festzustellen, ob der DeleteContactListBetrieb von Amazon Simple Email Service erfolgreich war.


SesV2Client sesv2Client = SesV2Client.create();

DeleteContactListRequest request = DeleteContactListRequest.builder()
    .contactListName("ExampleContactListName")
    .build();

DeleteContactListResponse response = sesv2Client.deleteContactList(request);
if (response.sdkHttpResponse().isSuccessful()) {
    System.out.println("Contact list deleted successfully");
} else {
    System.out.println("Failed to delete contact list. Status code: " + response.sdkHttpResponse().statusCode());
}

Behandeln Sie Ausnahmen

Der SDK verwendet Laufzeitausnahmen (oder ungeprüfte Ausnahmen), sodass Sie die Fehlerbehandlung genau steuern und sicherstellen können, dass die Ausnahmebehandlung mit Ihrer Anwendung skaliert.

Eine SdkServiceExceptionoder eine ihrer Unterklassen ist die häufigste Form von Ausnahme, die ausgelöst wird. SDK Diese Ausnahmen stellen Antworten des AWS Dienstes dar. Sie können auch mit Problemen umgehen SdkClientException, die auftreten, wenn auf der Clientseite (d. h. in Ihrer Entwicklungs- oder Anwendungsumgebung) ein Problem auftritt, z. B. ein Netzwerkverbindungsfehler.

Dieser Codeausschnitt demonstriert eine Möglichkeit, Serviceausnahmen zu behandeln, wenn Sie eine Datei hochladen. Amazon S3 Der Beispielcode fängt sowohl Client- als auch Serverausnahmen ab, protokolliert die Details und gibt die Anwendung an.


Region region = Region.US_WEST_2;
s3Client = S3Client.builder()
        .region(region)
        .build();

try {

    PutObjectRequest putObjectRequest = PutObjectRequest.builder()
                    .bucket(bucketName)
                    .key(key)
                    .build();

    s3Client.putObject(putObjectRequest, RequestBody.fromString("SDK for Java test"));

} catch (S3Exception se) {
    System.err.println("Service exception thrown.");
    System.err.println(se.awsErrorDetails().errorMessage());
} catch (SdkClientExeption ce){
   System.err.println("Client exception thrown.");
   System.err.println(ce.getMessage());
} finally {
   System.exit(1);
}

Weitere Informationen finden Sie unter Umgang mit Ausnahmen.

Verwenden Sie Kellner

Die Bearbeitung einiger Anfragen dauert einige Zeit, z. B. das Erstellen einer neuen Tabelle in DynamoDB oder das Erstellen eines neuen Amazon S3 Buckets. Verwenden Sie einen Kellner, um sicherzustellen, dass die Ressource bereit ist, bevor Ihr Code weiter ausgeführt wird.

Dieser Codeausschnitt erstellt beispielsweise eine neue Tabelle (“ myTable „) in DynamoDB, wartet, bis die Tabelle einen ACTIVE Status hat, und druckt dann die Antwort aus:


DynamoDbClient dynamoDbClient = DynamoDbClient.create();
DynamoDbWaiter dynamoDbWaiter = dynamoDbClient.waiter();

WaiterResponse<DescribeTableResponse> waiterResponse =
   dynamoDbWaiter.waitUntilTableExists(r -> r.tableName("myTable"));

waiterResponse.matched().response().ifPresent(System.out::println);

Weitere Informationen finden Sie unter Kellner verwenden.

Legen Sie Timeouts fest

Sie können Timeouts für jeden Ihrer Service-Clients konfigurieren, indem Sie die Einstellungen apiCallTimeoutund die apiCallAttemptTimeoutEinstellungen von verwenden. ClientOverrideConfiguration.Builder Die apiCallTimeout Einstellung gibt an, wie lange der Client die Ausführung eines API Anrufs abschließen kann. Die apiCallAttemptTimeout Einstellung gibt an, wie lange gewartet werden soll, bis jede HTTP Anfrage (Wiederholung) abgeschlossen ist, bevor der Vorgang abgebrochen wird.

Im folgenden Beispiel werden beide Timeouts für einen S3-Client festgelegt.


S3Client s3Client = S3Client.builder()
    .overrideConfiguration(b -> b
        .apiCallTimeout(Duration.ofSeconds(105L))
        .apiCallAttemptTimeout(Duration.ofSeconds(25L))).
    build();

Sie können Timeouts auch auf Anforderungsebene festlegen, indem Sie eine Methode konfigurieren AwsRequestOverrideConfigurationund sie dem Anforderungsobjekt mit der overrideConfiguration Methode zur Verfügung stellen.

Im folgenden Beispiel werden dieselben Timeout-Einstellungen verwendet, jedoch auf Anforderungsebene für einen PutObject S3-Vorgang.


S3Client basicS3Client = S3Client.create(); // Client with default timeout settings.

AwsRequestOverrideConfiguration overrideConfiguration = AwsRequestOverrideConfiguration.builder()
    .apiCallTimeout(Duration.ofSeconds(105L))
    .apiCallAttemptTimeout(Duration.ofSeconds(25L))
    .build();

basicS3Client.putObject(b -> b
        .bucket("DOC-EXAMPLE-BUCKET")
        .key("DOC-EXAMPLE-KEY")
        .overrideConfiguration(overrideConfiguration),
    RequestBody.fromString("test"));

Interzeptoren für die Ausführung

Sie können Code schreiben, der die Ausführung Ihrer API Anfragen und Antworten an verschiedenen Stellen des Anforderungs-/Antwortlebenszyklus abfängt. Auf diese Weise können Sie Metriken veröffentlichen, eine Anfrage während der Bearbeitung ändern, Fehler bei der Anforderungsverarbeitung beheben, Ausnahmen anzeigen und vieles mehr. Weitere Informationen finden Sie in der Referenz ExecutionInterceptor zur Benutzeroberfläche. AWS SDK for Java API

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

Richten Sie ein GraalVM Native Image-Projekt ein

Geben Sie temporäre Anmeldeinformationen für die SDK