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 e altri. EC2

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

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

Chiudere il client di 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();
    }
}

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 un'API fluida che puoi utilizzare per creare una richiesta. Con l'API fluent 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));

Utilizzate le richieste per sovrascrivere la configurazione del client

Sebbene un client di servizio sia immutabile, è possibile sovrascrivere molte delle sue impostazioni a livello di richiesta. Quando si crea una richiesta, è possibile fornire un'AwsRequestOverrideConfigurationistanza per fornire le impostazioni sostituite. Alcuni dei metodi che puoi usare per sovrascrivere le impostazioni del client sono:

Per un esempio di sovrascrittura di un'impostazione del client con una richiesta, supponiamo di avere il seguente client S3 che utilizza le impostazioni predefinite.

S3Client s3Client = S3Client.create();

Vuoi scaricare un file di grandi dimensioni e assicurarti che la richiesta non scada prima del termine del download. A tale scopo, aumenta i valori di timeout per una sola GetObject richiesta, come mostrato nel codice seguente.

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

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

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, vedi Uso dei camerieri.

Imposta i timeout

Puoi configurare i timeout per ciascuno dei tuoi client di servizio utilizzando i apiCallTimeoute i apiCallAttemptTimeoutsetter di. ClientOverrideConfiguration.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 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"));

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 per Java