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.

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 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 AWS SDK dan Alat serta matri AWS ks dukungan versi SDK dan Alat 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.amazonawsgroupId, sedangkan artefak Java 2.x SDK menggunakan. software.amazon.awssdk groupId

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

Memulai dengan AWS SDK for Java 2.x

Tutorial berikut menunjukkan cara menggunakan Apache Maven 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 di Panduan Peng AWS SDK for Java 2.x embang. Kami telah mengedit tutorial ini untuk melakukan panggilan ke DynamoDB alih-alih Amazon S3.

Langkah 1: Siapkan untuk tutorial ini

Sebelum Anda memulai tutorial ini, Anda memerlukan yang berikut:

Untuk menyiapkan tutorial ini, ikuti petunjuk dalam ikhtisar Peng aturan di Panduan Peng AWS SDK for Java 2.x embang. Setelah Anda mengonfigurasi lingkungan pengembangan Anda dengan akses masuk tunggal untuk Java SDK dan Anda memiliki sesi portal AWS akses aktif, lanjutkan ke Langkah 2 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.

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.

<?xml version="1.0" encoding="UTF-8"?>
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
 
     <groupId>org.example</groupId>
     <artifactId>getstarted</artifactId>
     <version>1.0-SNAPSHOT</version>
     <packaging>jar</packaging>
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <maven.compiler.source>1.8</maven.compiler.source>
         <maven.compiler.target>1.8</maven.compiler.target>
         <maven.shade.plugin.version>3.2.1</maven.shade.plugin.version>
         <maven.compiler.plugin.version>3.6.1</maven.compiler.plugin.version>
         <exec-maven-plugin.version>1.6.0</exec-maven-plugin.version>
         <aws.java.sdk.version>2.22.0</aws.java.sdk.version> <-------- SDK version picked up from archetype version.
         <slf4j.version>1.7.28</slf4j.version>
         <junit5.version>5.8.1</junit5.version>
     </properties>
 
     <dependencyManagement>
         <dependencies>
             <dependency>
                 <groupId>software.amazon.awssdk</groupId>
                 <artifactId>bom</artifactId>
                 <version>${aws.java.sdk.version}</version>
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>
         </dependencies>
     </dependencyManagement>
 
     <dependencies>
         <dependency>
             <groupId>software.amazon.awssdk</groupId>
             <artifactId>dynamodb</artifactId>  <-------- DynamoDB dependency
             <exclusions>
                 <exclusion>
                     <groupId>software.amazon.awssdk</groupId>
                     <artifactId>netty-nio-client</artifactId>
                 </exclusion>
                 <exclusion>
                     <groupId>software.amazon.awssdk</groupId>
                     <artifactId>apache-client</artifactId>
                 </exclusion>
             </exclusions>
         </dependency>
 
         <dependency>
             <groupId>software.amazon.awssdk</groupId>
             <artifactId>sso</artifactId> <-------- Required for identity center authentication.
         </dependency>
 
         <dependency>
             <groupId>software.amazon.awssdk</groupId>
             <artifactId>ssooidc</artifactId> <-------- Required for identity center authentication.
         </dependency>
 
         <dependency>
             <groupId>software.amazon.awssdk</groupId>
             <artifactId>apache-client</artifactId> <-------- HTTP client specified.
             <exclusions>
                 <exclusion>
                     <groupId>commons-logging</groupId>
                     <artifactId>commons-logging</artifactId>
                 </exclusion>
             </exclusions>
         </dependency>
 
         <dependency>
             <groupId>org.slf4j</groupId>
             <artifactId>slf4j-api</artifactId>
             <version>${slf4j.version}</version>
         </dependency>
 
         <dependency>
             <groupId>org.slf4j</groupId>
             <artifactId>slf4j-simple</artifactId>
             <version>${slf4j.version}</version>
         </dependency>
 
         <!-- Needed to adapt Apache Commons Logging used by Apache HTTP Client to Slf4j to avoid
         ClassNotFoundException: org.apache.commons.logging.impl.LogFactoryImpl during runtime -->
         <dependency>
             <groupId>org.slf4j</groupId>
             <artifactId>jcl-over-slf4j</artifactId>
             <version>${slf4j.version}</version>
         </dependency>
 
         <!-- Test Dependencies -->
         <dependency>
             <groupId>org.junit.jupiter</groupId>
             <artifactId>junit-jupiter</artifactId>
             <version>${junit5.version}</version>
             <scope>test</scope>
         </dependency>
     </dependencies>
 
     <build>
         <plugins>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
                 <version>${maven.compiler.plugin.version}</version>
             </plugin>
         </plugins>
     </build>
 
 </project>

Langkah 3: Tulis kode

Kode berikut menunjukkan App kelas yang dibuat Maven. mainMetode ini adalah titik masuk ke dalam aplikasi, yang membuat instance Handler kelas dan kemudian memanggil sendRequest metodenya.

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 instance. DynamoDbClientInstance 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.

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

