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 konsep yang berbeda termasuk lapisan abstraksi, manajemen konfigurasi, penanganan kesalahan, pengendalian kebijakan coba lagi, dan pengelolaan keep-alive.

Tentang AWS SDK for Java 2.x

Anda dapat mengakses DynamoDB dari Java menggunakan resmi. AWS SDK for Java SDKUntuk Java memiliki dua versi: 1.x dan 2.x. end-of-support Untuk 1.x diumumkan pada 12 Januari 2024. Ini akan memasuki mode pemeliharaan pada 31 Juli 2024 dan akan jatuh tempo pada 31 Desember 2025. end-of-support 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 yang SDK relevan dengan DynamoDB.

Untuk informasi tentang pemeliharaan dan dukungan untuk AWS SDKs, lihat Kebijakan pemeliharaan alat AWS SDK dan matriks dukungan versi Tools di Panduan Referensi Alat AWS SDKs dan.AWS SDKs

AWS SDK for Java 2.x Ini adalah penulisan ulang utama dari basis kode 1.x. SDKUntuk Java 2.x mendukung fitur Java modern, seperti I/O non-blocking yang diperkenalkan di Java 8. SDKUntuk Java 2.x juga menambahkan dukungan untuk implementasi HTTP klien pluggable 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 SDK 2.x menggunakan file. software.amazon.awssdk groupId

Support untuk versi Java

AWS SDK for Java 2.x Ini memberikan dukungan penuh untuk dukungan jangka panjang (LTS) rilis Java.

Memulai dengan AWS SDK for Java 2.x

Tutorial berikut menunjukkan cara menggunakan Apache Maven untuk mendefinisikan dependensi untuk Java 2.x. SDK Tutorial ini juga menunjukkan cara menulis kode yang menghubungkan ke DynamoDB untuk daftar tabel DynamoDB yang tersedia. Tutorial dalam panduan ini didasarkan pada tutorial Memulai dengan AWS SDK for Java 2.x di Panduan AWS SDK for Java 2.x Pengembang. 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 mengatur tutorial ini, ikuti petunjuk di Ikhtisar pengaturan di Panduan AWS SDK for Java 2.x Pengembang. Setelah Anda mengkonfigurasi lingkungan pengembangan Anda dengan akses masuk tunggal untuk Java SDK dan Anda memiliki sesi portal AWS akses aktif, kemudian 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 rintisan.

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 dari 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 kodenya

Kode berikut menunjukkan App kelas yang dibuat Maven. mainMetode ini adalah titik masuk ke dalam aplikasi, yang menciptakan sebuah instance dari 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");
     }
 }

DependencyFactoryKelas yang dibuat Maven berisi metode dynamoDbClient pabrik yang membangun dan mengembalikan sebuah instance. DynamoDbClient DynamoDbClientInstance menggunakan instance dari klien berbasis ApacheHTTP. Ini karena Anda menentukan apache-client kapan Maven meminta Anda untuk HTTP klien 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 sebuah instance Handler dibuat di App kelas, DependencyFactory melengkapi klien DynamoDbClient layanan. Kode Anda menggunakan DynamoDbClient instance untuk memanggil DynamoDB.

Maven menghasilkan Handler kelas berikut dengan komentar. TODO Langkah selanjutnya dalam tutorial menggantikan TODOkomentar 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 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: Bangun dan jalankan aplikasi

Setelah Anda membuat proyek dan berisi Handler kelas lengkap, membangun dan menjalankan aplikasi.

Setelah Anda melihat file, hapus objek, dan kemudian hapus ember.

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 dokumentasi AWS SDK for Java 2.x

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

Antarmuka yang didukung

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

Antarmuka tingkat rendah

Antarmuka tingkat rendah menyediakan one-to-one pemetaan ke layanan yang mendasarinya. API Setiap API DynamoDB tersedia melalui antarmuka ini. Ini berarti bahwa antarmuka tingkat rendah dapat menyediakan fungsionalitas yang 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 PutItemmenyisipkan 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)");
    }
}

Antarmuka tingkat tinggi

