Utilisez le AWS SDK for Java 2.x

Une fois les étapes de configuration du SDK terminées, vous êtes prêt à adresser des demandes à AWS des services tels qu'Amazon S3, DynamoDB, IAM, Amazon, etc. EC2

Travailler avec les clients du service

Création d'un client de service

Pour envoyer une demande à un Service AWS, vous devez d'abord instancier un client de service pour ce service en utilisant la méthode static factory,. builder() La builder() méthode renvoie un builder objet qui vous permet de personnaliser le client de service. Les méthodes setter courantes renvoient l'objet builder pour vous permettre de chaîner les appels de méthode pour plus de commodité et pour obtenir un code plus lisible. Après avoir configuré les propriétés souhaitées, appelez la build() méthode pour créer le client.

À titre d'exemple, l'extrait de code suivant instancie un Ec2Client objet en tant que client de service pour Amazon. EC2

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

Configuration du client par défaut

Les générateurs client ont une autre méthode de fabrique nommée create(). Cette méthode crée un client de service avec la configuration par défaut. Il utilise la chaîne de fournisseurs par défaut pour charger les informations d'identification et le Région AWS. Si les informations d'identification ou la région ne peuvent pas être déterminées à partir de l'environnement dans lequel l'application s'exécute, l'appel create échoue. Consultez les sections Utilisation des informations d'identification et Sélection de la région pour plus d'informations sur la manière dont le SDK détermine les informations d'identification et la région à utiliser.

Par exemple, l'extrait de code suivant instancie un DynamoDbClient objet en tant que client de service pour Amazon DynamoDB :

DynamoDbClient dynamoDbClient = DynamoDbClient.create();

Configuration des clients de service

Pour personnaliser la configuration d'un client de service, utilisez les paramètres de la méthode builder() d'usine. Pour plus de commodité et pour créer un code plus lisible, enchaînez les méthodes pour définir plusieurs options de configuration.

L'exemple suivant S3Client montre un système configuré avec plusieurs paramètres personnalisés.

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

Fermer le client de service

Il est recommandé d'utiliser un client de service pour plusieurs appels de service d'API au cours du cycle de vie d'une application. Toutefois, si vous avez besoin d'un client de service pour une utilisation unique ou si vous n'avez plus besoin du client de service, fermez-le.

Appelez la close() méthode lorsque le client de service n'est plus nécessaire pour libérer des ressources.

ec2Client.close();

Si vous avez besoin d'un client de service pour une utilisation unique, vous pouvez instancier le client de service en tant que ressource dans une instruction try -with-resources. Les clients du service implémentent l'Autoclosableinterface, de sorte que le JDK appelle automatiquement la close() méthode à la fin de l'instruction.

L'exemple suivant montre comment utiliser un client de service pour un appel ponctuel. Le StsClient qui appelle le AWS Security Token Service est fermé après avoir renvoyé l'identifiant du compte.

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

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

Faites des demandes

Utilisez le client de service pour faire des demandes au correspondant Service AWS.

Par exemple, cet extrait de code montre comment créer un RunInstancesRequest objet pour créer une nouvelle instance Amazon EC2  :

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

Plutôt que de créer une demande et de transmettre l'instance, le SDK fournit une API fluide que vous pouvez utiliser pour créer une demande. Avec l'API Fluent, vous pouvez utiliser une expression Java lambda pour créer la demande « en ligne ».

L'exemple suivant réécrit l'exemple précédent en utilisant la version de la runInstances méthode qui utilise un générateur pour créer la demande.

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

Utiliser des demandes pour annuler la configuration du client

Bien qu'un client de service soit immuable, vous pouvez modifier bon nombre de ses paramètres au niveau de la demande. Lorsque vous créez une demande, vous pouvez fournir une AwsRequestOverrideConfigurationinstance pour fournir les paramètres remplacés. Voici certaines des méthodes que vous pouvez utiliser pour modifier les paramètres du client :

Pour un exemple de remplacement d'un paramètre client par une demande, supposons que le client S3 suivant utilise les paramètres par défaut.

