Benutze die AWS SDK for Java 2.x

Nachdem Sie die Schritte unter SDK einrichten abgeschlossen haben, können Sie Anfragen an AWS Services wie Amazon S3, DynamoDB, IAM, Amazon EC2 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

Service-Clients im SDK sind threadsicher. 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 Service-Client-Objekt ist unveränderlich. Sie müssen also für jeden Service, an den Sie Anfragen stellen, einen neuen Client erstellen, oder wenn Sie eine andere Konfiguration für Anfragen an denselben Service 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-Aufrufe 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 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 das SDK die zu verwendenden Anmeldeinformationen und die Region bestimmt, 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();

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 Amazon EC2 EC2-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, bietet das SDK Builder, mit denen Sie eine Anfrage erstellen können. Mit einem Builder können Sie Java-Lambda-Ausdrücke verwenden, um die Anfrage „inline“ zu erstellen.

Im folgenden Beispiel wird das vorherige Beispiel neu geschrieben, 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));

Antworten verarbeiten

Das SDK gibt für die meisten Dienstoperationen ein Antwortobjekt 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());
}

Schließen Sie den Service-Client

Es hat sich bewährt, während der Lebensdauer einer Anwendung einen Service-Client für mehrere API-Dienstaufrufe 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 das JDK die close() Methode am Ende der Anweisung automatisch aufruft.

Das folgende Beispiel zeigt, wie ein Service-Client 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();
    }
}

Ausnahmen behandeln

Das 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 das SDK auslöst. 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.

HTTP-Clients

Sie können die Standardkonfiguration für HTTP-Clients in Anwendungen ändern, die Sie mit dem AWS SDK for Java erstellen. Informationen zur Konfiguration von HTTP-Clients und Einstellungen finden Sie unter HTTP-Konfiguration.

Timeouts

Sie können Timeouts für jeden Ihrer Service-Clients konfigurieren, indem Sie die apiCallTimeoutund die apiCallAttemptTimeoutSetter von verwenden. ClientOverrideConfiguration.Builder Die apiCallTimeout Einstellung gibt an, wie lange der Client die Ausführung eines API-Aufrufs 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 no 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-/Antwort-Lebenszyklus abfängt. Auf diese Weise können Sie Metriken veröffentlichen, eine Anfrage während der Bearbeitung ändern, Fehler bei der Bearbeitung von Anfragen beheben, Ausnahmen anzeigen und vieles mehr. Weitere Informationen finden Sie in der AWS SDK for Java API-Referenz zur ExecutionInterceptor Schnittstelle.

Zusätzliche Informationen

• Vollständige Beispiele für die obigen Codefragmente finden Sie unter Arbeiten mit Amazon DynamoDB, Arbeiten mit Amazon EC2 und Arbeiten mit. Amazon S3