Antarmuka tingkat tinggi di dalam disebut DynamoDB Enhanced Client. AWS SDK for Java 2.x 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 tersebut. 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 klien yang disempurnakan DynamoDB di AWS SDK for Java 2.x Panduan API Pengembang.

Contoh berikut PutItemmenggunakan antarmuka tingkat tinggi. Dalam contoh ini, yang DynamoDbBean bernama YourItem menciptakan 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(PutItem.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 for Java 1.x memiliki antarmuka tingkat tinggi sendiri, yang sering disebut oleh kelas utamanya. DynamoDBMapper 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.

Antarmuka tingkat tinggi menggunakan kelas data yang tidak dapat diubah

Fitur pemetaan API klien yang disempurnakan DynamoDB juga bekerja dengan kelas data yang tidak dapat diubah. Kelas yang tidak dapat diubah hanya memiliki getter dan membutuhkan kelas pembangun yang SDK digunakan untuk membuat instance kelas. Kekekalan di Jawa adalah gaya yang umum digunakan yang dapat digunakan pengembang untuk membuat kelas yang tidak memiliki efek samping. Kelas-kelas ini lebih dapat diprediksi dalam perilaku mereka dalam aplikasi multi-threaded yang kompleks. Alih-alih menggunakan @DynamoDbBean anotasi seperti yang ditunjukkan dalamHigh-level interface example, kelas yang tidak dapat diubah menggunakan @DynamoDbImmutable anotasi, yang mengambil kelas pembangun sebagai inputnya.

Contoh berikut mengambil kelas builder DynamoDbEnhancedClientImmutablePutItem sebagai masukan untuk membuat skema tabel. Contoh kemudian memberikan skema sebagai input untuk PutItemAPIpanggilan.

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

Antarmuka tingkat tinggi menggunakan kelas data yang tidak dapat diubah dan pustaka generasi 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 kelas. Builder Pustaka pihak ketiga, 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. AWS SDK Ini selanjutnya menghasilkan peningkatan produktivitas dan keterbacaan kode Anda. Untuk informasi selengkapnya, lihat Menggunakan pustaka pihak ketiga, seperti Lombok di Panduan AWS SDK for Java 2.x Pengembang.

Contoh berikut menunjukkan bagaimana Project Lombok menyederhanakan kode yang diperlukan untuk menggunakan DynamoDB klien ditingkatkan. 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 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 berubah 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;
}

YourImmutableLombokItemKelas menggunakan anotasi berikut yang Project Lombok dan menyediakan: AWS SDK

Antarmuka dokumen

Antarmuka AWS SDK for Java 2.x 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 for Java 1.x, Dokumen, tetapi dengan antarmuka yang didesain ulang.

Berikut ini Document interface example menunjukkan PutItem panggilan yang dinyatakan menggunakan antarmuka Dokumen. Contoh ini 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 sumber daya. DynamoDBTable 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 keseluruhan perilaku default dengan AttributeConverterProvider implementasi kustom. Anda juga dapat mengubah konverter untuk satu atribut. Panduan Referensi AWS SDKs and Tools memberikan rincian 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 memberikan informasi SDK 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 JSON dokumen ke dan dari tipe data Amazon DynamoDB asli, Anda dapat menggunakan metode utilitas berikut:

Membandingkan antarmuka dengan contoh Query

Bagian ini menunjukkan Querypanggilan 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

AWS SDK for Java 2.x Ini menyediakan klien sinkron dan asinkron untuk, Layanan AWS seperti DynamoDB.

DynamoDbEnhancedClientKelas DynamoDbClient dan menyediakan metode sinkron yang memblokir eksekusi thread Anda hingga klien menerima respons dari layanan. Klien ini adalah cara paling mudah untuk berinteraksi dengan DynamoDB jika Anda tidak memerlukan operasi asinkron.

