Usa il AWS SDK for Java 2.x

Dopo aver completato i passaggi descritti in Configurazione dell'SDK, sei pronto per effettuare richieste a AWS servizi come Amazon S3, DynamoDB, IAM, Amazon EC2 e molti altri.

Collabora con i clienti del servizio

Crea un client di servizio

Per effettuare una richiesta a un Servizio AWS, devi prima creare un'istanza di un client di servizio per quel servizio utilizzando il metodo static factory,. builder() Il builder() metodo restituisce un builder oggetto che consente di personalizzare il client del servizio. I metodi setter fluent restituiscono l'oggetto builder. In questo modo puoi concatenare chiamate al metodo per comodità e per avere un codice più leggibile. Dopo aver configurato le proprietà desiderate, chiamate il build() metodo per creare il client.

Ad esempio, il seguente frammento di codice crea un'istanza di un Ec2Client oggetto come client di servizio per Amazon EC2.

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

Nota

I client del servizio nell'SDK sono thread-safe. Per prestazioni ottimali, ti consigliamo di trattarli come oggetti di lunga durata. Ogni client dispone di una propria risorsa di pooling delle connessioni che viene rilasciata durante il processo di garbage collection del client.

Un oggetto client di servizio è immutabile, quindi è necessario creare un nuovo client per ogni servizio a cui si effettuano richieste o se si desidera utilizzare una configurazione diversa per effettuare richieste allo stesso servizio.

Non è necessario specificare Region nel service client builder per tutti i AWS servizi; tuttavia, è consigliabile impostare la regione per le chiamate API effettuate nelle applicazioni. Per ulteriori informazioni, consulta la sezione Selezione della AWS regione.

Configurazione client predefinita

I generatori client dispongono di un altro metodo factory denominato create(). Questo metodo consente di creare un client del servizio con la configurazione predefinita. Utilizza la catena di provider predefinita per caricare le credenziali e il Regione AWS. Se non è possibile determinare le credenziali o la regione dall'ambiente in cui è in esecuzione l'applicazione, la chiamata a create ha esito negativo. Vedi Utilizzo delle credenziali e Selezione della regione per ulteriori informazioni su come l'SDK determina le credenziali e la regione da utilizzare.

Ad esempio, il seguente frammento di codice crea un'istanza di un DynamoDbClient oggetto come client di servizio per Amazon DynamoDB:

DynamoDbClient dynamoDbClient = DynamoDbClient.create();

Configurare i client di servizio

Per personalizzare la configurazione di un client di servizio, utilizzate i setter del metodo builder() factory. Per comodità e per creare codice più leggibile, concatenate i metodi per impostare più opzioni di configurazione.

L'esempio seguente mostra un S3Client file configurato con diverse impostazioni personalizzate.

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

Effettua richieste

Utilizza il client di servizio per effettuare richieste al corrispondente Servizio AWS.

Ad esempio, questo frammento di codice mostra come creare un RunInstancesRequest oggetto per creare una nuova istanza 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);

Anziché creare una richiesta e passarla all'istanza, l'SDK fornisce dei builder che puoi utilizzare per creare una richiesta. Con un builder puoi utilizzare un'espressione lambda Java per creare la richiesta «in linea».

L'esempio seguente riscrive l'esempio precedente utilizzando la versione del runInstances metodo che utilizza un builder per creare la richiesta.

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

Gestisci le risposte

L'SDK restituisce un oggetto di risposta per la maggior parte delle operazioni di servizio. Il codice può elaborare le informazioni nell'oggetto di risposta in base alle vostre esigenze.

Ad esempio, il seguente frammento di codice stampa l'ID di prima istanza restituito con l'RunInstancesResponseoggetto dalla richiesta precedente.

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

Tuttavia, non tutte le operazioni restituiscono un oggetto di risposta con dati specifici del servizio. In queste situazioni, è possibile interrogare lo stato della risposta HTTP per sapere se l'operazione ha avuto esito positivo.

Ad esempio, il codice nello snippet seguente verifica la risposta HTTP per verificare se il DeleteContactListfunzionamento di Amazon Simple Email Service ha avuto successo.

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

Chiudi il client del servizio

Come procedura ottimale, è consigliabile utilizzare un client di servizio per più chiamate al servizio API durante la vita di un'applicazione. Tuttavia, se hai bisogno di un client di servizio per un uso singolo o non hai più bisogno del client di servizio, chiudilo.

