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 EC2, dan banyak lagi.

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

catatan

Klien layanan di SDK aman untuk utas. Untuk kinerja terbaik, perlakukan mereka sebagai benda berumur panjang. Setiap klien memiliki sumber daya kolam koneksi sendiri yang dilepaskan saat klien mengumpulkan sampah.

Objek klien layanan tidak dapat diubah, jadi Anda harus membuat klien baru untuk setiap layanan yang Anda minta, atau jika Anda ingin menggunakan konfigurasi yang berbeda untuk membuat permintaan ke layanan yang sama.

Menentukan Region dalam pembuat klien layanan tidak diperlukan untuk semua AWS layanan; namun, ini adalah praktik terbaik untuk mengatur Wilayah untuk panggilan API yang Anda buat dalam aplikasi Anda. Lihat pemilihan AWS wilayah untuk informasi lebih lanjut.

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

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 builder yang dapat Anda gunakan untuk membuat permintaan. Dengan pembangun Anda dapat menggunakan ekspresi lambda Java untuk membuat permintaan 'in-baris'.

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

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

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

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.

Klien HTTP

Anda dapat mengubah konfigurasi default untuk klien HTTP dalam aplikasi yang Anda buat dengan AWS SDK for Java. Untuk informasi tentang cara mengkonfigurasi klien dan pengaturan HTTP, lihat konfigurasi HTTP.

Timeout

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

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 for Java API.

Informasi tambahan

• Untuk contoh lengkap cuplikan kode di atas, lihat Bekerja dengan Amazon DynamoDB, Bekerja dengan Amazon EC2, dan Bekerja dengan. Amazon S3