DynamoDbEnhancedAsyncClientKelas DynamoDbAsyncClient and menyediakan metode asinkron yang segera kembali, dan memberikan kontrol kembali ke utas panggilan tanpa menunggu respons. Klien non-pemblokiran memiliki keuntungan yang digunakannya untuk konkurensi tinggi di beberapa utas, yang menyediakan penanganan permintaan I/O yang efisien dengan sumber daya komputasi minimal. Ini meningkatkan throughput dan daya tanggap.

AWS SDK for Java 2.x Menggunakan dukungan asli untuk I/O non-pemblokiran. AWS SDK for Java 1.x harus mensimulasikan I/O non-pemblokiran.

Metode sinkron kembali sebelum respons tersedia, jadi Anda memerlukan cara untuk mendapatkan respons saat sudah siap. Metode asinkron dalam AWS SDK for Java mengembalikan CompletableFutureobjek yang berisi hasil operasi asinkron di masa depan. Ketika Anda memanggil get() atau join() pada CompletableFuture objek-objek ini, kode Anda memblokir 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

HTTPklien

Untuk mendukung setiap klien, ada HTTP klien yang menangani komunikasi dengan klien Layanan AWS. Anda dapat menghubungkan HTTP klien alternatif, memilih salah satu yang memiliki karakteristik yang paling sesuai dengan aplikasi Anda. Beberapa lebih ringan; beberapa memiliki lebih banyak opsi konfigurasi.

Beberapa HTTP klien hanya mendukung penggunaan sinkron, sementara yang lain hanya mendukung penggunaan asinkron. Untuk diagram alur yang dapat membantu Anda memilih HTTP klien optimal untuk beban kerja Anda, lihat rekomendasi HTTP klien di Panduan AWS SDK for Java 2.x Pengembang.

Daftar berikut menyajikan beberapa HTTP klien yang mungkin:

Klien berbasis Apache HTTP

ApacheHttpClientKelas mendukung klien layanan sinkron. Ini adalah HTTP klien default untuk penggunaan sinkron. Untuk informasi tentang mengonfigurasi ApacheHttpClient kelas, lihat Mengkonfigurasi HTTP klien berbasis Apache di Panduan Pengembang.AWS SDK for Java 2.x

URLConnectionberbasis HTTP klien

UrlConnectionHttpClientKelas adalah pilihan lain untuk klien sinkron. Ini memuat lebih cepat daripada HTTP klien berbasis Apache, tetapi memiliki lebih sedikit fitur. Untuk informasi tentang mengonfigurasi UrlConnectionHttpClient kelas, lihat Mengkonfigurasi HTTP klien URLConnection berbasis di Panduan AWS SDK for Java 2.x Pengembang.

Klien berbasis Netty HTTP

NettyNioAsyncHttpClientKelas mendukung klien async. Ini adalah pilihan default untuk penggunaan async. Untuk informasi tentang mengonfigurasi NettyNioAsyncHttpClient kelas, lihat Mengkonfigurasi HTTP klien berbasis Netty di Panduan Pengembang.AWS SDK for Java 2.x

AWS CRTberbasis HTTP klien

Yang lebih baru AwsCrtHttpClient dan AwsCrtAsyncHttpClient kelas dari pustaka AWS Common Runtime (CRT) adalah lebih banyak opsi yang mendukung klien sinkron dan asinkron. Dibandingkan dengan HTTP klien lain, AWS CRT penawaran:

Untuk informasi tentang mengonfigurasi AwsCrtAsyncHttpClient kelas AwsCrtHttpClient dan, lihat Mengonfigurasi HTTP klien AWS CRT berbasis di Panduan AWS SDK for Java 2.x Pengembang.

HTTPKlien AWS CRT berbasis bukan default karena itu akan merusak kompatibilitas mundur untuk aplikasi yang ada. Namun, untuk DynamoDB kami menyarankan Anda menggunakan klien HTTP berbasis untuk penggunaan AWS CRT sinkronisasi dan asinkron.

Untuk pengenalan HTTP klien AWS CRT berbasis, lihat Mengumumkan ketersediaan AWS CRT HTTP Klien AWS SDK for Java 2.x di Blog Alat AWS Pengembang.

Mengonfigurasi klien HTTP

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