Richiamate il close() metodo quando il client di servizio non è più necessario per liberare risorse.

ec2Client.close();

Se hai bisogno di un client di servizio da utilizzare una sola volta, puoi creare un'istanza del client di servizio come risorsa in un'tryistruzione -with-resources. I client di servizio implementano l'Autoclosableinterfaccia, quindi il JDK chiama automaticamente il metodo alla fine dell'close()istruzione.

L'esempio seguente mostra come utilizzare un client di servizio per una chiamata una tantum. La chiamata StsClient che chiama AWS Security Token Service viene chiusa dopo la restituzione dell'ID dell'account.

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

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

Gestisci le eccezioni

L'SDK utilizza eccezioni di runtime (o non controllate), che forniscono un controllo preciso sulla gestione degli errori e garantiscono che la gestione delle eccezioni sia scalabile in base all'applicazione.

Una SdkServiceExceptiono una delle sue sottoclassi è la forma di eccezione più comune generata dall'SDK. Queste eccezioni rappresentano le risposte del servizio. AWS Puoi anche gestire un SdkClientExceptionproblema sul lato client (ad esempio, nell'ambiente di sviluppo o applicativo), come un errore di connessione di rete.

Questo frammento di codice mostra un modo per gestire le eccezioni di servizio quando si carica un file su. Amazon S3 Il codice di esempio rileva le eccezioni del client e del server, registra i dettagli ed esiste l'applicazione.

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

Per ulteriori informazioni, vedere Gestione delle eccezioni.

Usa i camerieri

L'elaborazione di alcune richieste richiede tempo, ad esempio la creazione di una nuova tabella in DynamoDB o la creazione di un nuovo Amazon S3 bucket. Per assicurarti che la risorsa sia pronta prima che il codice continui a funzionare, usa un Waiter.

Ad esempio, questo frammento di codice crea una nuova tabella («myTable») in DynamoDB, attende che la tabella abbia uno ACTIVE stato, quindi stampa la risposta:

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

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

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

Per ulteriori informazioni, consulta Uso dei camerieri.

Client HTTP

È possibile modificare la configurazione predefinita per i client HTTP nelle applicazioni create con. AWS SDK for Java Per informazioni su come configurare i client e le impostazioni HTTP, consulta Configurazione HTTP.

Tentativi

È possibile modificare le impostazioni predefinite per i nuovi tentativi nei client di servizio, inclusa la modalità di ripetizione e la strategia di back-off. Per ulteriori informazioni, fate riferimento alla RetryPolicyclasse nell'API Reference. AWS SDK for Java

Per ulteriori informazioni sui nuovi tentativi nei AWS servizi, vedete Ritentativi di errore e backoff esponenziale in. AWS

Timeout

È possibile configurare i timeout per ciascuno dei client di servizio utilizzando e i setter di. apiCallTimeoutapiCallAttemptTimeoutClientOverrideConfiguration.Builder L'apiCallTimeoutimpostazione indica la quantità di tempo necessaria per consentire al client di completare l'esecuzione di una chiamata API. L'apiCallAttemptTimeoutimpostazione indica il tempo di attesa per il completamento di ogni richiesta HTTP (nuovo tentativo) prima di rinunciare.

L'esempio seguente imposta entrambi i timeout per un client S3.

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

Puoi anche impostare i timeout a livello di richiesta configurando un oggetto di richiesta AwsRequestOverrideConfiguratione fornendolo all'oggetto della richiesta con il metodo. overrideConfiguration

L'esempio seguente utilizza le stesse impostazioni di timeout ma a livello di richiesta per un'operazione S3. PutObject

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

Intercettori di esecuzione

È possibile scrivere codice che intercetta l'esecuzione delle richieste e delle risposte API in diverse parti del ciclo di vita della richiesta/risposta. Ciò consente di pubblicare metriche, modificare una richiesta in corso, eseguire il debug dell'elaborazione delle richieste, visualizzare le eccezioni e altro ancora. Per ulteriori informazioni, consulta l'ExecutionInterceptorinterfaccia nell'API Reference. AWS SDK for Java

Informazioni aggiuntive

• Per esempi completi dei frammenti di codice precedenti, consulta Lavorare con Amazon DynamoDB, Lavorare con Amazon EC2 e Lavorare con. Amazon S3