HandlerKelas 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.

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. sendRequestMetode ini diisi dan impor yang diperlukan ditambahkan.

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.

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 proyekgetstarted.

Meninjau AWS SDK for Java 2.x dokumentasi

Panduan Peng AWS SDK for Java 2.x embang mencakup semua aspek SDK di semua Layanan AWS. Kami menyarankan Anda meninjau topik-topik berikut:

Antarmuka yang didukung

Men AWS SDK for Java 2.x dukung antarmuka berikut, tergantung pada tingkat abstraksi yang Anda inginkan.

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 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 di Panduan Peng AWS SDK for Java 2.x embang.

Contoh berikut PutItem 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<YourItem> DYNAMODB_TABLE = ENHANCED_DYNAMODB_CLIENT.table("YourTableName", TableSchema.fromBean(YourItem.class));
    private static final Logger LOGGER = LoggerFactory.getLogger(DynamoDbEnhancedClientPutItem.class);

    private void putItem() {
        PutItemEnhancedResponse<YourItem> 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) bernamasoftware.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 padaHigh-level interface example, 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 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<YourImmutableItem> DYNAMODB_TABLE = ENHANCED_DYNAMODB_CLIENT.table("YourTableName", TableSchema.fromImmutableClass(YourImmutableItem.class));
    private static final Logger LOGGER = LoggerFactory.getLogger(DynamoDbEnhancedClientImmutablePutItem.class);

    private void putItem() {
        PutItemEnhancedResponse<YourImmutableItem> 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, 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 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<YourImmutableLombokItem> DYNAMODB_TABLE = ENHANCED_DYNAMODB_CLIENT.table("YourTableName", TableSchema.fromImmutableClass(YourImmutableLombokItem.class));
    private static final Logger LOGGER = LoggerFactory.getLogger(DynamoDbEnhancedClientImmutableLombokPutItem.class);

    private void putItem() {
        PutItemEnhancedResponse<YourImmutableLombokItem> 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:

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 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 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<EnhancedDocument> 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<EnhancedDocument> 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:

Membandingkan antarmuka dengan contoh Query

Bagian ini menunjukkan Query panggilan yang sama yang diekspresikan menggunakan berbagai antarmuka. Untuk menyempurnakan hasil kueri ini, perhatikan hal berikut:

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

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

    }
}

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

Contoh kode tambahan

Untuk contoh tambahan tentang cara menggunakan DynamoDB dengan SDK untuk Java 2.x, lihat repositori contoh kode berikut:

Pemrograman sinkron dan asinkron

Men AWS SDK for Java 2.x yediakan klien sin kron dan asinkron untuk Layanan AWS, seperti DynamoDB.

DynamoDbEnhancedClientKel 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.

DynamoDbEnhancedAsyncClientKel 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 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 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 di Panduan Peng AWS SDK for Java 2.x embang.

Daftar berikut menyajikan beberapa klien HTTP yang mungkin:

Apache-based Klien HTTP

ApacheHttpClientKelas 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 di Panduan AWS SDK for Java 2.x Pengembang.

Klien HTTP berbasis URLConnection

Kel UrlConnectionHttpClient 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 di Panduan AWS SDK for Java 2.x Pengembang.

Netty-based Klien HTTP

NettyNioAsyncHttpClientKelas ini mendukung klien async. Ini adalah pilihan default untuk penggunaan async. Untuk informasi tentang mengonfigurasi NettyNioAsyncHttpClient kelas, lihat Meng onfigurasi klien Netty-based HTTP 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 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 di Blog Alat Peng AWS embang.

Mengkonfigurasi klien HTTP

Saat mengonfigurasi klien, Anda dapat memberikan berbagai opsi konfigurasi, termasuk:

Anda mengontrol konfigurasi dengan menyediakan ClientOverrideConfiguration 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.

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

Men AWS SDK for Java 2.x yedi akan nilai default 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 diClientOverrideConfiguration, 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 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 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:

Anda dapat menemukan definisi yang diperluas dari mode coba ulang ini di topik Perilaku 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 di Blog Alat Pengembang. AWS Untuk detail yang tepat untuk SDK untuk Java 2.x, lihat pembaruan perilaku coba lagi (diskusi #6984) di situs web. GitHub

Strategi coba lagi

Setiap mode coba lagi diimplementasikan oleh strategi coba ulang. API strategi coba ulang (software.amazon.awssdk.retriespaket) menggantikan API kebijakan coba ulang yang lebih lama (RetryPolicydan masuk). RetryCondition software.amazon.awssdk.core.retry RetryPolicyKonfigurasi yang ada terus berfungsi—SDK menyesuaikannya dengan strategi coba lagi—tetapi kode baru harus menggunakan a. RetryStrategy AWS SDK untuk Java 2.x menyediakan tiga strategi bawaan:

Untuk informasi selengkapnya, lihat Mengonfigurasi perilaku coba ulang di AWS SDK untuk Java 2. 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:

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:

Anda dapat mengonfigurasi mode default dengan cara berikut:

Def ault konfigurasi cerdas 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

DynamoDbAsyncClient asyncClient = DynamoDbAsyncClient.builder()
    .defaultsMode(DefaultsMode.IN_REGION)
    .httpClientBuilder(AwsCrtAsyncHttpClient.builder())
    .overrideConfiguration(ClientOverrideConfiguration.builder()
        .apiCallTimeout(Duration.ofSeconds(3))
        .apiCallAttemptTimeout(Duration.ofMillis(500))
        .build())
    .build();

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

DynamoDbClient client = DynamoDbClient.builder()
    .httpClientBuilder(ApacheHttpClient.builder().tcpKeepAlive(true))
    .build();

Klien HTTP berbasis URLConnection

Setiap klien sinkron yang menggunakan klien HTTP URLConnection berbasis HttpURLConnection tidak memiliki mekanisme untuk mengaktifkan keep-alive.

DynamoDbAsyncClient client = DynamoDbAsyncClient.builder()
    .httpClientBuilder(NettyNioAsyncHttpClient.builder().tcpKeepAlive(true))
    .build();

DynamoDbClient client = DynamoDbClient.builder()
    .httpClientBuilder(AwsCrtHttpClient.builder()
    .tcpKeepAliveConfiguration(TcpKeepAliveConfiguration.builder()
        .keepAliveInterval(Duration.ofSeconds(50))
        .keepAliveTimeout(Duration.ofSeconds(5))
        .build()))
    .build();

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, yang memanjang dari Java yang tidak dicentangRuntimeException. Jika Anda menangkap ini, Anda akan menangkap semua pengecualian yang diberikan SDK.

SdkServiceExceptionmemiliki subkelas yang disebut AwsServiceException. Subkelas ini menunjukkan masalah apa pun dalam komunikasi dengan. Layanan AWS Ini memiliki subkelas yang disebut DynamoDbException, 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 di bawahDynamoDbException. Beberapa jenis pengecualian ini berlaku untuk operasi bidang kontrol seperti. TableAlreadyExistsException Lainnya berlaku untuk operasi data-plane. Berikut ini adalah contoh pengecualian bidang data umum:

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() baliantrue.

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, lihatPenanganan kesalahan dengan DynamoDB. Lihat juga Kes alahan Umum di Referensi API Amazon DynamoDB. Referensi API juga memberikan kesalahan yang tepat yang mungkin terjadi untuk setiap operasi API, seperti untuk Query operasi. Untuk informasi tentang penanganan pengecualian, lihat Penanganan pengecualian untuk AWS SDK for Java 2.x 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() 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 TRACEDEBUG,INFO,WARN,ERROR,ALL, atauOFF. 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.

Setiap logger memiliki perilaku tertentu. Secara default, logger Log4j 2.x membuatConsoleAppender, 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 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 atauorg.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 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 keWARN. Semua logger dalam hierarki mewarisi level log ini, termasuk software.amazon.awssdk logger.

Secara default, output masuk keSystem.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.

<Configuration status="WARN">
  <Appenders>
    <Console name="ConsoleAppender" target="SYSTEM_OUT">
      <PatternLayout pattern="%d{YYYY-MM-dd HH:mm:ss} [%t] %-5p %c:%L - %m%n" />
    </Console>
  </Appenders>

  <Loggers>
    <Root level="WARN">
      <AppenderRef ref="ConsoleAppender"/>
    </Root>
  </Loggers>
</Configuration>

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 untuk menjaga level root logger diERROR, software.amazon.awssdk level atWARN, dan software.amazon.awssdk.request at levelDEBUG. Menyetel level ini membantu menangkap ID permintaan dan detail terkait permintaan lainnya, seperti titik akhir dan kode status.

<Configuration status="WARN">
  <Appenders>
    <Console name="ConsoleAppender" target="SYSTEM_OUT">
      <PatternLayout pattern="%d{YYYY-MM-dd HH:mm:ss} [%t] %-5p %c:%L - %m%n" />
    </Console>
  </Appenders>

  <Loggers>
    <Root level="ERROR">
      <AppenderRef ref="ConsoleAppender"/>
    </Root>
    <Logger name="software.amazon.awssdk" level="WARN" />
    <Logger name="software.amazon.awssdk.request" level="DEBUG" />
  </Loggers>
</Configuration>

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 dan Scan, 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 dan ScanPaginator, 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 kelas data.

Praktik terbaik

Untuk informasi selengkapnya tentang praktik terbaik Java SDK, lihat Praktik terbaik untuk menggunakan AWS SDK untuk Java 2.x di Panduan Peng AWS SDK for Java 2.x embang.