Anda mengontrol konfigurasi dengan menyediakan ClientOverrideConfigurationobjek ke Builder kelas klien layanan. Anda akan melihat ini di beberapa contoh kode di bagian berikut.

ClientOverrideConfigurationIni menyediakan pilihan konfigurasi standar. HTTPKlien pluggable yang berbeda memiliki kemungkinan konfigurasi khusus implementasi juga.

Konfigurasi waktu habis

Anda dapat menyesuaikan konfigurasi klien untuk mengontrol berbagai batas waktu yang terkait dengan panggilan layanan. DynamoDB memberikan latensi yang lebih rendah dibandingkan dengan yang lain. Layanan AWS Oleh karena itu, Anda mungkin ingin menyesuaikan properti ini untuk menurunkan nilai batas waktu sehingga Anda dapat gagal dengan cepat jika ada masalah jaringan.

Anda dapat menyesuaikan perilaku terkait latensi menggunakan ClientOverrideConfiguration pada klien DynamoDB atau dengan mengubah opsi konfigurasi terperinci pada implementasi klien yang mendasarinya. HTTP

Anda dapat mengonfigurasi properti berdampak berikut menggunakan: ClientOverrideConfiguration

AWS SDK for Java 2.x Ini memberikan nilai default untuk beberapa opsi batas waktu, seperti batas waktu koneksi dan batas waktu soket. SDKTidak memberikan nilai default untuk batas waktu API panggilan atau batas waktu percobaan API panggilan individual. Jika batas waktu ini tidak diatur dalamClientOverrideConfiguration, maka nilai batas waktu soket akan SDK digunakan sebagai gantinya untuk batas waktu API panggilan keseluruhan. Batas waktu soket memiliki nilai default 30 detik.

RetryMode

Konfigurasi lain yang terkait dengan konfigurasi batas waktu yang harus Anda pertimbangkan adalah objek RetryMode konfigurasi. Objek konfigurasi ini berisi kumpulan perilaku coba lagi.

SDKUntuk Java 2.x mendukung mode coba lagi berikut:

Anda dapat menemukan definisi yang diperluas dari mode coba lagi ini dalam topik perilaku Coba lagi di Panduan Referensi Alat AWS SDKs dan Alat.

Coba lagi kebijakan

Semua RetryMode konfigurasi memiliki RetryPolicy, yang dibangun berdasarkan satu atau lebih RetryConditionkonfigurasi. TokenBucketRetryConditionIni sangat penting untuk perilaku coba lagi implementasi klien SDK DynamoDB. Kondisi ini membatasi jumlah percobaan ulang yang SDK dibuat menggunakan algoritma token bucket. Bergantung pada mode coba lagi yang dipilih, pengecualian pembatasan mungkin atau mungkin tidak mengurangi token dari. TokenBucket

Ketika klien menemukan kesalahan yang dapat dicoba ulang, seperti pengecualian pelambatan atau kesalahan server sementara, maka secara otomatis mencoba ulang permintaan tersebutSDK. Anda dapat mengontrol berapa kali dan seberapa cepat percobaan ulang ini terjadi.

Saat mengkonfigurasi klien, Anda dapat memberikan RetryPolicy yang mendukung parameter berikut:

Kode berikut menyediakan kebijakan coba lagi alternatif. Ini menentukan total lima percobaan ulang (enam permintaan total). Percobaan ulang pertama harus dilakukan setelah penundaan sekitar 100 ms, dengan setiap percobaan lagi tambahan menggandakan waktu itu secara eksponensial, hingga penundaan maksimum satu detik.

DynamoDbClient client = DynamoDbClient.builder()
    .overrideConfiguration(ClientOverrideConfiguration.builder()
        .retryPolicy(RetryPolicy.builder()
            .backoffStrategy(FullJitterBackoffStrategy.builder()
                .baseDelay(Duration.ofMillis(100))
                .maxBackoffTime(Duration.ofSeconds(1))
                .build())
            .numRetries(5)
            .build())
        .build())
    .build();

DefaultsMode

