Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Pemrograman DynamoDB dengan AWS SDK for Java 2.x Panduan pemrograman ini memberikan orientasi bagi programmer yang ingin menggunakan Amazon DynamoDB dengan Java. Panduan ini mencakup berbagai konsep termasuk lapisan abstraksi, manajemen konfigurasi, penanganan kesalahan, mengendalikan kebijakan coba ulang, dan mengelola keep-alive. **Topics** + [Tentang AWS SDK for Java 2.x](#AboutProgrammingWithJavaSDK) + [Memulai](#GetStartedProgrammingWithJavaSDK) + [SDK untuk dokumentasi Java 2.x](#ProgrammingWithJavaUseDoc) + [Antarmuka yang didukung](#JavaInterfaces) + [Contoh kode tambahan](#AdditionalCodeEx) + [Sinkronisasi dan pemrograman asinkron](#SyncAsyncProgramming) + [Klien HTTP](#HttpClients) + [Config](#ConfigHttpClient) + [Penanganan kesalahan](#JavaErrorHandling) + [AWS ID permintaan](#JavaRequestID) + [Pencatatan log](#JavaLogging) + [Paginasi](#JavaPagination) + [Anotasi kelas data](#JavaDataClassAnnotation) + [Praktik terbaik](#JavaBestPractices) ## Tentang AWS SDK for Java 2.x Anda dapat mengakses DynamoDB dari Java menggunakan resmi. AWS SDK untuk Java SDK untuk Java memiliki dua versi: 1.x dan 2.x. Dukungan untuk 1.x berakhir pada 31 Desember 2025. Untuk informasi selengkapnya, [ lihat Mengumumkan akhir dukungan untuk AWS SDK untuk Java v1.x ](https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-aws-sdk-for-java-v1-x-on-december-31-2025/) di Blog AWS Alat Pengembang. Untuk pengembangan baru, kami sangat menyarankan Anda menggunakan 2.x, yang pertama kali dirilis pada tahun 2018. Panduan ini secara eksklusif menargetkan 2.x dan hanya berfokus pada bagian-bagian SDK yang relevan dengan DynamoDB. Untuk informasi tentang pemeliharaan dan dukungan untuk AWS SDK, lihat kebijakan [ pemeliharaan ](https://docs.aws.amazon.com/sdkref/latest/guide/maint-policy.html)AWS SDK dan Alat serta matri [AWS ks dukungan versi SDK dan Alat ](https://docs.aws.amazon.com/sdkref/latest/guide/version-support-matrix.html) di Panduan Referensi *AWS SDK dan Alat. * Ini AWS SDK for Java 2.x adalah penulisan ulang utama dari basis kode 1.x. SDK untuk Java 2.x mendukung fitur Java modern, seperti non-blocker yang I/O diperkenalkan di Java 8. SDK untuk Java 2.x juga menambahkan dukungan untuk implementasi klien HTTP yang dapat dicolokkan untuk memberikan lebih banyak fleksibilitas koneksi jaringan dan opsi konfigurasi. Perubahan nyata antara SDK untuk Java 1.x dan SDK untuk Java 2.x adalah penggunaan nama paket baru. Java 1.x SDK menggunakan nama `com.amazonaws` paket, sedangkan Java 2.x SDK menggunakan. `software.amazon.awssdk` Demikian pula, artefak Maven untuk Java 1.x SDK menggunakan `com.amazonaws``groupId`, sedangkan artefak Java 2.x SDK menggunakan. `software.amazon.awssdk` `groupId` **penting** AWS SDK untuk Java 1.x memiliki paket DynamoDB bernama. `com.amazonaws.dynamodbv2` “V2" dalam nama paket tidak menunjukkan bahwa itu untuk Java 2 (J2SE). Sebaliknya, “v2" menunjukkan bahwa paket mendukung versi [ kedua ](CurrentAPI.md) dari DynamoDB level rendah API alih-alih versi [Versi API DynamoDB tingkat rendah sebelumnya (2011-12-05)](Appendix.APIv20111205.md) asli dari API tingkat rendah. ### Dukungan untuk versi Java Ini AWS SDK for Java 2.x memberikan dukungan penuh untuk dukungan jangka panjang (LTS) rilis [https://github.com/aws/aws-sdk-java-v2?tab=readme-ov-file#maintenance-and-support-for-java-versions](https://github.com/aws/aws-sdk-java-v2?tab=readme-ov-file#maintenance-and-support-for-java-versions) Java. ## Memulai dengan AWS SDK for Java 2.x Tutorial berikut menunjukkan cara menggunakan [ Apache Maven ](https://maven.apache.org/) untuk menentukan dependensi untuk SDK untuk Java 2.x. Tutorial ini juga menunjukkan cara menulis kode yang terhubung ke DynamoDB untuk mencantumkan tabel DynamoDB yang tersedia. Tutorial dalam panduan ini didasarkan pada tutorial [ Memulai dengan AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html) di Panduan Peng *AWS SDK for Java 2.x embang*. Kami telah mengedit tutorial ini untuk melakukan panggilan ke DynamoDB alih-alih Amazon S3. **Topics** + [Langkah 1: Siapkan untuk tutorial ini](#GetStartedJavaSetup) + [Langkah 2: Buat proyek](#GetStartedJavaProjectSetup) + [Langkah 3: Tulis kode](#GetStartedJavaCode) + [Langkah 4: Membangun dan menjalankan aplikasi](#GetStartedRunJava) ### Langkah 1: Siapkan untuk tutorial ini Sebelum Anda memulai tutorial ini, Anda memerlukan yang berikut: + Izin untuk mengakses DynamoDB. + Lingkungan pengembangan Java yang dikonfigurasi dengan akses masuk tunggal untuk Layanan AWS menggunakan. Portal akses AWS Untuk menyiapkan tutorial ini, ikuti petunjuk dalam ikhtisar Peng [ aturan ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup.html#setup-overview) di Panduan Peng *AWS SDK for Java 2.x embang*. Setelah Anda [ mengonfigurasi lingkungan pengembangan Anda dengan akses masuk tunggal ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup.html#setup-credentials) untuk Java SDK dan Anda memiliki sesi portal AWS akses [ aktif](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup.html#setup-login-sso), lanjutkan ke [ Langkah 2 ](#GetStartedJavaProjectSetup) dari tutorial ini. ### Langkah 2: Buat proyek Untuk membuat proyek untuk tutorial ini, Anda menjalankan perintah Maven yang meminta Anda untuk masukan tentang cara mengkonfigurasi proyek. Setelah semua input dimasukkan dan dikonfirmasi, Maven selesai membangun proyek dengan membuat `pom.xml` file dan membuat file Java stub. 1. Buka jendela terminal atau command prompt dan arahkan ke direktori pilihan Anda, misalnya `Home` folder `Desktop` atau Anda. 1. Masukkan perintah berikut di terminal, lalu tekan ** Enter**. ``` mvn archetype:generate \ -DarchetypeGroupId=software.amazon.awssdk \ -DarchetypeArtifactId=archetype-app-quickstart \ -DarchetypeVersion=2.22.0 ``` 1. Untuk setiap prompt, masukkan nilai yang tercantum di kolom kedua. [See the AWS documentation website for more details](http://docs.aws.amazon.com/id_id/amazondynamodb/latest/developerguide/ProgrammingWithJava.html) 1. Setelah Anda memasukkan nilai terakhir, Maven mencantumkan pilihan yang Anda buat. Untuk mengonfirmasi, masukkan ** Y**. Atau, masukkan ** N**, lalu masukkan kembali pilihan Anda. Maven membuat folder proyek bernama `getstarted` berdasarkan `artifactId` nilai yang Anda masukkan. Di dalam `getstarted` folder, temukan file bernama `README.md` yang dapat Anda tinjau, `pom.xml` file, dan `src` direktori. Maven membangun pohon direktori berikut. ``` getstarted ├── README.md ├── pom.xml └── src ├── main │ ├── java │ │ └── org │ │ └── example │ │ ├── App.java │ │ ├── DependencyFactory.java │ │ └── Handler.java │ └── resources │ └── simplelogger.properties └── test └── java └── org └── example └── HandlerTest.java 10 directories, 7 files ``` Berikut ini menunjukkan isi file `pom.xml` proyek. #### `pom.xml` `dependencyManagement`Bagian berisi ketergantungan ke AWS SDK for Java 2.x, dan `dependencies` bagian tersebut memiliki ketergantungan untuk DynamoDB. Menentukan dependensi ini memaksa Maven untuk menyertakan `.jar` file yang relevan di jalur kelas Java Anda. Secara default, AWS SDK tidak menyertakan semua kelas untuk semua Layanan AWS. Untuk DynamoDB, jika Anda menggunakan antarmuka tingkat rendah, maka Anda harus memiliki ketergantungan pada artefak. `dynamodb` Atau, jika Anda menggunakan antarmuka tingkat tinggi, pada `dynamodb-enhanced` artefak. Jika Anda tidak menyertakan dependensi yang relevan, maka kode Anda tidak dapat dikompilasi. Proyek ini menggunakan Java 1.8 karena `1.8` nilai dalam `maven.compiler.target` properti `maven.compiler.source` dan. ``` 4.0.0 org.example getstarted 1.0-SNAPSHOT jar UTF-8 1.8 1.8 3.2.1 3.6.1 1.6.0 2.22.0{{ <-------- SDK version picked up from archetype version}}. 1.7.28 5.8.1 software.amazon.awssdk bom ${aws.java.sdk.version} pom import software.amazon.awssdk dynamodb {{ <-------- DynamoDB dependency}} software.amazon.awssdk netty-nio-client software.amazon.awssdk apache-client software.amazon.awssdk sso{{ <-------- Required for identity center authentication.}} software.amazon.awssdk ssooidc{{ <-------- Required for identity center authentication.}} software.amazon.awssdk apache-client{{ <-------- HTTP client specified.}} commons-logging commons-logging org.slf4j slf4j-api ${slf4j.version} org.slf4j slf4j-simple ${slf4j.version} org.slf4j jcl-over-slf4j ${slf4j.version} org.junit.jupiter junit-jupiter ${junit5.version} test org.apache.maven.plugins maven-compiler-plugin ${maven.compiler.plugin.version} ``` ### Langkah 3: Tulis kode Kode berikut menunjukkan `App` kelas yang dibuat Maven. `main`Metode ini adalah titik masuk ke dalam aplikasi, yang membuat instance `Handler` kelas dan kemudian memanggil `sendRequest` metodenya. #### ``Kelas aplikasi ``` package org.example; import org.slf4j.Logger; import org.slf4j.LoggerFactory; public class App { private static final Logger logger = LoggerFactory.getLogger(App.class); public static void main(String... args) { logger.info("Application starts"); Handler handler = new Handler(); handler.sendRequest(); logger.info("Application ends"); } } ``` Kel `DependencyFactory` as yang dibuat Maven berisi metode `dynamoDbClient` pabrik yang membangun dan mengembalikan [`DynamoDbClient`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/DynamoDbClient.html) instance. `DynamoDbClient`Instance menggunakan instance klien Apache-based HTTP. Ini karena Anda menentukan `apache-client` kapan Maven meminta klien HTTP mana yang akan digunakan. Kode berikut menunjukkan `DependencyFactory` kelas. #### DependencyFactory kelas ``` package org.example; import software.amazon.awssdk.http.apache.ApacheHttpClient; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; /** * The module containing all dependencies required by the {@link Handler}. */ public class DependencyFactory { private DependencyFactory() {} /** * @return an instance of DynamoDbClient */ public static DynamoDbClient dynamoDbClient() { return DynamoDbClient.builder() .httpClientBuilder(ApacheHttpClient.builder()) .build(); } } ``` `Handler`Kelas berisi logika utama program Anda. Ketika instance `Handler` dibuat di `App` kelas, itu `DependencyFactory` menyediakan klien `DynamoDbClient` layanan. Kode Anda menggunakan `DynamoDbClient` instance untuk memanggil DynamoDB. Maven menghasilkan `Handler` kelas berikut dengan `TODO` komentar. Langkah selanjutnya dalam tutorial menggantikan * `TODO` * komentar dengan kode. #### ``Kelas Handler, Maven-generated ``` package org.example; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; public class Handler { private final DynamoDbClient dynamoDbClient; public Handler() { dynamoDbClient = DependencyFactory.dynamoDbClient(); } public void sendRequest() { // TODO: invoking the API calls using dynamoDbClient. } } ``` Untuk mengisi logika, ganti seluruh isi `Handler` kelas dengan kode berikut. `sendRequest`Metode ini diisi dan impor yang diperlukan ditambahkan. #### ``Kelas Handler, diimplementasikan Kode berikut menggunakan [`DynamoDbClient`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/DynamoDbClient.html) instance untuk mengambil daftar tabel yang ada. Jika tabel ada untuk akun tertentu dan Wilayah AWS, maka kode menggunakan `Logger` instance untuk mencatat nama-nama tabel ini. ``` package org.example; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import software.amazon.awssdk.services.dynamodb.model.ListTablesResponse; public class Handler { private final DynamoDbClient dynamoDbClient; public Handler() { dynamoDbClient = DependencyFactory.dynamoDbClient(); } public void sendRequest() { Logger logger = LoggerFactory.getLogger(Handler.class); logger.info("calling the DynamoDB API to get a list of existing tables"); ListTablesResponse response = dynamoDbClient.listTables(); if (!response.hasTableNames()) { logger.info("No existing tables found for the configured account & region"); } else { response.tableNames().forEach(tableName -> logger.info("Table: " + tableName)); } } } ``` ### Langkah 4: Membangun dan menjalankan aplikasi Setelah Anda membuat proyek dan berisi `Handler` kelas lengkap, buat dan jalankan aplikasi. 1. Pastikan Anda memiliki AWS IAM Identity Center sesi aktif. Untuk mengonfirmasi, jalankan perintah AWS Command Line Interface (AWS CLI) `aws sts get-caller-identity` dan periksa responsnya. Jika Anda tidak memiliki sesi aktif, lihat [ Masuk menggunakan AWS CLI](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup.html#setup-login-sso) petunjuk. 1. Buka terminal atau jendela command prompt dan navigasikan ke direktori proyek Anda`getstarted`. 1. Untuk membangun proyek Anda, jalankan perintah berikut: ``` mvn clean package ``` 1. Untuk menjalankan aplikasi, jalankan perintah berikut: ``` mvn exec:java -Dexec.mainClass="org.example.App" ``` #### Berhasil Jika proyek Maven Anda dibangun dan berjalan tanpa kesalahan, maka selamat\! Anda telah berhasil membangun aplikasi Java pertama Anda menggunakan SDK untuk Java 2.x. #### Pembersihan Untuk membersihkan sumber daya yang Anda buat selama tutorial ini, hapus folder proyek`getstarted`. ## Meninjau AWS SDK for Java 2.x dokumentasi Panduan Peng [AWS SDK for Java 2.x embang ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/home.html) mencakup semua aspek SDK di semua Layanan AWS. Kami menyarankan Anda meninjau topik-topik berikut: + [Bermigrasi dari versi 1.x ke 2.x ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration.html) - Termasuk penjelasan rinci tentang perbedaan antara 1.x dan 2.x. Topik ini juga berisi petunjuk tentang cara menggunakan kedua versi utama secara berdampingan. + [Panduan DynamoDB untuk Java 2.x SDK ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/examples-dynamodb.html) - Menunjukkan cara melakukan operasi DynamoDB dasar: membuat tabel, memanipulasi item, dan mengambil item. Contoh-contoh ini menggunakan antarmuka tingkat rendah. Java memiliki beberapa antarmuka, seperti yang dijelaskan di bagian berikut:[Antarmuka yang didukung](#JavaInterfaces). **Tip** Setelah Anda meninjau topik ini, tandai Refer [AWS SDK for Java 2.x ensi API](https://sdk.amazonaws.com/java/api/latest/). Ini mencakup semua Layanan AWS, dan kami sarankan Anda menggunakannya sebagai referensi API utama Anda. ## Antarmuka yang didukung Men AWS SDK for Java 2.x dukung antarmuka berikut, tergantung pada tingkat abstraksi yang Anda inginkan. **Topics** + [Low-level antarmuka](#LowLevelInterface) + [High-level antarmuka](#HighLevelInterface) + [Antarmuka dokumen](#DocumentInterface) + [Membandingkan antarmuka dengan `contoh` Query](#CompareJavaInterfacesQueryEx) ### Low-level antarmuka Antarmuka tingkat rendah menyediakan pemetaan satu-ke-satu ke API layanan yang mendasarinya. Setiap DynamoDB API tersedia melalui antarmuka ini. Ini berarti bahwa antarmuka tingkat rendah dapat memberikan fungsionalitas lengkap, tetapi seringkali lebih bertele-tele dan kompleks untuk digunakan. Misalnya, Anda harus menggunakan `.s()` fungsi untuk menahan string dan `.n()` fungsi untuk menahan angka. Contoh berikut menyisi [ PutItem ](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html) pkan item menggunakan antarmuka tingkat rendah. ``` import org.slf4j.*; import software.amazon.awssdk.http.crt.AwsCrtHttpClient; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import software.amazon.awssdk.services.dynamodb.model.*; import java.util.Map; public class PutItem { // Create a DynamoDB client with the default settings connected to the DynamoDB // endpoint in the default region based on the default credentials provider chain. private static final DynamoDbClient DYNAMODB_CLIENT = DynamoDbClient.create(); private static final Logger LOGGER = LoggerFactory.getLogger(PutItem.class); private void putItem() { PutItemResponse response = DYNAMODB_CLIENT.putItem(PutItemRequest.builder() .item(Map.of( "pk", AttributeValue.builder().s("123").build(), "sk", AttributeValue.builder().s("cart#123").build(), "item_data", AttributeValue.builder().s("YourItemData").build(), "inventory", AttributeValue.builder().n("500").build() // ... more attributes ... )) .returnConsumedCapacity(ReturnConsumedCapacity.TOTAL) .tableName("YourTableName") .build()); LOGGER.info("PutItem call consumed [" + response.consumedCapacity().capacityUnits() + "] Write Capacity Unites (WCU)"); } } ``` ### High-level antarmuka Antarmuka tingkat tinggi di AWS SDK for Java 2.x disebut klien yang ditingkatkan DynamoDB. Antarmuka ini memberikan pengalaman penulisan kode yang lebih idiomatis. Klien yang disempurnakan menawarkan cara untuk memetakan antara kelas data sisi klien dan tabel DynamoDB yang dirancang untuk menyimpan data itu. Anda menentukan hubungan antara tabel dan kelas model yang sesuai dalam kode Anda. Kemudian, Anda dapat mengandalkan SDK untuk mengelola manipulasi tipe data. Untuk informasi selengkapnya tentang klien yang disempurnakan, lihat API klien [ yang disempurnakan DynamoDB ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/dynamodb-enhanced-client.html) di Panduan Peng *AWS SDK for Java 2.x embang. * Contoh berikut [ PutItem ](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html) menggunakan antarmuka tingkat tinggi. Dalam contoh ini, `DynamoDbBean` nama membuat `YourItem` a `TableSchema` yang memungkinkan penggunaan langsungnya sebagai input untuk `putItem()` panggilan. ``` import org.slf4j.*; import software.amazon.awssdk.enhanced.dynamodb.*; import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.*; import software.amazon.awssdk.enhanced.dynamodb.model.*; import software.amazon.awssdk.services.dynamodb.model.ReturnConsumedCapacity; public class DynamoDbEnhancedClientPutItem { private static final DynamoDbEnhancedClient ENHANCED_DYNAMODB_CLIENT = DynamoDbEnhancedClient.builder().build(); private static final DynamoDbTable DYNAMODB_TABLE = ENHANCED_DYNAMODB_CLIENT.table("YourTableName", TableSchema.fromBean(YourItem.class)); private static final Logger LOGGER = LoggerFactory.getLogger(DynamoDbEnhancedClientPutItem.class); private void putItem() { PutItemEnhancedResponse response = DYNAMODB_TABLE.putItemWithResponse(PutItemEnhancedRequest.builder(YourItem.class) .item(new YourItem("123", "cart#123", "YourItemData", 500)) .returnConsumedCapacity(ReturnConsumedCapacity.TOTAL) .build()); LOGGER.info("PutItem call consumed [" + response.consumedCapacity().capacityUnits() + "] Write Capacity Unites (WCU)"); } @DynamoDbBean public static class YourItem { public YourItem() {} public YourItem(String pk, String sk, String itemData, int inventory) { this.pk = pk; this.sk = sk; this.itemData = itemData; this.inventory = inventory; } private String pk; private String sk; private String itemData; private int inventory; @DynamoDbPartitionKey public void setPk(String pk) { this.pk = pk; } public String getPk() { return pk; } @DynamoDbSortKey public void setSk(String sk) { this.sk = sk; } public String getSk() { return sk; } public void setItemData(String itemData) { this.itemData = itemData; } public String getItemData() { return itemData; } public void setInventory(int inventory) { this.inventory = inventory; } public int getInventory() { return inventory; } } } ``` AWS SDK untuk Java 1.x memiliki antarmuka tingkat tinggi sendiri, yang sering disebut oleh kelas `DynamoDBMapper` utamanya. AWS SDK for Java 2.x Ini diterbitkan dalam paket terpisah (dan artefak Maven) bernama`software.amazon.awssdk.enhanced.dynamodb`. Java 2.x SDK sering disebut oleh kelas `DynamoDbEnhancedClient` utamanya. #### High-level antarmuka menggunakan kelas data yang tidak dapat diubah Fitur pemetaan API klien yang ditingkatkan DynamoDB juga berfungsi dengan kelas data yang tidak dapat diubah. Kelas yang tidak dapat diubah hanya memiliki getter dan memerlukan kelas builder yang digunakan SDK untuk membuat instance kelas. Kekekalan di Java adalah gaya yang umum digunakan pengembang untuk membuat kelas yang tidak memiliki efek samping. Kelas ini lebih dapat diprediksi dalam perilakunya dalam aplikasi multi-utas yang kompleks. Alih-alih menggunakan an `@DynamoDbBean` otasi seperti yang ditunjukkan pada[High-level interface example](#highleveleg), kelas yang tidak dapat diubah menggunakan an `@DynamoDbImmutable` otasi, yang mengambil kelas builder sebagai inputnya. Contoh berikut mengambil kelas builder `DynamoDbEnhancedClientImmutablePutItem` sebagai input untuk membuat skema tabel. Contoh kemudian menyediakan skema sebagai input untuk panggilan [ PutItem ](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html) API. ``` import org.slf4j.*; import software.amazon.awssdk.enhanced.dynamodb.*; import software.amazon.awssdk.enhanced.dynamodb.model.*; import software.amazon.awssdk.services.dynamodb.model.ReturnConsumedCapacity; public class DynamoDbEnhancedClientImmutablePutItem { private static final DynamoDbEnhancedClient ENHANCED_DYNAMODB_CLIENT = DynamoDbEnhancedClient.builder().build(); private static final DynamoDbTable DYNAMODB_TABLE = ENHANCED_DYNAMODB_CLIENT.table("YourTableName", TableSchema.fromImmutableClass(YourImmutableItem.class)); private static final Logger LOGGER = LoggerFactory.getLogger(DynamoDbEnhancedClientImmutablePutItem.class); private void putItem() { PutItemEnhancedResponse response = DYNAMODB_TABLE.putItemWithResponse(PutItemEnhancedRequest.builder(YourImmutableItem.class) .item(YourImmutableItem.builder() .pk("123") .sk("cart#123") .itemData("YourItemData") .inventory(500) .build()) .returnConsumedCapacity(ReturnConsumedCapacity.TOTAL) .build()); LOGGER.info("PutItem call consumed [" + response.consumedCapacity().capacityUnits() + "] Write Capacity Unites (WCU)"); } } ``` Contoh berikut menunjukkan kelas data yang tidak dapat diubah. ``` @DynamoDbImmutable(builder = YourImmutableItem.YourImmutableItemBuilder.class) class YourImmutableItem { private final String pk; private final String sk; private final String itemData; private final int inventory; public YourImmutableItem(YourImmutableItemBuilder builder) { this.pk = builder.pk; this.sk = builder.sk; this.itemData = builder.itemData; this.inventory = builder.inventory; } public static YourImmutableItemBuilder builder() { return new YourImmutableItemBuilder(); } @DynamoDbPartitionKey public String getPk() { return pk; } @DynamoDbSortKey public String getSk() { return sk; } public String getItemData() { return itemData; } public int getInventory() { return inventory; } static final class YourImmutableItemBuilder { private String pk; private String sk; private String itemData; private int inventory; private YourImmutableItemBuilder() {} public YourImmutableItemBuilder pk(String pk) { this.pk = pk; return this; } public YourImmutableItemBuilder sk(String sk) { this.sk = sk; return this; } public YourImmutableItemBuilder itemData(String itemData) { this.itemData = itemData; return this; } public YourImmutableItemBuilder inventory(int inventory) { this.inventory = inventory; return this; } public YourImmutableItem build() { return new YourImmutableItem(this); } } } ``` #### High-level antarmuka menggunakan kelas data yang tidak dapat diubah dan pustaka pembuatan boilerplate pihak ketiga Kelas data yang tidak dapat diubah (ditunjukkan pada contoh sebelumnya) memerlukan beberapa kode boilerplate. Misalnya, logika getter dan setter pada kelas data, selain `Builder` kelas. Third-party library, seperti [ Project Lombok](https://projectlombok.org/), dapat membantu Anda menghasilkan jenis kode boilerplate tersebut. Mengurangi sebagian besar kode boilerplate membantu Anda membatasi jumlah kode yang diperlukan untuk bekerja dengan kelas data yang tidak dapat diubah dan SDK. AWS Ini lebih lanjut menghasilkan peningkatan produktivitas dan keterbacaan kode Anda. Untuk informasi selengkapnya, lihat [ Menggunakan pustaka pihak ketiga, seperti Lombok ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-use-immut.html#ddb-en-client-use-immut-lombok) di Panduan * Peng *AWS SDK for Java 2.x embang. Contoh berikut menunjukkan bagaimana Project Lombok menyederhanakan kode yang diperlukan untuk menggunakan API klien yang ditingkatkan DynamoDB. ``` import org.slf4j.*; import software.amazon.awssdk.enhanced.dynamodb.*; import software.amazon.awssdk.enhanced.dynamodb.model.*; import software.amazon.awssdk.services.dynamodb.model.ReturnConsumedCapacity; public class DynamoDbEnhancedClientImmutableLombokPutItem { private static final DynamoDbEnhancedClient ENHANCED_DYNAMODB_CLIENT = DynamoDbEnhancedClient.builder().build(); private static final DynamoDbTable DYNAMODB_TABLE = ENHANCED_DYNAMODB_CLIENT.table("YourTableName", TableSchema.fromImmutableClass(YourImmutableLombokItem.class)); private static final Logger LOGGER = LoggerFactory.getLogger(DynamoDbEnhancedClientImmutableLombokPutItem.class); private void putItem() { PutItemEnhancedResponse response = DYNAMODB_TABLE.putItemWithResponse(PutItemEnhancedRequest.builder(YourImmutableLombokItem.class) .item(YourImmutableLombokItem.builder() .pk("123") .sk("cart#123") .itemData("YourItemData") .inventory(500) .build()) .returnConsumedCapacity(ReturnConsumedCapacity.TOTAL) .build()); LOGGER.info("PutItem call consumed [" + response.consumedCapacity().capacityUnits() + "] Write Capacity Unites (WCU)"); } } ``` Contoh berikut menunjukkan objek data yang tidak dapat diubah dari kelas data yang tidak dapat diubah. ``` import lombok.*; import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.*; @Builder @DynamoDbImmutable(builder = YourImmutableLombokItem.YourImmutableLombokItemBuilder.class) @Value public class YourImmutableLombokItem { @Getter(onMethod_=@DynamoDbPartitionKey) String pk; @Getter(onMethod_=@DynamoDbSortKey) String sk; String itemData; int inventory; } ``` Kel `YourImmutableLombokItem` as menggunakan anotasi berikut yang disediakan Project Lombok dan AWS SDK: + [@Builder ](https://projectlombok.org/features/Builder) — Menghasilkan API pembangun kompleks untuk kelas data yang disediakan Project Lombok. + [@ DynamoDbImmutable ](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/mapper/annotations/DynamoDbImmutable.html) — Mengidentifikasi `DynamoDbImmutable` kelas sebagai anotasi entitas yang dapat dipetakan DynamoDB yang disediakan SDK. AWS + [@Value ](https://projectlombok.org/features/Value) — Varian yang tidak dapat diubah dari. `@Data` Secara default, semua bidang dibuat pribadi dan final, dan setter tidak dihasilkan. Proyek Lombok memberikan anotasi ini. ### Antarmuka dokumen Antar AWS SDK for Java 2.x muka Dokumen menghindari kebutuhan untuk menentukan deskriptor tipe data. Jenis data yang tersirat oleh semantik data itu sendiri. Antarmuka Dokumen ini mirip dengan antarmuka AWS SDK untuk Java Dokumen 1.x, tetapi dengan antarmuka yang didesain ulang. Berikut ini [Document interface example](#DocInterfaceEg) menunjukkan `PutItem` panggilan yang diekspresikan menggunakan antarmuka Dokumen. Contohnya juga menggunakan EnhancedDocument. Untuk menjalankan perintah terhadap tabel DynamoDB menggunakan API dokumen yang disempurnakan, Anda harus terlebih dahulu mengaitkan tabel dengan skema tabel dokumen Anda untuk membuat objek `DynamoDBTable` sumber daya. Pembuat skema tabel dokumen memerlukan kunci indeks utama dan penyedia konverter atribut. Anda dapat menggunakan `AttributeConverterProvider.defaultProvider()` untuk mengonversi atribut dokumen dari tipe default. Anda dapat mengubah perilaku default secara keseluruhan dengan `AttributeConverterProvider` implementasi kustom. Anda juga dapat mengubah konverter untuk atribut tunggal. Panduan Refer [AWS ensi SDK dan Alat ](https://docs.aws.amazon.com/sdkref/latest/guide/version-support-matrix.html) memberikan detail dan contoh lebih lanjut tentang cara menggunakan konverter khusus. Penggunaan utamanya adalah untuk atribut kelas domain Anda yang tidak memiliki konverter default yang tersedia. Menggunakan konverter khusus, Anda dapat menyediakan SDK dengan informasi yang diperlukan untuk menulis atau membaca ke DynamoDB. ``` import org.slf4j.*; import software.amazon.awssdk.enhanced.dynamodb.*; import software.amazon.awssdk.enhanced.dynamodb.document.EnhancedDocument; import software.amazon.awssdk.enhanced.dynamodb.model.*; import software.amazon.awssdk.services.dynamodb.model.ReturnConsumedCapacity; public class DynamoDbEnhancedDocumentClientPutItem { private static final DynamoDbEnhancedClient ENHANCED_DYNAMODB_CLIENT = DynamoDbEnhancedClient.builder().build(); private static final DynamoDbTable DYNAMODB_TABLE = ENHANCED_DYNAMODB_CLIENT.table("YourTableName", TableSchema.documentSchemaBuilder() .addIndexPartitionKey(TableMetadata.primaryIndexName(),"pk", AttributeValueType.S) .addIndexSortKey(TableMetadata.primaryIndexName(), "sk", AttributeValueType.S) .attributeConverterProviders(AttributeConverterProvider.defaultProvider()) .build()); private static final Logger LOGGER = LoggerFactory.getLogger(DynamoDbEnhancedDocumentClientPutItem.class); private void putItem() { PutItemEnhancedResponse response = DYNAMODB_TABLE.putItemWithResponse( PutItemEnhancedRequest.builder(EnhancedDocument.class) .item( EnhancedDocument.builder() .attributeConverterProviders(AttributeConverterProvider.defaultProvider()) .putString("pk", "123") .putString("sk", "cart#123") .putString("item_data", "YourItemData") .putNumber("inventory", 500) .build()) .returnConsumedCapacity(ReturnConsumedCapacity.TOTAL) .build()); LOGGER.info("PutItem call consumed [" + response.consumedCapacity().capacityUnits() + "] Write Capacity Unites (WCU)"); } } ``` Untuk mengonversi dokumen JSON ke dan dari tipe data asli Amazon DynamoDB, Anda dapat menggunakan metode utilitas berikut: + [`EnhancedDocument.fromJson(String json)`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html#fromJson(java.lang.String))- Membuat EnhancedDocument instance baru dari string JSON. + [`EnhancedDocument.toJson()`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html#toJson())- Membuat representasi string JSON dari dokumen yang dapat Anda gunakan dalam aplikasi Anda seperti objek JSON lainnya. ### Membandingkan antarmuka dengan `contoh` Query Bagian ini menunjukkan [`Query`](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html) panggilan yang sama yang diekspresikan menggunakan berbagai antarmuka. Untuk menyempurnakan hasil kueri ini, perhatikan hal berikut: + DynamoDB menargetkan satu nilai kunci partisi tertentu, jadi Anda harus menentukan kunci partisi sepenuhnya. + Agar kueri hanya menargetkan item keranjang, kunci pengurutan memiliki ekspresi kondisi kunci yang digunakan`begins_with`. + `limit()`Metode ini membatasi kueri hingga maksimum 100 item yang dikembalikan. + Pengaturan `scanIndexForward` ke false mengembalikan hasil dalam urutan terbalik UTF-8 byte, yang biasanya berarti item keranjang dengan nomor terendah dikembalikan terlebih dahulu. Dengan menyet `scanIndexForward` el ke false, ini membalikkan pesanan dan item keranjang dengan nomor tertinggi dikembalikan terlebih dahulu. + Filter menghapus hasil yang tidak sesuai dengan kriteria. Data yang difilter menghabiskan kapasitas baca apakah item tersebut cocok dengan filter. **Example `Kueri` menggunakan antarmuka tingkat rendah** Contoh berikut menanyakan tabel bernama `YourTableName` menggunakan a`keyConditionExpression`. Ini membatasi kueri ke nilai kunci partisi tertentu dan mengurutkan nilai kunci yang dimulai dengan nilai awalan tertentu. Kondisi kunci ini membatasi jumlah data yang dibaca dari DynamoDB. Akhirnya, kueri menerapkan filter pada data yang diambil dari DynamoDB menggunakan a. `filterExpression` ``` import org.slf4j.*; import software.amazon.awssdk.services.dynamodb.DynamoDbClient; import software.amazon.awssdk.services.dynamodb.model.*; import java.util.Map; public class Query { // Create a DynamoDB client with the default settings connected to the DynamoDB // endpoint in the default region based on the default credentials provider chain. private static final DynamoDbClient DYNAMODB_CLIENT = DynamoDbClient.builder().build(); private static final Logger LOGGER = LoggerFactory.getLogger(Query.class); private static void query() { QueryResponse response = DYNAMODB_CLIENT.query(QueryRequest.builder() .expressionAttributeNames(Map.of("#name", "name")) .expressionAttributeValues(Map.of( ":pk_val", AttributeValue.fromS("id#1"), ":sk_val", AttributeValue.fromS("cart#"), ":name_val", AttributeValue.fromS("SomeName"))) .filterExpression("#name = :name_val") .keyConditionExpression("pk = :pk_val AND begins_with(sk, :sk_val)") .limit(100) .scanIndexForward(false) .tableName("YourTableName") .build()); LOGGER.info("nr of items: " + response.count()); LOGGER.info("First item pk: " + response.items().get(0).get("pk")); LOGGER.info("First item sk: " + response.items().get(0).get("sk")); } } ``` **Example `Kueri` menggunakan antarmuka Dokumen** Contoh berikut menanyakan tabel bernama `YourTableName` menggunakan antarmuka Dokumen. ``` import org.slf4j.Logger; import org.slf4j.LoggerFactory; import software.amazon.awssdk.enhanced.dynamodb.*; import software.amazon.awssdk.enhanced.dynamodb.document.EnhancedDocument; import software.amazon.awssdk.enhanced.dynamodb.model.*; import java.util.Map; public class DynamoDbEnhancedDocumentClientQuery { // Create a DynamoDB client with the default settings connected to the DynamoDB // endpoint in the default region based on the default credentials provider chain. private static final DynamoDbEnhancedClient ENHANCED_DYNAMODB_CLIENT = DynamoDbEnhancedClient.builder().build(); private static final DynamoDbTable DYNAMODB_TABLE = ENHANCED_DYNAMODB_CLIENT.table("YourTableName", TableSchema.documentSchemaBuilder() .addIndexPartitionKey(TableMetadata.primaryIndexName(),"pk", AttributeValueType.S) .addIndexSortKey(TableMetadata.primaryIndexName(), "sk", AttributeValueType.S) .attributeConverterProviders(AttributeConverterProvider.defaultProvider()) .build()); private static final Logger LOGGER = LoggerFactory.getLogger(DynamoDbEnhancedDocumentClientQuery.class); private void query() { PageIterable response = DYNAMODB_TABLE.query(QueryEnhancedRequest.builder() .filterExpression(Expression.builder() .expression("#name = :name_val") .expressionNames(Map.of("#name", "name")) .expressionValues(Map.of(":name_val", AttributeValue.fromS("SomeName"))) .build()) .limit(100) .queryConditional(QueryConditional.sortBeginsWith(Key.builder() .partitionValue("id#1") .sortValue("cart#") .build())) .scanIndexForward(false) .build()); LOGGER.info("nr of items: " + response.items().stream().count()); LOGGER.info("First item pk: " + response.items().iterator().next().getString("pk")); LOGGER.info("First item sk: " + response.items().iterator().next().getString("sk")); } } ``` **Example `Kueri` menggunakan antarmuka tingkat tinggi** Contoh berikut menanyakan tabel bernama `YourTableName` menggunakan API klien yang disempurnakan DynamoDB. ``` import org.slf4j.*; import software.amazon.awssdk.enhanced.dynamodb.*; import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.*; import software.amazon.awssdk.enhanced.dynamodb.model.*; import software.amazon.awssdk.services.dynamodb.model.AttributeValue; import java.util.Map; public class DynamoDbEnhancedClientQuery { private static final DynamoDbEnhancedClient ENHANCED_DYNAMODB_CLIENT = DynamoDbEnhancedClient.builder().build(); private static final DynamoDbTable DYNAMODB_TABLE = ENHANCED_DYNAMODB_CLIENT.table("YourTableName", TableSchema.fromBean(DynamoDbEnhancedClientQuery.YourItem.class)); private static final Logger LOGGER = LoggerFactory.getLogger(DynamoDbEnhancedClientQuery.class); private void query() { PageIterable response = DYNAMODB_TABLE.query(QueryEnhancedRequest.builder() .filterExpression(Expression.builder() .expression("#name = :name_val") .expressionNames(Map.of("#name", "name")) .expressionValues(Map.of(":name_val", AttributeValue.fromS("SomeName"))) .build()) .limit(100) .queryConditional(QueryConditional.sortBeginsWith(Key.builder() .partitionValue("id#1") .sortValue("cart#") .build())) .scanIndexForward(false) .build()); LOGGER.info("nr of items: " + response.items().stream().count()); LOGGER.info("First item pk: " + response.items().iterator().next().getPk()); LOGGER.info("First item sk: " + response.items().iterator().next().getSk()); } @DynamoDbBean public static class YourItem { public YourItem() {} public YourItem(String pk, String sk, String name) { this.pk = pk; this.sk = sk; this.name = name; } private String pk; private String sk; private String name; @DynamoDbPartitionKey public void setPk(String pk) { this.pk = pk; } public String getPk() { return pk; } @DynamoDbSortKey public void setSk(String sk) { this.sk = sk; } public String getSk() { return sk; } public void setName(String name) { this.name = name; } public String getName() { return name; } } } ``` **High-level antarmuka menggunakan kelas data yang tidak dapat diubah** Ketika Anda melakukan a `Query` dengan kelas data immutable tingkat tinggi, kodenya sama dengan contoh antarmuka tingkat tinggi kecuali untuk konstruksi kelas `YourItem` entitas atau. `YourImmutableItem` Untuk informasi lebih lanjut, lihat [ PutItem ](#HighLevelImmutableDataClassEg) contoh. **High-level antarmuka menggunakan kelas data yang tidak dapat diubah dan pustaka pembuatan boilerplate pihak ketiga** Ketika Anda melakukan a `Query` dengan kelas data immutable tingkat tinggi, kodenya sama dengan contoh antarmuka tingkat tinggi kecuali untuk konstruksi kelas `YourItem` entitas atau. `YourImmutableLombokItem` Untuk informasi lebih lanjut, lihat [ PutItem ](#HighLevelImmutableDataClassEg) contoh. ## Contoh kode tambahan Untuk contoh tambahan tentang cara menggunakan DynamoDB dengan SDK untuk Java 2.x, lihat repositori contoh kode berikut: + [Contoh kode AWS tindakan tunggal resmi ](https://docs.aws.amazon.com/code-library/latest/ug/java_2_dynamodb_code_examples.html) + [Community-maintained contoh kode tindakan tunggal ](https://github.com/aws-samples/aws-dynamodb-examples/tree/master/examples/SDK/java) + [Contoh kode AWS berorientasi skenario resmi ](https://github.com/aws-samples/aws-dynamodb-examples/tree/master/examples/SDK/java) ## Pemrograman sinkron dan asinkron Men AWS SDK for Java 2.x yediakan * klien * sin * kron * dan asinkron untuk Layanan AWS, seperti DynamoDB. `DynamoDbEnhancedClient`Kel `DynamoDbClient` as dan menyediakan metode sinkron yang memblokir eksekusi thread Anda sampai klien menerima respons dari layanan. Klien ini adalah cara paling mudah untuk berinteraksi dengan DynamoDB jika Anda tidak memerlukan operasi asinkron. `DynamoDbEnhancedAsyncClient`Kel `DynamoDbAsyncClient` as and menyediakan metode asinkron yang segera kembali, dan memberikan kontrol kembali ke thread pemanggil tanpa menunggu respons. Klien non-pemblokiran memiliki keuntungan yang digunakan untuk konkurensi tinggi di beberapa utas, yang menyediakan penanganan I/O permintaan yang efisien dengan sumber daya komputasi minimal. Ini meningkatkan throughput dan daya tanggap. Menggunakan AWS SDK for Java 2.x dukungan asli untuk non-pemblokiran I/O. AWS SDK untuk Java 1.x harus mensimulasikan non- I/O pemblokiran. Metode asinkron kembali sebelum respons tersedia, jadi Anda memerlukan cara untuk mendapatkan respons ketika sudah siap. Metode ini AWS SDK untuk Java mengembalikan [`CompletableFuture`](https://docs.oracle.com/javase/8/docs/api/index.html?java/util/concurrent/CompletableFuture.html) objek yang berisi hasil operasi asinkron di masa depan. Saat Anda memang `get()` gil atau `join()` pada `CompletableFuture` objek ini, kode Anda diblokir sampai hasilnya tersedia. Jika Anda memanggil ini pada saat yang sama saat Anda membuat permintaan, maka perilakunya mirip dengan panggilan sinkron biasa. Untuk informasi selengkapnya tentang pemrograman asinkron, lihat [ Menggunakan pemrograman asinkron ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/asynchronous.html) di Panduan Pengembang. *AWS SDK for Java 2.x * ## Klien HTTP Untuk mendukung setiap klien, ada klien HTTP yang menangani komunikasi dengan Layanan AWS. Anda dapat mencolokkan klien HTTP alternatif, memilih salah satu yang memiliki karakteristik yang paling sesuai dengan aplikasi Anda. Beberapa lebih ringan; beberapa memiliki lebih banyak opsi konfigurasi. Beberapa klien HTTP hanya mendukung penggunaan sinkron, sementara yang lain hanya mendukung penggunaan asinkron. Untuk diagram alur yang dapat membantu Anda memilih klien HTTP optimal untuk beban kerja Anda, lihat rekomendasi klien [ HTTP ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/http-configuration.html#http-clients-recommend) di Panduan * Peng *AWS SDK for Java 2.x embang. Daftar berikut menyajikan beberapa klien HTTP yang mungkin: **Topics** + [Apache-based Klien HTTP](#ApacheHttpClient) + [`Klien HTTP` berbasis URLConnection](#URLConnHttpClient) + [Netty-based Klien HTTP](#NettyHttpClient) + [AWS CRT-based Klien HTTP](#AWSCRTHttpClient) ### Apache-based Klien HTTP [`ApacheHttpClient`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/apache/ApacheHttpClient.html)Kelas ini mendukung klien layanan sinkron. Ini adalah klien HTTP default untuk penggunaan sinkron. Untuk informasi tentang mengonfigurasi `ApacheHttpClient` kelas, lihat Meng [ onfigurasi klien Apache-based HTTP ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/http-configuration-apache.html) di Panduan *AWS SDK for Java 2.x Pengembang*. ### `Klien HTTP` berbasis URLConnection Kel [`UrlConnectionHttpClient`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/http/urlconnection/UrlConnectionHttpClient.html) as adalah pilihan lain untuk klien sinkron. Ini memuat lebih cepat daripada klien Apache-based HTTP, tetapi memiliki lebih sedikit fitur. Untuk informasi tentang mengonfigurasi `UrlConnectionHttpClient` kelas, lihat Meng [ onfigurasi klien URLConnection-based HTTP ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/http-configuration-url.html) di Panduan *AWS SDK for Java 2.x Pengembang*. ### Netty-based Klien HTTP `NettyNioAsyncHttpClient`Kelas ini mendukung klien async. Ini adalah pilihan default untuk penggunaan async. Untuk informasi tentang mengonfigurasi `NettyNioAsyncHttpClient` kelas, lihat Meng [ onfigurasi klien Netty-based HTTP ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/http-configuration-netty.html) di Panduan *AWS SDK for Java 2.x Pengembang*. ### AWS CRT-based Klien HTTP Kelas `AwsCrtHttpClient` dan `AwsCrtAsyncHttpClient` kelas yang lebih baru dari pust AWS aka Common Runtime (CRT) adalah lebih banyak opsi yang mendukung klien sinkron dan asinkron. Untuk informasi tentang mengonfigurasi `AwsCrtAsyncHttpClient` kelas `AwsCrtHttpClient` dan, lihat Meng [ onfigurasi klien AWS CRT-based HTTP ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/http-configuration-crt.html) di Panduan *AWS SDK for Java 2.x Pengembang*. Untuk pengenalan klien AWS CRT-based HTTP, lihat Mengum [ umkan ketersediaan Klien HTTP AWS CRT AWS SDK for Java 2.x](https://aws.amazon.com/blogs/developer/announcing-availability-of-the-aws-crt-http-client-in-the-aws-sdk-for-java-2-x/) di Blog * Alat Peng *AWS embang. ## Mengkonfigurasi klien HTTP Saat mengonfigurasi klien, Anda dapat memberikan berbagai opsi konfigurasi, termasuk: + Menyetel batas waktu untuk berbagai aspek panggilan API. + Mengaktifkan TCP Keep-Alive. + Mengontrol kebijakan coba lagi saat mengalami kesalahan. + Menentukan atribut eksekusi yang dapat [ dimodifikasi oleh ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/interceptors.html) instance pencegat eksekusi. Pencegat eksekusi dapat menulis kode yang mencegat eksekusi permintaan dan tanggapan API Anda. Ini memungkinkan Anda untuk melakukan tugas-tugas seperti menerbitkan metrik dan memodifikasi permintaan dalam penerbangan. + Menambahkan atau memanipulasi header HTTP. + Mengaktifkan pelacakan met [ rik kinerja sisi klien. ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/metrics.html) Menggunakan fitur ini membantu Anda mengumpulkan metrik tentang klien layanan di aplikasi Anda dan menganalisis output di Amazon CloudWatch. + Menentukan layanan eksekutor alternatif yang akan digunakan untuk penjadwalan tugas, seperti upaya percobaan ulang asinkron dan tugas batas waktu. Anda mengontrol konfigurasi dengan menyediakan [`ClientOverrideConfiguration`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/client/config/ClientOverrideConfiguration.html) objek ke `Builder` kelas klien layanan. Anda akan melihat ini dalam beberapa contoh kode di bagian berikut. Men `ClientOverrideConfiguration` yediakan pilihan konfigurasi standar. Klien HTTP yang dapat dicolokkan yang berbeda memiliki kemungkinan konfigurasi khusus implementasi juga. **Topics** + [Konfigurasi waktu habis](#TimeoutConfig) + [RetryMode](#RetryMode) + [DefaultsMode](#DefaultsMode) + [Keep-Alive konfigurasi](#KeepAliveConfig) + [Koneksi dan konkurensi maksimal](#MaxConnectionsConcurrency) ### Konfigurasi waktu habis Anda dapat menyesuaikan konfigurasi klien untuk mengontrol batas waktu yang terkait dengan panggilan layanan. DynamoDB memberikan latensi yang lebih rendah dibandingkan dengan yang lain. Layanan AWS Oleh karena itu, Anda dapat menyesuaikan properti ini untuk menurunkan nilai batas waktu (antara 4 dan 10 detik) agar gagal lebih cepat jika ada masalah jaringan. Anda dapat menyesuaikan perilaku terkait latensi menggunakan klien Dynam `ClientOverrideConfiguration` oDB atau dengan mengubah opsi konfigurasi terperinci pada implementasi klien HTTP yang mendasarinya. Anda dapat mengonfigurasi properti berdampak berikut menggunakan: `ClientOverrideConfiguration` + `apiCallAttemptTimeout`Jumlah waktu untuk menunggu satu upaya untuk menyelesaikan permintaan HTTP sebelum menyerah dan waktu habis. + `apiCallTimeout`— Jumlah waktu yang dimiliki klien untuk sepenuhnya menjalankan panggilan API. Ini termasuk eksekusi request handler yang terdiri dari semua permintaan HTTP, termasuk percobaan ulang. Men AWS SDK for Java 2.x yedi [ akan nilai default ](https://github.com/aws/aws-sdk-java-v2/blob/a0c8a0af1fa572b16b5bd78f310594d642324156/http-client-spi/src/main/java/software/amazon/awssdk/http/SdkHttpConfigurationOption.java#L134) untuk beberapa opsi batas waktu, seperti batas waktu koneksi dan batas waktu soket. SDK tidak memberikan nilai default untuk batas waktu panggilan API atau batas waktu percobaan panggilan API individual. Jika batas waktu ini tidak disetel di`ClientOverrideConfiguration`, maka SDK secara efektif menggunakan nilai batas waktu soket sebagai `apiCallAttemptTimeout` dan tidak memaksakan an. `apiCallTimeout` Waktu tunggu soket memiliki nilai default 30 detik. Untuk informasi dan contoh selengkapnya, lihat [ Waktu habis ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/timeouts.html) di Panduan * Peng *AWS SDK for Java 2.x embang. Jangan mengatur batas waktu yang sangat rendah atau Anda berisiko semua permintaan gagal selama waktu latensi tinggi. Pola yang lebih baik adalah menggunakan lindung nilai permintaan dan memulai permintaan bersamaan kedua jika yang pertama memakan waktu terlalu lama. Untuk contoh bagaimana lindung nilai permintaan dapat mengurangi latensi ekor, lihat [ Bagaimana Global Payments Inc. meningkatkan latensi ekor mereka menggunakan lindung nilai permintaan dengan DynamoDB ](https://aws.amazon.com/blogs/database/how-global-payments-inc-improved-their-tail-latency-using-request-hedging-with-amazon-dynamodb/) di Blog Database. AWS ### RetryMode Konfigurasi lain yang terkait dengan konfigurasi batas waktu yang harus Anda pertimbangkan adalah objek `RetryMode` konfigurasi. Objek konfigurasi ini berisi kumpulan perilaku coba ulang. SDK untuk Java 2.x mendukung mode coba ulang berikut: + `legacy`— Mode coba ulang default jika Anda tidak mengubahnya secara eksplisit. Mode coba ulang ini khusus untuk Java SDK. Ini ditandai dengan hingga tiga percobaan ulang, atau lebih untuk layanan seperti DynamoDB, yang memiliki hingga delapan percobaan ulang. + `standard`— Dinamakan “standar” karena lebih konsisten dengan AWS SDK lain. Untuk setiap percobaan ulang, mode ini menunggu jumlah waktu acak antara 0 ms dan plafon yang tumbuh secara eksponensial. Pendekatan ini, yang disebut jitter penuh, sepenuhnya mengacak setiap penantian daripada menggunakan penundaan tetap. Untuk DynamoDB, plafon itu dimulai dari penundaan dasar 25 ms dan berlipat ganda dengan setiap percobaan ulang berikutnya, dibatasi pada 20 detik. Mode ini melakukan percobaan ulang pada kondisi kegagalan yang lebih terdeteksi daripada `legacy` mode. Untuk DynamoDB, ia melakukan hingga sembilan total upaya maksimal kecuali Anda mengganti dengan. [the maximum number of attempts](#numRetries) + `adaptive`— Membangun `standard` mode dan secara dinamis membatasi tingkat AWS permintaan untuk memaksimalkan tingkat keberhasilan. Ini dapat terjadi dengan mengorbankan latensi permintaan. Kami tidak merekomendasikan mode coba ulang adaptif ketika latensi yang dapat diprediksi penting. Anda dapat menemukan definisi yang diperluas dari mode coba ulang ini di [ topik Perilaku ](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html) Coba Ulang di Panduan Refer *AWS ensi SDK dan Alat. * Untuk informasi tentang perubahan mendatang pada perilaku coba ulang default di semua AWS SDK, lihat Mengumumkan perilaku [ coba ulang yang diperbarui untuk AWS SDK dan Alat ](https://aws.amazon.com/blogs/developer/announcing-updated-retry-behavior-for-aws-sdks-and-tools/) di Blog Alat Pengembang. AWS Untuk detail yang tepat untuk SDK untuk Java 2.x, lihat pembaruan perilaku [ coba lagi (diskusi \#6984) ](https://github.com/aws/aws-sdk-java-v2/discussions/6984) di situs web. GitHub #### Strategi coba lagi Setiap mode coba lagi diimplementasikan oleh strategi coba ulang*. * API strategi coba ulang (`software.amazon.awssdk.retries`paket) menggantikan * API * kebijakan coba ulang yang lebih lama (`RetryPolicy`dan masuk). `RetryCondition` `software.amazon.awssdk.core.retry` `RetryPolicy`Konfigurasi yang ada terus berfungsi—SDK menyesuaikannya dengan strategi coba lagi—tetapi kode baru harus menggunakan a. [`RetryStrategy`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/api/RetryStrategy.html) AWS SDK untuk Java 2.x menyediakan tiga strategi bawaan: + [`StandardRetryStrategy`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/StandardRetryStrategy.html)— Strategi yang direkomendasikan untuk sebagian besar kasus penggunaan. + [`LegacyRetryStrategy`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/LegacyRetryStrategy.html)— Strategi default ketika Anda tidak menentukan satu. Ini memperlakukan pengecualian throttling dan non-throttling secara berbeda. + [`AdaptiveRetryStrategy`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/AdaptiveRetryStrategy.html)— Untuk kasus penggunaan terbatas sumber daya. Ini menambahkan pembatas tingkat sisi klien dan mengasumsikan klien bekerja melawan satu sumber daya. Untuk informasi selengkapnya, lihat [ Mengonfigurasi perilaku coba ulang di AWS SDK untuk Java 2. ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/retry-strategy.html) x. Ketika klien menemukan kesalahan yang dapat dicoba ulang, seperti pengecualian pembatasan atau kesalahan server sementara, maka SDK akan secara otomatis mencoba ulang permintaan tersebut. Anda dapat mengontrol berapa kali dan seberapa cepat percobaan ulang ini terjadi dengan menyesuaikan strategi coba ulang dengan yang berikut: + `maxAttempts`— Jumlah maksimum upaya (percobaan pertama ditambah percobaan ulang) sebelum permintaan dianggap gagal. Untuk klien DynamoDB, defaultnya adalah 9 upaya untuk semua strategi. + `backoffStrategy`— A [`BackoffStrategy`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/retries/api/BackoffStrategy.html) yang menentukan penundaan antara percobaan ulang. Secara default, klien DynamoDB menggunakan `BackoffStrategy.exponentialDelay` dengan penundaan dasar 25 ms dan penundaan maksimum 20 detik. + `retryOnException`— Menambahkan jenis pengecualian ke set yang memicu percobaan ulang, selain kumpulan pengecualian default SDK yang dapat dicoba ulang. Kode berikut mengonfigurasi klien DynamoDB dengan strategi coba ulang standar yang disesuaikan dengan maksimum enam upaya (upaya pertama ditambah lima percobaan ulang) dan backoff eksponensial yang dimulai pada 100 ms dan dibatasi pada satu detik. ``` BackoffStrategy backoffStrategy = BackoffStrategy.exponentialDelay(Duration.ofMillis(100), Duration.ofSeconds(1)); StandardRetryStrategy retryStrategy = AwsRetryStrategy.standardRetryStrategy() .toBuilder() .maxAttempts(6) .backoffStrategy(backoffStrategy) .build(); DynamoDbClient client = DynamoDbClient.builder() .overrideConfiguration(o -> o.retryStrategy(retryStrategy)) .build(); ``` ### DefaultsMode Properti batas waktu yang `ClientOverrideConfiguration` dan `RetryMode` tidak dikelola biasanya dikonfigurasi secara implisit dengan menentukan a. `DefaultsMode` AWS SDK for Java 2.x (Versi 2.17.102 atau yang lebih baru) memperkenalkan dukungan untuk. `DefaultsMode` Fitur ini menyediakan serangkaian nilai default untuk pengaturan umum yang dapat dikonfigurasi, seperti pengaturan komunikasi HTTP, perilaku coba ulang, pengaturan titik akhir regional layanan, dan kemungkinan konfigurasi apa pun SDK-related . Saat Anda menggunakan fitur ini, Anda bisa mendapatkan default konfigurasi baru yang disesuaikan dengan skenario penggunaan umum. Mode default distandarisasi di semua AWS SDK. SDK untuk Java 2.x mendukung mode default berikut: + `legacy`- Menyediakan pengaturan default yang bervariasi menurut AWS SDK dan yang ada sebelum `DefaultsMode` dibuat. + `standard`- Menyediakan pengaturan default yang tidak dioptimalkan untuk sebagian besar skenario. + `in-region`- Dibangun pada mode standar dan menyertakan pengaturan yang disesuaikan untuk aplikasi yang memang Layanan AWS gil dari dalam yang sama Wilayah AWS. + `cross-region`- Dibangun pada mode standar dan menyertakan pengaturan dengan batas waktu tinggi untuk aplikasi yang memanggil Layanan AWS di Wilayah yang berbeda. + `mobile`- Dibangun pada mode standar dan menyertakan pengaturan dengan batas waktu tinggi yang disesuaikan untuk aplikasi seluler dengan latensi yang lebih tinggi. + `auto`— Dibangun pada mode standar dan mencakup fitur eksperimental. SDK mencoba menemukan lingkungan runtime untuk menentukan pengaturan yang sesuai secara otomatis. Deteksi otomatis berbasis heuristik dan tidak memberikan akurasi 100%. Jika lingkungan runtime tidak dapat ditentukan, maka mode standar digunakan. Deteksi otomatis mungkin menanyakan metadata [ Instance dan data pengguna](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html), yang mungkin menimbulkan latensi. Jika latensi startup sangat penting untuk aplikasi Anda, sebaiknya pilih yang eksplisit sebagai `DefaultsMode` gantinya. Anda dapat mengonfigurasi mode default dengan cara berikut: + Langsung pada klien, melalui`AwsClientBuilder.Builder#defaultsMode(DefaultsMode)`. + Pada profil konfigurasi, melalui properti file `defaults_mode` profil. + Secara global, melalui properti `aws.defaultsMode` sistem. + Secara global, melalui variabel `AWS_DEFAULTS_MODE` lingkungan. **catatan** Untuk mode apa pun selain`legacy`, nilai default yang dijual mungkin berubah seiring dengan berkembangnya praktik terbaik. Oleh karena itu, jika Anda menggunakan mode selain`legacy`, maka kami menyarankan Anda untuk melakukan pengujian saat memutakhirkan SDK. Def [ ault konfigurasi cerdas ](https://docs.aws.amazon.com/sdkref/latest/guide/feature-smart-config-defaults.html) di *AWS SDK dan Panduan Referensi Alat * menyediakan daftar properti konfigurasi dan nilai defaultnya dalam mode default yang berbeda. Anda memilih nilai mode default berdasarkan karakteristik aplikasi Anda dan interaksi aplikasi. Layanan AWS Nilai-nilai ini dikonfigurasi dengan berbagai pilihan Layanan AWS dalam pikiran. Untuk penerapan DynamoDB tipikal di mana tabel DynamoDB dan aplikasi Anda digunakan dalam satu Wilayah, mode default `in-region` paling relevan di antara mode default. `standard` **Example Konfigurasi klien DynamoDB SDK disetel untuk panggilan latensi rendah** Contoh berikut menyesuaikan batas waktu ke nilai yang lebih rendah untuk panggilan DynamoDB latensi rendah yang diharapkan. ``` DynamoDbAsyncClient asyncClient = DynamoDbAsyncClient.builder() .defaultsMode(DefaultsMode.IN_REGION) .httpClientBuilder(AwsCrtAsyncHttpClient.builder()) .overrideConfiguration(ClientOverrideConfiguration.builder() .apiCallTimeout(Duration.ofSeconds(3)) .apiCallAttemptTimeout(Duration.ofMillis(500)) .build()) .build(); ``` Implementasi klien HTTP individual dapat memberi Anda kontrol yang lebih terperinci atas batas waktu dan perilaku penggunaan koneksi. Misalnya, untuk AWS CRT-based klien, Anda dapat mengaktifkan`ConnectionHealthConfiguration`, yang memungkinkan klien untuk secara aktif memantau kesehatan koneksi yang digunakan. Untuk informasi selengkapnya, lihat Konfigurasi [ lanj AWS CRT-based utan klien HTTP ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/http-configuration-crt.html#configuring-the-crt-based-http-client) di Panduan *AWS SDK for Java 2.x Pengembang*. ### Keep-Alive konfigurasi Mengaktifkan keep-alive dapat mengurangi latensi dengan menggunakan kembali koneksi. Ada dua jenis keep-alive yang berbeda: HTTP Keep-Alive dan TCP. Keep-Alive + HTTP Keep-Alive mencoba mempertahankan koneksi HTTPS antara klien dan server sehingga permintaan selanjutnya dapat menggunakan kembali koneksi itu. Ini melewatkan otentikasi HTTPS kelas berat pada permintaan selanjutnya. HTTP Keep-Alive diaktifkan secara default pada semua klien. + TCP Keep-Alive meminta agar sistem operasi yang mendasarinya mengirimkan paket kecil melalui koneksi soket untuk memberikan jaminan ekstra bahwa soket tetap hidup dan untuk segera mendeteksi setiap tetes. Ini memastikan bahwa permintaan selanjutnya tidak akan menghabiskan waktu mencoba menggunakan soket yang terputus. Secara default, TCP dinon Keep-Alive aktifkan pada semua klien. Contoh kode berikut menunjukkan cara mengaktifkannya pada setiap klien HTTP. Ketika diaktifkan untuk semua klien HTTP berbasis non-CRT, Keep-Alive mekanisme sebenarnya tergantung pada sistem operasi. Oleh karena itu, Anda harus mengkonfigurasi Keep-Alive nilai TCP tambahan, seperti batas waktu dan jumlah paket, melalui sistem operasi. Anda dapat melakukan ini menggunakan `sysctl` di Linux atau macOS, atau menggunakan nilai registri di Windows. **Example untuk mengaktifkan TCP Keep-Alive pada klien Apache-based HTTP** ``` DynamoDbClient client = DynamoDbClient.builder() .httpClientBuilder(ApacheHttpClient.builder().tcpKeepAlive(true)) .build(); ``` **`Klien HTTP` berbasis URLConnection** Setiap klien sinkron yang menggunakan klien HTTP `URLConnection` berbasis [`HttpURLConnection`](https://docs.oracle.com/javase/8/docs/api/java/net/HttpURLConnection.html) tidak memiliki [ mekanisme ](https://docs.oracle.com/javase/8/docs/api/java/net/doc-files/net-properties.html) untuk mengaktifkan keep-alive. **Example untuk mengaktifkan TCP Keep-Alive pada klien Netty-based HTTP** ``` DynamoDbAsyncClient client = DynamoDbAsyncClient.builder() .httpClientBuilder(NettyNioAsyncHttpClient.builder().tcpKeepAlive(true)) .build(); ``` **Example untuk mengaktifkan TCP Keep-Alive pada AWS CRT-based Klien HTTP** Dengan klien AWS CRT-based HTTP, Anda dapat mengaktifkan TCP keep-alive dan mengontrol durasinya. ``` DynamoDbClient client = DynamoDbClient.builder() .httpClientBuilder(AwsCrtHttpClient.builder() .tcpKeepAliveConfiguration(TcpKeepAliveConfiguration.builder() .keepAliveInterval(Duration.ofSeconds(50)) .keepAliveTimeout(Duration.ofSeconds(5)) .build())) .build(); ``` Saat menggunakan klien DynamoDB asinkron, Anda dapat mengaktifkan TCP Keep-Alive seperti yang ditunjukkan dalam kode berikut. ``` DynamoDbAsyncClient client = DynamoDbAsyncClient.builder() .httpClientBuilder(AwsCrtAsyncHttpClient.builder() .tcpKeepAliveConfiguration(TcpKeepAliveConfiguration.builder() .keepAliveInterval(Duration.ofSeconds(50)) .keepAliveTimeout(Duration.ofSeconds(5)) .build())) .build(); ``` ### Koneksi dan konkurensi maksimal Setiap mesin HTTP kecuali dasar `URLConnection` menawarkan baik `maxConnections()` (untuk sinkron) atau `maxConcurrency()` (untuk asinkron) untuk mengontrol jumlah permintaan bersamaan yang diizinkan. Defaultnya adalah 50. Anda dapat menaikkan ini saat mengharapkan konkurensi tinggi terhadap instance klien yang sama. ``` ApacheHttpClient.Builder httpClientBuilder = ApacheHttpClient.builder() .maxConnections(100); // Set to 100 from this synchronous client NettyNioAsyncHttpClient.Builder nettyClientBuilder = NettyNioAsyncHttpClient.builder() .maxConcurrency(200); // Async allows higher throughput ``` ## Penanganan kesalahan Dalam hal penanganan pengecualian, AWS SDK for Java 2.x menggunakan pengecualian runtime (tidak dicentang). Pengecualian dasar, yang mencakup semua pengecualian SDK, adalah [`SdkServiceException`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/exception/SdkServiceException.html), yang memanjang dari Java yang tidak dicentang`RuntimeException`. Jika Anda menangkap ini, Anda akan menangkap semua pengecualian yang diberikan SDK. `SdkServiceException`memiliki subkelas yang disebut [`AwsServiceException`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/awscore/exception/AwsServiceException.html). Subkelas ini menunjukkan masalah apa pun dalam komunikasi dengan. Layanan AWS Ini memiliki subkelas yang disebut [`DynamoDbException`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/model/DynamoDbException.html), yang menunjukkan masalah dalam komunikasi dengan DynamoDB. Jika Anda menangkap ini, Anda akan menangkap semua pengecualian yang terkait dengan DynamoDB, tetapi tidak ada pengecualian SDK lainnya. Ada jenis [ pengecualian yang lebih spesifik ](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/model/DynamoDbException.html) di bawah`DynamoDbException`. Beberapa jenis pengecualian ini berlaku untuk operasi bidang kontrol seperti. [`TableAlreadyExistsException`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/model/TableAlreadyExistsException.html) Lainnya berlaku untuk operasi data-plane. Berikut ini adalah contoh pengecualian bidang data umum: + [`ConditionalCheckFailedException`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/model/ConditionalCheckFailedException.html)— Anda menentukan kondisi dalam permintaan yang dievaluasi menjadi salah. Misalnya, Anda mungkin telah mencoba melakukan pembaruan bersyarat pada suatu item, tetapi nilai atribut sebenarnya tidak cocok dengan nilai yang diharapkan dalam kondisi yang dihadapi. Permintaan yang gagal dengan cara ini tidak dicoba lagi. Situasi lain tidak memiliki pengecualian khusus yang ditentukan. Misalnya, ketika permintaan Anda dibatasi, spesifik `ProvisionedThroughputExceededException` mungkin dilemparkan, sementara dalam kasus lain yang lebih umum `DynamoDbException` dilemparkan. Dalam kedua kasus tersebut, Anda dapat menentukan apakah throttling menyebabkan pengecualian dengan memeriksa apakah pengem `isThrottlingException()` balian`true`. Tergantung pada kebutuhan aplikasi Anda, Anda dapat menangkap semua `AwsServiceException` atau `DynamoDbException` contoh. Namun, Anda sering membutuhkan perilaku yang berbeda dalam situasi yang berbeda. Logika untuk menangani kegagalan pemeriksaan kondisi berbeda dengan menangani pelambatan. Tentukan jalur luar biasa mana yang ingin Anda tangani dan pastikan untuk menguji jalur alternatif. Ini membantu Anda memastikan bahwa Anda dapat menangani semua skenario yang relevan. Untuk daftar kesalahan umum yang mungkin Anda temui, lihat[Penanganan kesalahan dengan DynamoDB](Programming.Errors.md). Lihat juga Kes [ alahan Umum ](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/CommonErrors.html) di Referensi API * Amazon DynamoDB. * Referensi API juga memberikan kesalahan yang tepat yang mungkin terjadi untuk setiap operasi API, seperti untuk [`Query`](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html) operasi. Untuk informasi tentang penanganan pengecualian, lihat [ Penanganan pengecualian untuk AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/handling-exceptions.html) di Panduan *AWS SDK for Java 2.x Pengembang*. ## AWS ID permintaan Setiap permintaan menyertakan ID permintaan, yang dapat berguna untuk ditarik jika Anda bekerja AWS Dukungan untuk mendiagnosis masalah. Setiap pengecualian yang berasal dari `SdkServiceException` memiliki [`requestId()`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/exception/SdkServiceException.html#requestId()) metode yang tersedia untuk mengambil ID permintaan. ## Pencatatan log Menggunakan logging yang disediakan SDK dapat berguna baik untuk menangkap pesan penting dari pustaka klien dan untuk tujuan debugging yang lebih mendalam. Logger bersifat hierarkis dan SDK digunakan `software.amazon.awssdk` sebagai root logger. Anda dapat mengonfigurasi level dengan salah satu dari `TRACE``DEBUG`,`INFO`,`WARN`,`ERROR`,`ALL`, atau`OFF`. Level yang dikonfigurasi berlaku untuk logger itu dan turun ke hierarki logger. Untuk pencatatan, AWS SDK for Java 2.x menggunakan Simple Logging Facade for Java (SLF4J). Ini bertindak sebagai lapisan abstraksi di sekitar logger lain, dan Anda dapat menggunakannya untuk menyambungkan logger yang Anda inginkan. Untuk petunjuk tentang mencolokkan logger, lihat panduan pengguna [ SLF4J. ](https://www.slf4j.org/manual.html) Setiap logger memiliki perilaku tertentu. Secara default, logger Log4j 2.x membuat`ConsoleAppender`, yang menambahkan peristiwa log ke `System.out` dan default ke tingkat log. `ERROR` SimpleLogger Logger yang disertakan dalam output SLF4J secara default ke `System.err` dan default ke level log. `INFO` Sebaiknya setel level ke `WARN` for `software.amazon.awssdk` untuk setiap penerapan produksi untuk menangkap pesan penting dari pustaka klien SDK sambil membatasi kuantitas keluaran. Jika SLF4J tidak dapat menemukan logger yang didukung di jalur kelas (tidak ada pengikatan SLF4J), maka default ke implementasi tanpa operasi. [https://www.slf4j.org/codes.html#noProviders](https://www.slf4j.org/codes.html#noProviders) Implementasi ini menghasilkan catatan pesan untuk `System.err` menjelaskan bahwa SLF4J tidak dapat menemukan implementasi logger di classpath. Untuk mencegah situasi ini, Anda harus menambahkan implementasi logger. Untuk melakukan ini, Anda dapat menambahkan ketergantungan di Apache Maven Anda `pom.xml` pada artefak, seperti `org.slf4j.slf4j-simple` atau`org.apache.logging.log4j.log4j-slf4j2-imp`. Untuk informasi tentang cara mengonfigurasi logging di SDK, termasuk menambahkan dependensi logging ke konfigurasi aplikasi Anda, lihat [ Logging dengan SDK untuk Java 2.x ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/logging-slf4j.html) di Panduan Peng *AWS SDK untuk Java embang. * Konfigurasi berikut dalam `Log4j2.xml` file menunjukkan cara menyesuaikan perilaku logging jika Anda menggunakan logger Apache Log4j 2. Konfigurasi ini mengatur level root logger ke`WARN`. Semua logger dalam hierarki mewarisi level log ini, termasuk `software.amazon.awssdk` logger. Secara default, output masuk ke`System.out`. Dalam contoh berikut, kami masih mengganti appender Log4j keluaran default untuk menerapkan Log4j yang disesuaikan. `PatternLayout` **Contoh dari `Log4j2.xml` berkas konfigurasi** Konfigurasi berikut mencatat pesan ke konsol di `WARN` level `ERROR` dan untuk semua hierarki logger. ``` ``` ### AWS meminta pencatatan ID Ketika terjadi kesalahan, Anda dapat menemukan ID permintaan dalam pengecualian. Namun, jika Anda menginginkan ID permintaan untuk permintaan yang tidak menghasilkan pengecualian, maka Anda dapat menggunakan logging. Out `software.amazon.awssdk.request` put logger meminta ID di `DEBUG` level tersebut. Contoh berikut memperluas yang sebelumnya [configuration example](#Log4j2ConfigEg) untuk menjaga level root logger di`ERROR`, `software.amazon.awssdk` level at`WARN`, dan `software.amazon.awssdk.request` at level`DEBUG`. Menyetel level ini membantu menangkap ID permintaan dan detail terkait permintaan lainnya, seperti titik akhir dan kode status. ``` ``` Berikut adalah contoh keluaran log: ``` 2022-09-23 16:02:08 [main] DEBUG software.amazon.awssdk.request:85 - Sending Request: DefaultSdkHttpFullRequest(httpMethod=POST, protocol=https, host=dynamodb.us-east-1.amazonaws.com, encodedPath=/, headers=[amz-sdk-invocation-id, Content-Length, Content-Type, User-Agent, X-Amz-Target], queryParameters=[]) 2022-09-23 16:02:08 [main] DEBUG software.amazon.awssdk.request:85 - Received successful response: 200, Request ID: QS9DUMME2NHEDH8TGT9N5V53OJVV4KQNSO5AEMVJF66Q9ASUAAJG, Extended Request ID: not available ``` ## Paginasi Beberapa permintaan, seperti [`Query`](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html) dan [`Scan`](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html), membatasi ukuran data yang dikembalikan pada satu permintaan dan mengharuskan Anda membuat permintaan berulang untuk menarik halaman berikutnya. Anda dapat mengontrol jumlah maksimum item untuk dibaca untuk setiap halaman dengan `Limit` parameter. Misalnya, Anda dapat menggunakan `Limit` parameter untuk mengambil hanya 10 item. Batas ini menentukan berapa banyak item yang akan dibaca dari tabel sebelum pemfilteran diterapkan. Jika Anda ingin tepat 10 item setelah pemfilteran, tidak ada cara untuk menentukannya. Anda hanya dapat mengontrol jumlah pra-filter dan memeriksa sisi klien ketika Anda benar-benar mengambil 10 item. Terlepas dari batasnya, respons selalu memiliki ukuran maksimum 1 MB. A `LastEvaluatedKey` mungkin disertakan dalam respons API. Ini menunjukkan bahwa respons berakhir karena mencapai batas hitungan atau batas ukuran. Kunci ini adalah kunci terakhir yang dievaluasi untuk respons itu. Dengan berinteraksi langsung dengan API, Anda dapat mengambil ini `LastEvaluatedKey` dan meneruskannya ke panggilan tindak lanjut `ExclusiveStartKey` untuk membaca potongan berikutnya dari titik awal itu. Jika no `LastEvaluatedKey` dikembalikan, itu berarti tidak ada lagi item yang cocok dengan panggilan `Scan` API `Query` or. Contoh berikut menggunakan antarmuka tingkat rendah untuk membatasi item hingga 100 berdasarkan `keyConditionExpression` parameter. ``` QueryRequest.Builder queryRequestBuilder = QueryRequest.builder() .expressionAttributeValues(Map.of( ":pk_val", AttributeValue.fromS("123"), ":sk_val", AttributeValue.fromN("1000"))) .keyConditionExpression("pk = :pk_val AND sk > :sk_val") .limit(100) .tableName(TABLE_NAME); while (true) { QueryResponse queryResponse = DYNAMODB_CLIENT.query(queryRequestBuilder.build()); queryResponse.items().forEach(item -> { LOGGER.info("item PK: [" + item.get("pk") + "] and SK: [" + item.get("sk") + "]"); }); if (!queryResponse.hasLastEvaluatedKey()) { break; } queryRequestBuilder.exclusiveStartKey(queryResponse.lastEvaluatedKey()); } ``` AWS SDK for Java 2.x Dapat menyederhanakan interaksi ini dengan DynamoDB dengan menyediakan metode pagination otomatis yang membuat beberapa panggilan layanan untuk secara otomatis mendapatkan halaman hasil berikutnya untuk Anda. Ini menyederhanakan kode Anda, tetapi menghilangkan beberapa kontrol penggunaan sumber daya yang akan Anda simpan dengan membaca halaman secara manual. Dengan menggunakan `Iterable` metode yang tersedia di klien DynamoDB, seperti [`QueryPaginator`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/DynamoDbClient.html#queryPaginator(software.amazon.awssdk.services.dynamodb.model.QueryRequest)) dan [`ScanPaginator`](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/DynamoDbClient.html#scanPaginator(software.amazon.awssdk.services.dynamodb.model.ScanRequest)), SDK menangani paginasi. Jenis pengembalian metode ini adalah iterable kustom yang dapat Anda gunakan untuk mengulangi semua halaman. SDK secara internal menangani panggilan layanan untuk Anda. Menggunakan Java Stream API, Anda dapat menangani hasil `QueryPaginator` seperti yang ditunjukkan pada contoh berikut. ``` QueryIterable results = DYNAMODB_CLIENT.queryPaginator(QueryRequest.builder() .expressionAttributeValues(Map.of( ":pk_val", AttributeValue.fromS("123"), ":sk_val", AttributeValue.fromN("1000"))) .keyConditionExpression("pk = :pk_val AND sk > :sk_val") .limit(100) .tableName("YourTableName") .build()); results.items().stream() .forEach(item -> System.out.println(item.get("itemData"))); ``` ## Anotasi kelas data Java SDK menyediakan beberapa anotasi yang dapat Anda masukkan pada atribut kelas data Anda. Anotasi ini memengaruhi cara SDK berinteraksi dengan atribut. Dengan menambahkan anotasi, Anda dapat memiliki atribut yang berperilaku sebagai penghitung atom implisit, mempertahankan nilai stempel waktu yang dibuat secara otomatis, atau melacak nomor versi item. Untuk informasi selengkapnya, lihat [ Anotasi ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/ddb-en-client-anno-index.html) kelas data. ## Praktik terbaik Untuk informasi selengkapnya tentang praktik terbaik Java SDK, lihat Praktik [ terbaik untuk menggunakan AWS SDK untuk Java 2.x ](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/best-practices.html) di Panduan * Peng *AWS SDK for Java 2.x embang.