Gunakan AWS SDK for Java 2.x

Setelah menyelesaikan langkah-langkah dalam Menyiapkan SDK, Anda siap untuk membuat permintaan ke AWS layanan seperti Amazon S3, DynamoDB, IAM, Amazon, dan banyak lagi. EC2

Bekerja dengan klien layanan

Buat klien layanan

Untuk membuat permintaan ke Layanan AWS, Anda harus terlebih dahulu membuat instance klien layanan untuk layanan tersebut dengan menggunakan metode pabrik statis,. builder() builder()Metode mengembalikan builder objek yang memungkinkan Anda untuk menyesuaikan klien layanan. Metode penyetel yang lancar mengembalikan builder objek, sehingga Anda dapat merantai panggilan metode untuk kenyamanan dan kode yang lebih mudah dibaca. Setelah Anda mengkonfigurasi properti yang Anda inginkan, panggil build() metode untuk membuat klien.

Sebagai contoh, cuplikan kode berikut membuat instance Ec2Client objek sebagai klien layanan untuk Amazon. EC2

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

Konfigurasi klien default

Pembangun klien memiliki metode pabrik lain bernamacreate(). Metode ini menciptakan klien layanan dengan konfigurasi default. Ini menggunakan rantai penyedia default untuk memuat kredensi dan file. Wilayah AWS Jika kredensil atau Wilayah tidak dapat ditentukan dari lingkungan tempat aplikasi berjalan, panggilan ke create gagal. Lihat Menggunakan kredensil dan pemilihan Wilayah untuk informasi selengkapnya tentang cara SDK menentukan kredensil dan Wilayah yang akan digunakan.

Misalnya, cuplikan kode berikut membuat instance DynamoDbClient objek sebagai klien layanan untuk Amazon DynamoDB:

DynamoDbClient dynamoDbClient = DynamoDbClient.create();

Konfigurasikan klien layanan

Untuk menyesuaikan konfigurasi klien layanan, gunakan setter pada metode builder() pabrik. Untuk kenyamanan dan untuk membuat kode yang lebih mudah dibaca, rantai metode untuk mengatur beberapa opsi konfigurasi.

Contoh berikut menunjukkan S3Client yang dikonfigurasi dengan beberapa pengaturan kustom.

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

Tutup klien layanan

Sebagai praktik terbaik, Anda harus menggunakan klien layanan untuk beberapa panggilan layanan API selama masa pakai aplikasi. Namun, jika Anda membutuhkan klien layanan untuk penggunaan satu kali atau tidak lagi membutuhkan klien layanan, tutuplah.

Panggil close() metode ketika klien layanan tidak lagi diperlukan untuk membebaskan sumber daya.

ec2Client.close();

Jika Anda memerlukan klien layanan untuk penggunaan satu kali, Anda dapat membuat instance klien layanan sebagai sumber daya dalam pernyataan -with-resources. try Klien layanan mengimplementasikan Autoclosable antarmuka, sehingga JDK secara otomatis memanggil close() metode di akhir pernyataan.

Contoh berikut menunjukkan cara menggunakan klien layanan untuk panggilan satu kali. StsClientYang memanggil AWS Security Token Service ditutup setelah mengembalikan ID akun.

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

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

Membuat permintaan

Gunakan klien layanan untuk membuat permintaan ke yang sesuai Layanan AWS.

Misalnya, cuplikan kode ini menunjukkan cara membuat RunInstancesRequest objek untuk membuat instance Amazon EC2 baru:

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

Alih-alih membuat permintaan dan meneruskan instance, SDK menyediakan API lancar yang dapat Anda gunakan untuk membuat permintaan. Dengan API yang lancar, Anda dapat menggunakan ekspresi lambda Java untuk membuat permintaan 'in-line'.

Contoh berikut menulis ulang contoh sebelumnya dengan menggunakan versi runInstances metode yang menggunakan pembangun untuk membuat permintaan.

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

Gunakan permintaan untuk mengganti konfigurasi klien

Meskipun klien layanan tidak dapat diubah, Anda dapat mengganti banyak pengaturannya di tingkat permintaan. Saat membuat permintaan, Anda dapat memberikan AwsRequestOverrideConfigurationinstance untuk menyediakan pengaturan yang diganti. Beberapa metode yang dapat Anda gunakan untuk mengganti pengaturan klien adalah:

Untuk contoh penggantian pengaturan klien dengan permintaan, asumsikan bahwa Anda memiliki klien S3 berikut yang menggunakan pengaturan default.

S3Client s3Client = S3Client.create();

Anda ingin mengunduh file besar dan ingin memastikan permintaan tidak batas waktu sebelum unduhan selesai. Untuk mencapai hal ini, tingkatkan nilai batas waktu hanya untuk satu GetObject permintaan seperti yang ditunjukkan dalam kode berikut.

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

Menangani tanggapan

SDK mengembalikan objek respons untuk sebagian besar operasi layanan. Kode Anda dapat memproses informasi dalam objek respons sesuai dengan kebutuhan Anda.

Misalnya, cuplikan kode berikut mencetak id contoh pertama yang dikembalikan dengan RunInstancesResponseobjek dari permintaan sebelumnya.

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

Namun, tidak semua operasi mengembalikan objek respons dengan data khusus layanan. Dalam situasi ini, Anda dapat menanyakan status respons HTTP untuk mengetahui apakah operasi berhasil.

Misalnya, kode dalam cuplikan berikut memeriksa respons HTTP untuk melihat apakah DeleteContactListpengoperasian Amazon Simple Email Service berhasil.

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

Menangani pengecualian

SDK menggunakan pengecualian runtime (atau tidak dicentang), memberi Anda kontrol halus atas penanganan kesalahan dan memastikan bahwa penanganan pengecualian akan diskalakan dengan aplikasi Anda.

An SdkServiceException, atau salah satu sub-kelasnya, adalah bentuk pengecualian yang paling umum yang akan dilemparkan SDK. Pengecualian ini mewakili tanggapan dari AWS layanan. Anda juga dapat menangani SdkClientException, yang terjadi ketika ada masalah di sisi klien (yaitu, dalam pengembangan atau lingkungan aplikasi Anda), seperti kegagalan koneksi jaringan.

Cuplikan kode ini menunjukkan salah satu cara untuk menangani pengecualian layanan saat Anda mengunggah file ke. Amazon S3 Kode contoh menangkap pengecualian klien dan server, mencatat detailnya, dan ada aplikasi.

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

Lihat Menangani pengecualian untuk informasi selengkapnya.

Gunakan pelayan

Beberapa permintaan membutuhkan waktu untuk diproses, seperti membuat tabel baru DynamoDB atau membuat Amazon S3 bucket baru. Untuk memastikan sumber daya siap sebelum kode Anda terus berjalan, gunakan Pelayan.

Misalnya, cuplikan kode ini membuat tabel baru (“myTable”) di DynamoDB, menunggu tabel berada dalam ACTIVE status, dan kemudian mencetak respons:

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

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

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

Lihat Menggunakan pelayan untuk informasi lebih lanjut.

Tetapkan batas waktu

Anda dapat mengonfigurasi batas waktu untuk setiap klien layanan Anda menggunakan apiCallTimeoutdan apiCallAttemptTimeoutpenyetel. ClientOverrideConfiguration.Builder apiCallTimeoutPengaturan adalah jumlah waktu untuk memungkinkan klien menyelesaikan eksekusi panggilan API. apiCallAttemptTimeoutPengaturan adalah jumlah waktu untuk menunggu setiap permintaan HTTP (coba lagi) selesai sebelum menyerah.

Contoh berikut menetapkan kedua batas waktu untuk klien S3.

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

Anda juga dapat mengatur batas waktu pada tingkat permintaan dengan mengonfigurasi AwsRequestOverrideConfigurationdan menyediakannya ke objek permintaan dengan metode. overrideConfiguration

Contoh berikut menggunakan pengaturan batas waktu yang sama tetapi pada tingkat permintaan untuk operasi S3PutObject.

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

Pencegat eksekusi

Anda dapat menulis kode yang mencegat eksekusi permintaan dan tanggapan API Anda di berbagai bagian siklus hidup permintaan/respons. Ini memungkinkan Anda untuk mempublikasikan metrik, memodifikasi permintaan dalam penerbangan, men-debug pemrosesan permintaan, melihat pengecualian, dan banyak lagi. Untuk informasi selengkapnya, lihat ExecutionInterceptorantarmuka di Referensi AWS SDK untuk Java API.