Properti batas waktu yang ClientOverrideConfiguration dan RetryMode tidak dikelola biasanya dikonfigurasi secara implisit dengan menentukan. 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 HTTP komunikasi, perilaku coba lagi, pengaturan titik akhir Regional layanan, dan kemungkinan konfigurasi terkait apa punSDK. Saat Anda menggunakan fitur ini, Anda bisa mendapatkan default konfigurasi baru yang disesuaikan dengan skenario penggunaan umum.

Mode default distandarisasi di semua. AWS SDKs SDKUntuk Java 2.x mendukung mode default berikut:

Anda dapat mengonfigurasi mode default dengan cara berikut:

Konfigurasi Smart default di Panduan Referensi Alat AWS SDKs dan menyediakan daftar properti konfigurasi dan nilai defaultnya dalam mode default yang berbeda.

Anda memilih nilai mode default berdasarkan karakteristik aplikasi Anda dan interaksi dengan Layanan AWS aplikasi.

Nilai-nilai ini dikonfigurasi dengan berbagai pilihan Layanan AWS dalam pikiran. Untuk penerapan DynamoDB tipikal di mana tabel dan aplikasi DynamoDB 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();

Konfigurasi Keep-Alive

Mengaktifkan keep-alive dapat mengurangi latensi dengan menggunakan kembali koneksi. Ada dua jenis keep-alive: HTTP Keep-Alive dan Keep-Alive. TCP

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

URLConnectionberbasis HTTP klien

Setiap klien sinkron yang menggunakan HTTP klien URLConnection berbasis HttpURLConnectiontidak 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();

Penanganan kesalahan

Ketika datang ke penanganan pengecualian, AWS SDK for Java 2.x menggunakan pengecualian runtime (tidak dicentang).

Pengecualian dasar, yang mencakup semua SDK pengecualian, adalah SdkServiceException, yang meluas dari Java tidak dicentang. RuntimeException Jika Anda menangkap ini, Anda akan menangkap semua pengecualian yang SDK dilemparkan.

SdkServiceExceptionmemiliki subclass yang disebut AwsServiceException. Subkelas ini menunjukkan masalah apa pun dalam komunikasi dengan. Layanan AWS Ini memiliki subclass 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 lain. SDK

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 permintaan yang lebih umum DynamoDbException dilemparkan. Dalam kedua kasus tersebut, Anda dapat menentukan apakah pelambatan menyebabkan pengecualian dengan memeriksa apakah isThrottlingException() pengembalian. true

Tergantung pada kebutuhan aplikasi Anda, Anda dapat menangkap semua AwsServiceException atau DynamoDbException instance. Namun, Anda sering membutuhkan perilaku yang berbeda dalam situasi yang berbeda. Logika untuk menangani kegagalan pemeriksaan kondisi berbeda dari itu untuk 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 Kesalahan Umum di Referensi Amazon API DynamoDB. APIReferensi juga memberikan kemungkinan kesalahan yang tepat untuk setiap API operasi, seperti untuk Queryoperasi. Untuk informasi tentang menangani pengecualian, lihat Penanganan pengecualian untuk Panduan AWS SDK for Java 2.x Pengembang. AWS SDK for Java 2.x

AWS ID permintaan

Setiap permintaan menyertakan ID permintaan, yang dapat berguna untuk ditarik jika Anda bekerja dengan AWS Support untuk mendiagnosis masalah. Setiap pengecualian yang berasal dari SdkServiceException memiliki requestId()metode yang tersedia untuk mengambil ID permintaan.

Pencatatan log

Menggunakan logging asalkan penyediaan dapat SDK 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 mengkonfigurasi level dengan salah satu dariTRACE,DEBUG,INFO,WARN,ERROR,ALL, atauOFF. Level yang dikonfigurasi berlaku untuk logger itu dan turun ke hierarki logger.

Untuk logging nya, AWS SDK for Java 2.x menggunakan Simple Logging Façade for Java ()SLF4J. Ini bertindak sebagai lapisan abstraksi di sekitar logger lain, dan Anda dapat menggunakannya untuk mencolokkan logger yang Anda inginkan. Untuk petunjuk tentang memasukkan logger, lihat panduan SLF4Jpengguna.

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 disertakan dalam SLF4J output secara default ke System.err dan default ke tingkat log. INFO