S3Client s3Client = S3Client.create();

Vous souhaitez télécharger un fichier volumineux et vous assurer que la demande n'expire pas avant la fin du téléchargement. Pour ce faire, augmentez les valeurs de délai d'expiration pour une seule GetObject demande, comme indiqué dans le code suivant.

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

GetObjectRequest request = GetObjectRequest.builder()
    .bucket("DOC-EXAMPLE-BUCKET")
    .key("DOC-EXAMPLE-KEY")
    .overrideConfiguration(overrideConfiguration)
    .build();

s3Client.getObject(request, myPath);

Gérer les réponses

Le SDK renvoie un objet de réponse pour la plupart des opérations de service. Votre code peut traiter les informations contenues dans l'objet de réponse en fonction de vos besoins.

Par exemple, l'extrait de code suivant affiche le premier identifiant d'instance renvoyé avec l'RunInstancesResponseobjet de la demande précédente.

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

Cependant, toutes les opérations ne renvoient pas d'objet de réponse contenant des données spécifiques au service. Dans ces situations, vous pouvez demander l'état de la réponse HTTP pour savoir si l'opération a réussi.

Par exemple, le code de l'extrait suivant vérifie la réponse HTTP pour vérifier si le DeleteContactListfonctionnement d'Amazon Simple Email Service s'est déroulé correctement.

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

Gérer les exceptions

Le SDK utilise des exceptions d'exécution (ou non contrôlées), vous permettant ainsi de contrôler avec précision la gestion des erreurs et de garantir que la gestion des exceptions évolue en fonction de votre application.

Une SdkServiceException, ou l'une de ses sous-classes, est la forme d'exception la plus courante émise par le SDK. Ces exceptions représentent les réponses du AWS service. Vous pouvez également gérer un SdkClientExceptionproblème qui se produit en cas de problème côté client (c'est-à-dire dans votre environnement de développement ou d'application), tel qu'une panne de connexion réseau.

Cet extrait de code montre une façon de gérer les exceptions de service lorsque vous chargez un fichier vers. Amazon S3 L'exemple de code détecte à la fois les exceptions du client et du serveur, enregistre les détails et fait exister l'application.

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

Voir Gestion des exceptions pour plus d'informations.

Utilisez des serveurs

Le traitement de certaines demandes prend du temps, comme la création d'une nouvelle table DynamoDB ou d'un nouveau Amazon S3 compartiment. Pour vous assurer que la ressource est prête avant que votre code ne continue de s'exécuter, utilisez un serveur.

Par exemple, cet extrait de code crée une nouvelle table (« MyTable ») dans DynamoDB, attend que la table ait un ACTIVE statut, puis imprime la réponse :

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

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

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

Voir Utilisation de serveurs pour plus d'informations.

Définissez des délais

Vous pouvez configurer les délais d'expiration pour chacun de vos clients de service à l'aide apiCallAttemptTimeoutdes paramètres apiCallTimeoutet du. ClientOverrideConfiguration.Builder Le apiCallTimeout paramètre est le délai imparti au client pour terminer l'exécution d'un appel d'API. Le apiCallAttemptTimeout paramètre est le temps d'attente avant que chaque requête HTTP (nouvelle tentative) soit terminée avant d'abandonner.

L'exemple suivant définit les deux délais d'expiration pour un client S3.

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

Vous pouvez également définir des délais d'expiration au niveau de la demande en configurant un AwsRequestOverrideConfigurationet en le fournissant à l'objet de la demande avec la overrideConfiguration méthode.

L'exemple suivant utilise les mêmes paramètres de délai d'attente, mais au niveau de la demande pour une PutObject opération S3.

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

Intercepteurs d'exécution

Vous pouvez écrire du code qui intercepte l'exécution de vos demandes et réponses d'API à différentes étapes du cycle de vie des demandes/réponses. Cela vous permet de publier des métriques, de modifier une demande en cours de route, de déboguer le traitement des demandes, de consulter les exceptions, etc. Pour plus d'informations, consultez l'ExecutionInterceptorinterface dans la référence de l' AWS SDK pour Java API.