Kami menyarankan Anda mengatur level WARN untuk setiap penerapan produksi software.amazon.awssdk untuk menangkap pesan penting apa pun dari pustaka SDK klien sambil membatasi kuantitas keluaran.

Jika tidak SLF4J dapat menemukan logger yang didukung di jalur kelas (tidak ada SLF4J pengikatan), maka defaultnya adalah implementasi tanpa operasi. Implementasi ini menghasilkan pencatatan pesan untuk System.err menjelaskan yang tidak SLF4J 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 atau. org.slf4j.slf4j-simple org.apache.logging.log4j.log4j-slf4j2-imp

Untuk informasi tentang cara mengonfigurasi loggingSDK, termasuk menambahkan dependensi logging ke konfigurasi aplikasi Anda, lihat Logging with the SDK for Java 2.x di Panduan Pengembang AWS SDK for Java .

Konfigurasi berikut dalam Log4j2.xml file menunjukkan cara menyesuaikan perilaku logging jika Anda menggunakan logger Apache Log4j 2. Konfigurasi ini menetapkan level root logger keWARN. Semua logger dalam hierarki mewarisi level log ini, termasuk logger. software.amazon.awssdk

Secara default, output masuk keSystem.out. Dalam contoh berikut, kita masih mengganti appender Log4j keluaran default untuk menerapkan log4j yang disesuaikan. PatternLayout

Contoh file Log4j2.xml konfigurasi

Konfigurasi berikut mencatat pesan ke konsol di WARN tingkat 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 minta pencatatan ID

Ketika terjadi kesalahan, Anda dapat menemukan permintaan IDs dalam pengecualian. Namun, jika Anda menginginkan permintaan IDs untuk permintaan yang tidak menghasilkan pengecualian, Anda dapat menggunakan logging.

Permintaan keluaran software.amazon.awssdk.request logger IDs di tingkat tersebut. DEBUG Contoh berikut memperluas sebelumnya configuration example untuk menjaga level root logger padaERROR, level atWARN, dan level at. software.amazon.awssdk software.amazon.awssdk.request DEBUG Menyetel level ini membantu menangkap permintaan IDs 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 output 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 Querydan 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 terakhir. Batas ini menentukan berapa banyak item untuk membaca dari tabel sebelum penyaringan diterapkan. Jika Anda menginginkan tepat 10 item setelah pemfilteran, tidak ada cara untuk menentukannya. Anda hanya dapat mengontrol jumlah yang telah difilter sebelumnya dan memeriksa sisi klien saat Anda benar-benar mengambil 10 item. Terlepas dari batasnya, respons selalu memiliki ukuran maksimum 1 MB.

A LastEvaluatedKey dapat dimasukkan dalam API tanggapan. 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 denganAPI, Anda dapat mengambil ini LastEvaluatedKey dan meneruskannya ke panggilan tindak lanjut ExclusiveStartKey untuk membaca potongan berikutnya dari titik awal itu. Jika LastEvaluatedKey tidak dikembalikan, itu berarti tidak ada lagi item yang cocok dengan Scan API panggilan Query atau.

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

Ini 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, QueryPaginatorseperti ScanPaginatordan, mengurus SDK pagination. Jenis pengembalian metode ini adalah iterable khusus yang dapat Anda gunakan untuk mengulangi semua halaman. SDKSecara internal menangani panggilan layanan untuk Anda. Menggunakan Java StreamAPI, Anda dapat menangani hasil QueryPaginator seperti yang ditunjukkan pada contoh berikut.

QueryPublisher queryPublisher =
    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());

queryPublisher.items().subscribe(item ->
    System.out.println(item.get("itemData"))).join();

Anotasi kelas data

Java SDK menyediakan beberapa anotasi yang dapat Anda masukkan pada atribut kelas data Anda. Anotasi ini mempengaruhi bagaimana 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.