Programmieren von DynamoDB mit dem AWS SDK for Java 2.x

Dieser Programmierleitfaden bietet eine Einführung für Entwickler, die Amazon DynamoDB mit Java verwenden möchten. Es werden verschiedene Konzepte wie Abstraktionsschichten, Konfigurationsmanagement, Fehlerbehandlung, Steuerung von Wiederholungsrichtlinien und Verwaltung von Keepalive-Verbindungen behandelt.

Über die AWS SDK for Java 2.x

Sie können von Java aus mit dem offiziellen auf DynamoDB zugreifen. AWS SDK für Java Das SDK für Java ist in zwei Versionen verfügbar: 1.x und 2.x. Das Supportende für Version 1.x wurde am 12. Januar 2024 angekündigt. Sie tritt am 31. Juli 2024 in den Wartungsmodus und wird am 31. Dezember 2025 endgültig eingestellt. Für neue Entwicklungen wird dringend empfohlen, Version 2.x zu verwenden, die erstmals 2018 veröffentlicht wurde. Dieses Handbuch richtet sich ausschließlich an Version 2.x und konzentriert sich auf die für DynamoDB relevanten Teile des SDK.

Informationen zu Wartung und Support für die AWS SDKs finden Sie unter Wartungsrichtlinie für AWS SDK und Tools und Matrix zur Unterstützung der Versionen von AWS SDKs und Tools im Referenzhandbuch für AWS SDKs und Tools.

Das AWS SDK for Java 2.x ist eine grundlegende Neufassung der 1.x-Codebasis. Das SDK for Java 2.x unterstützt moderne Java-Funktionen, wie z. B. das in Java 8 I/O eingeführte Non-Blocking. Das SDK for Java 2.x bietet auch Unterstützung für steckbare HTTP-Client-Implementierungen, um mehr Flexibilität bei Netzwerkverbindungen und Konfigurationsoptionen zu bieten.

Eine bemerkenswerte Änderung zwischen dem SDK for Java 1.x und dem SDK for Java 2.x ist die Verwendung eines neuen Paketnamens. Das Java 1.x SDK verwendet den com.amazonaws-Paketnamen, während das Java 2.x SDK software.amazon.awssdk verwendet. In ähnlicher Weise verwenden Maven-Artefakte für das Java 1.x-SDK die com.amazonaws-groupId, während Java 2.x-SDK-Artefakte die software.amazon.awssdk-groupId verwenden.

Support für Java-Versionen

Das AWS SDK for Java 2.x bietet volle Unterstützung für Java-Versionen mit langfristigem Support (LTS).

Erste Schritte mit dem AWS SDK for Java 2.x

Das folgende Tutorial zeigt Ihnen, wie Sie Apache Maven verwenden, um Abhängigkeiten für das SDK für Java 2.x zu definieren. Dieses Tutorial zeigt Ihnen auch, wie Sie den Code schreiben, der eine Verbindung zu DynamoDB herstellt, um die verfügbaren DynamoDB-Tabellen aufzulisten. Das Tutorial in diesem Handbuch basiert auf dem Tutorial Erste Schritte mit dem AWS SDK for Java 2.x im AWS SDK for Java 2.x -Entwicklerhandbuch. Wir haben dieses Tutorial so überbearbeitet, dass DynamoDB statt Amazon S3 aufgerufen wird.

Schritt 1: Einrichtung für dieses Tutorial

Bevor Sie mit diesem Tutorial beginnen, brauchen Sie Folgendes:

Folgen Sie zur Einrichtung dieses Tutorials den Anleitungen in der Übersicht über die Einrichtung im AWS SDK for Java 2.x -Entwicklerhandbuch. Nachdem Sie Ihre Entwicklungsumgebung mit Single Sign-On-Zugriff für das Java SDK konfiguriert haben und eine aktive AWS -Access-Portal-Sitzung eingerichtet haben, fahren Sie mit Schritt 2 dieses Tutorials fort.

Schritt 2: Erstellen des Projekts

Um das Projekt für dieses Tutorial zu erstellen, führen Sie einen Maven-Befehl aus, der Sie zur Eingabe der Konfiguration des Projekts auffordert. Nachdem alle Daten eingegeben und bestätigt wurden, beendet Maven den Aufbau des Projekts, indem es eine pom.xml-Datei und Stub-Java-Dateien erstellt.

Maven erstellt einen Projektordner namens getstarted, der auf dem von Ihnen eingegebenen artifactId-Wert basiert. Suchen Sie im getstarted-Ordners nach einer Datei namens README.md, die Sie überprüfen können, nach einer pom.xml-Datei und einem src-Verzeichnis.

Maven erstellt den folgenden Verzeichnisbaum.

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

Unten sehen Sie die Inhalte der pom.xml-Projektdatei.

<?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>

Schritt 3: Schreiben des Codes

Der folgende Code zeigt die App-Klasse, die von Maven erstellt wird. Die main-Methode ist der Einstiegspunkt in die Anwendung, die eine Instance der Handler-Klasse erstellt und dann ihre sendRequest-Methode aufruft.

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

Die DependencyFactory-Klasse, die Maven erstellt, enthält die dynamoDbClient-Factory-Methode, die eine DynamoDbClient-Instance erstellt und zurückgibt. Die DynamoDbClient Instanz verwendet eine Instanz des Apache-based HTTP-Clients. Dies liegt daran, dass Sie apache-client angegeben haben, als Maven Sie nach dem zu verwendenden HTTP-Client gefragt hat.

Der folgende Code zeigt die Klasse DependencyFactory.

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

Die Handler-Klasse enthält die Hauptlogik Ihres Programms. Wenn eine Instance von Handler in der Klasse App erstellt wird, stellt DependencyFactory den Service-Client für DynamoDbClient bereit. Ihr Code verwendet die DynamoDbClient-Instance, um DynamoDB aufzurufen.

Maven generiert die folgende Handler-Klasse mit einem TODO-Kommentar. Der nächste Schritt im Tutorial ersetzt den TODO-Kommentar durch Code.

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

Um die Logik zu ergänzen, ersetzen Sie den gesamten Inhalt der Klasse Handler durch den folgenden Code: Die Methode sendRequest ist vollständig implementiert, und die erforderlichen Importe werden hinzugefügt.

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

Schritt 4: Anwendung erstellen und ausführen

Nachdem Sie das Projekt erstellt haben und es die komplette Handler-Klasse enthält, erstellen Sie die Anwendung und führen Sie sie aus.

Nachdem Sie die Datei angezeigt haben, löschen Sie das Objekt und anschließend den Bucket.

Herzlichen Glückwunsch

Wenn Ihr Maven-Projekt ohne Fehler erstellt und ausgeführt wurde, dann herzlichen Glückwunsch! Sie haben erfolgreich Ihre erste Java-Anwendung mit dem SDK for Java 2.x erstellt.

Bereinigen

Um die während dieses Tutorials erstellten Ressourcen zu bereinigen, löschen Sie den Projektordner getstarted.

Überprüfung der AWS SDK for Java 2.x Dokumentation

Das AWS SDK for Java 2.x -Entwicklerhandbuch deckt alle Aspekte des SDK in allen AWS-Services ab. Wir empfehlen, dass Sie sich mit den folgenden Themen vertraut machen:

Unterstützte Schnittstellen

Die AWS SDK for Java 2.x unterstützt die folgenden Schnittstellen, abhängig von der gewünschten Abstraktionsebene.

Low-level Schnittstelle

Die Low-Level-Schnittstelle bietet eine Eins-zu-Eins-Zuordnung zur zugrunde liegenden Service-API. Jede DynamoDB-API ist über diese Schnittstelle verfügbar. Das bedeutet, dass die Low-Level-Schnittstelle vollständige Funktionalität bieten kann, aber häufig ausführlicher und komplexer in der Anwendung ist. Beispielsweise müssen Sie die .s()-Funktionen zum Speichern von Zeichenketten, und die .n()-Funktionen zum Speichern von Zahlen verwenden. Das folgende Beispiel PutItemfügt ein Element mithilfe der Low-Level-Schnittstelle ein.

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 Schnittstelle

Die High-Level-Schnittstelle im AWS SDK for Java 2.x wird als DynamoDB Enhanced Client bezeichnet. Diese Schnittstelle ermöglicht eine idiomatischere und natürlichere Programmerfahrung.

Der erweiterte Client bietet eine Möglichkeit, clientseitige Datenklassen mit den dafür vorgesehenen DynamoDB-Tabellen zu verknüpfen. Sie definieren die Beziehungen zwischen Tabellen und ihren jeweiligen Modellklassen im Code. Anschließend können Sie sich darauf verlassen, dass das SDK die Umwandlung der Datentypen übernimmt. Weitere Informationen zum erweiterten Client finden Sie unter API für den erweiterten DynamoDB-Client im AWS SDK for Java 2.x -Entwicklerhandbuch.

Im folgenden Beispiel wird die High-Level-Schnittstelle PutItemverwendet. In diesem Beispiel erstellt die DynamoDbBean mit dem Namen YourItem ein TableSchema, das ihre direkte Verwendung als Eingabe für den putItem()-Aufruf ermöglicht.

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

Die AWS SDK für Java Version 1.x hat ihre eigene High-Level-Schnittstelle, die oft mit ihrer Hauptklasse DynamoDBMapper bezeichnet wird. Das AWS SDK for Java 2.x wird in einem separaten Paket (und einem Maven-Artefakt) mit dem Namen veröffentlicht. software.amazon.awssdk.enhanced.dynamodb Das Java SDK 2.x wird oft über seine Hauptklasse DynamoDbEnhancedClient referenziert.

High-level Schnittstelle, die unveränderliche Datenklassen verwendet

Die Mapping-Funktion der erweiterten DynamoDB-Client-API funktioniert auch mit unveränderlichen Datenklassen. Eine unveränderliche Klasse hat nur Getter und erfordert eine Builder-Klasse, die das SDK verwendet, um Instances der Klasse zu erstellen. Unveränderlichkeit ist ein in Java häufig verwendeter Programmierstil, mit dem Entwickler Klassen erstellen können, die keine Nebeneffekte verursachen. Solche Klassen verhalten sich in komplexen, nebenläufigen Anwendungen vorhersehbarer. Anstelle der Annotation @DynamoDbBean, wie im Beispiel zur High-level interface example gezeigt, verwenden unveränderliche Klassen die @DynamoDbImmutable-Annotation, die die zugehörige Builder-Klasse als Eingabe erhält.

Im folgenden Beispiel wird die Builder-Klasse DynamoDbEnhancedClientImmutablePutItem als Eingabe verwendet, um ein Tabellenschema zu erstellen. Das Beispiel stellt dann das Schema als Eingabe für den PutItemAPI-Aufruf bereit.

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

Im folgenden Beispiel wird die unveränderliche Datenklasse gezeigt.

@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 Schnittstelle, die unveränderliche Datenklassen und Bibliotheken zur Generierung von Boilerplates von Drittanbietern verwendet

Unveränderliche Datenklassen (wie im vorherigen Beispiel gezeigt) erfordern etwas Boilerplate-Code. Zum Beispiel die Getter- und Setter-Logik für die Datenklassen zusätzlich zu den Klassen. Builder Third-party Bibliotheken wie Project Lombok können Ihnen dabei helfen, diese Art von Standardcode zu generieren. Wenn Sie den Großteil des Standardcodes reduzieren, können Sie die Menge an Code einschränken, die für die Arbeit mit unveränderlichen Datenklassen und dem SDK benötigt wird. AWS Dies führt zu höherer Produktivität und verbessert die Lesbarkeit Ihres Codes. Weitere Informationen finden Sie unter Verwenden von externen Bibliotheken wie Lombok im -Entwicklerhandbuch.

Im folgenden Beispiel wird gezeigt, wie Project Lombok den Code vereinfacht, der für die Nutzung der erweiterten DynamoDB-Client-API erforderlich ist.

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

Das folgende Beispiel zeigt das unveränderliche Datenobjekt der unveränderlichen Datenklasse.

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

Die YourImmutableLombokItem Klasse verwendet die folgenden Anmerkungen, die Project Lombok und das SDK bereitstellen: AWS

Dokumentschnittstelle

Die AWS SDK for Java 2.x Document-Schnittstelle macht die Angabe von Datentypdeskriptoren überflüssig. Die Datentypen ergeben sich aus der Semantik der Daten selbst. Diese Dokumentschnittstelle ähnelt der Dokumentschnittstelle von AWS SDK für Java 1.x, verfügt jedoch über eine neu gestaltete Oberfläche.

Im Folgenden Document interface example wird der über die Dokumentschnittstelle ausgedrückte PutItem-Aufruf dargestellt. Das Beispiel verwendet auch. EnhancedDocument Um Befehle gegen eine DynamoDB-Tabelle mit der erweiterten Dokument-API auszuführen, müssen Sie die Tabelle zunächst mit Ihrem Dokumenttabellenschema verknüpfen, um ein DynamoDBTable-Ressourcenobjekt zu erstellen. Der Tabellenschema-Builder für Dokumente erfordert den Primärschlüssel des Indexes sowie Anbieter für Attributkonverter.

Sie können AttributeConverterProvider.defaultProvider() verwenden, um Dokumentattribute mit Standardtypen zu konvertieren. Das allgemeine Standardverhalten lässt sich durch eine benutzerdefinierte AttributeConverterProvider-Implementierung ändern. Ebenso können Sie den Konverter für ein einzelnes Attribut anpassen. Weitere Details und Beispiele zur Verwendung benutzerdefinierter Konverter finden Sie im AWS -SDKs und Referenzleitfaden für Tools. Ihr Hauptzweck besteht darin, Attribute Ihrer Domänenklassen zu unterstützen, für die kein Standardkonverter verfügbar ist. Mit einem benutzerdefinierten Konverter können Sie dem SDK die nötigen Informationen bereitstellen, um Daten in DynamoDB zu schreiben oder daraus zu lesen.

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

}

Um JSON-Dokumente in native Amazon-DynamoDB-Datentypen zu konvertieren und umgekehrt, können Sie die folgenden Hilfsmethoden verwenden:

Vergleich von Schnittstellen mit einem Query-Beispiel

Dieser Abschnitt zeigt den gleichen Query-Aufruf, der über die verschiedenen Schnittstellen ausgedrückt wird. Beachten Sie Folgendes, um die Ergebnisse dieser Abfragen zu optimieren:

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

Weitere Codebeispiele

Weitere Beispiele zur Verwendung von DynamoDB mit dem AWS SDK für Java 2.x finden Sie in den folgenden Codebeispiel-Repositories:

Synchrone und asynchrone Programmierung

Der AWS SDK for Java 2.x bietet sowohl synchrone als auch asynchrone Clients für AWS-Services, z. B. DynamoDB.

Die Klassen DynamoDbClient und DynamoDbEnhancedClient bieten synchrone Methoden, die die Ausführung Ihres Threads blockieren, bis der Client eine Antwort vom Service erhält. Dieser Client ist die einfachste Möglichkeit, mit DynamoDB zu arbeiten, wenn Sie keine asynchronen Operationen benötigen.

Die Klassen DynamoDbAsyncClient und DynamoDbEnhancedAsyncClient bieten asynchrone Methoden, die sofort reagieren und die Kontrolle an den aufrufenden Thread zurückgeben, ohne auf eine Antwort zu warten. Der nicht blockierende Client hat den Vorteil, dass er für eine hohe Parallelität innerhalb weniger Threads verwendet wird, was eine effiziente Bearbeitung von I/O Anfragen mit minimalen Rechenressourcen ermöglicht. Dies verbessert den Durchsatz und die Reaktionsfähigkeit.

Der AWS SDK for Java 2.x verwendet die native Unterstützung für die Nichtblockierung. I/O Die Version AWS SDK für Java 1.x musste das Blockieren ohne Blockierung simulieren. I/O

Die asynchronen Methoden kehren zurück, bevor eine Antwort verfügbar ist. Sie benötigen also eine Möglichkeit, die Antwort zu erhalten, wenn sie bereit ist. Diese Methoden AWS SDK für Java geben ein CompletableFutureObjekt zurück, das die Ergebnisse der asynchronen Operation in der future enthält. Wenn Sie get() oder join() auf diesen CompletableFuture-Objekten aufrufen, blockiert Ihr Code, bis das Ergebnis verfügbar ist. Wenn Sie diese Methoden gleichzeitig mit der Anfrage aufrufen, verhält sich der Code ähnlich wie bei einem normalen synchronen Aufruf.

Weitere Informationen zur asynchronen Programmierung finden Sie unter Verwenden der asynchronen Programmierung im AWS SDK for Java 2.x -Entwicklerhandbuch.

HTTP-Clients

Zur Unterstützung jedes Clients gibt es einen HTTP-Client, der die Kommunikation mit den AWS-Servicesübernimmt. Sie können alternative HTTP-Clients einbinden und dabei denjenigen auswählen, der am besten zu den Anforderungen Ihrer Anwendung passt. Einige sind besonders ressourcenschonend, andere bieten umfangreiche Konfigurationsmöglichkeiten.

Einige HTTP-Clients unterstützen ausschließlich die synchrone Nutzung, während andere nur für die asynchrone Verwendung geeignet sind. Ein Diagramm, das Ihnen bei der Auswahl des optimalen HTTP-Clients für Ihre Workload hilft, finden Sie unter Empfehlungen zu HTTP-Clients im AWS SDK for Java 2.x -Entwicklerhandbuch.

In der folgenden Liste sehen Sie einige der möglichen HTTP-Clients:

Apache-based HTTP-Client

Die ApacheHttpClient-Klasse unterstützt synchrone Service-Clients. Dies ist der Standard-HTTP-Client für die synchrone Verwendung. Informationen zur Konfiguration der ApacheHttpClient Klasse finden Sie unter Konfiguration des Apache-based HTTP-Clients im AWS SDK for Java 2.x Entwicklerhandbuch.

Auf URLConnection basierender HTTP-Client

Die UrlConnectionHttpClient-Klasse ist eine weitere Option für synchrone Clients. Er wird schneller geladen als der Apache-based HTTP-Client, hat aber weniger Funktionen. Informationen zur Konfiguration der UrlConnectionHttpClient Klasse finden Sie unter Konfiguration des URLConnection-based HTTP-Clients im AWS SDK for Java 2.x Entwicklerhandbuch.

Netty-based HTTP-Client

Die NettyNioAsyncHttpClient-Klasse unterstützt asynchrone Clients. Dies ist die Standardauswahl für die asynchrone Verwendung. Informationen zur Konfiguration der NettyNioAsyncHttpClient Klasse finden Sie unter Konfiguration des Netty-based HTTP-Clients im AWS SDK for Java 2.x Entwicklerhandbuch.

AWS CRT-based HTTP-Client

Die neueren AwsCrtHttpClient und die AwsCrtAsyncHttpClient Klassen aus den AWS Common Runtime (CRT) -Bibliotheken sind weitere Optionen, die synchrone und asynchrone Clients unterstützen. Im Vergleich zu anderen HTTP-Clients bietet CRT: AWS

Informationen zur Konfiguration der AwsCrtAsyncHttpClient Klassen AwsCrtHttpClient und finden Sie unter Konfiguration der AWS CRT-based HTTP-Clients im AWS SDK for Java 2.x Entwicklerhandbuch.

Der AWS CRT-based HTTP-Client ist nicht der Standard, da dies die Abwärtskompatibilität vorhandener Anwendungen beeinträchtigen würde. Für DynamoDB empfehlen wir jedoch, den AWS CRT-based HTTP-Client sowohl für synchrone als auch asynchrone Zwecke zu verwenden.

Eine Einführung in den AWS CRT-based HTTP-Client finden Sie unter Ankündigung der Verfügbarkeit des AWS CRT-HTTP-Clients im Blog zu AWS SDK for Java 2.x den Entwicklertools.AWS

Konfigurieren eines HTTP-Clients

Beim Konfigurieren eines Clients können Sie verschiedene Konfigurationsoptionen angeben, darunter:

Sie steuern die Konfiguration, indem Sie der Service-Client-Klasse Builder ein ClientOverrideConfiguration-Objekt bereitstellen. Sie werden dies in einigen Codebeispielen in den folgenden Abschnitten sehen.

ClientOverrideConfiguration bietet Standardkonfigurationsoptionen. Die verschiedenen einsteckbaren HTTP-Clients verfügen zusätzlich über implementierungsspezifische Optionen.

Timeout-Konfiguration

Sie können die Client-Konfiguration anpassen, um verschiedene Timeout-Einstellungen für Serviceaufrufe zu steuern. DynamoDB im Vergleich zu anderen AWS-Services geringere Latenzen. Darum empfiehlt es sich, diese Eigenschaften auf niedrigere Timeout-Werte zu setzen, um bei Netzwerkproblemen schnell zu reagieren.

Das latenzbezogene Verhalten lässt sich entweder über ClientOverrideConfiguration am DynamoDB-Client oder durch detaillierte Einstellungen am zugrunde liegenden HTTP-Client vornehmen.

Folgende wichtige Eigenschaften können über ClientOverrideConfiguration konfiguriert werden:

Das AWS SDK for Java 2.x bietet Standardwerte für einige Timeout-Optionen, wie Verbindungs-Timeout und Socket-Timeouts. Das SDK bietet keine Standardwerte für Timeouts bei API-Aufrufen oder Timeouts für einzelne API-Aufrufversuche. Wenn diese Timeouts nicht explizit in der ClientOverrideConfiguration gesetzt werden, verwendet das SDK stattdessen den Socket-Timeout-Wert als Gesamtzeitlimit für den API-Aufruf. Der Standardwert für den Socket-Timeout beträgt 30 Sekunden.

RetryMode

Eine weitere Einstellung im Zusammenhang mit der Timeout-Konfiguration, die Sie berücksichtigen sollten, ist das Konfigurationsobjekt RetryMode. Dieses Konfigurationsobjekt enthält eine Sammlung von Wiederholungsverhalten.

Das SDK for Java 2.x unterstützt die folgenden Wiederholungsmodi:

Eine ausführlichere Beschreibung dieser Retry-Modi finden Sie im Thema Wiederholungsverhalten im Referenzhandbuch für AWS -SDKs und Tools.

Versuchen Sie es erneut mit Strategien

Jeder Wiederholungsmodus wird durch eine Wiederholungsstrategie implementiert. Die API für Wiederholungsstrategien (das software.amazon.awssdk.retries Paket) ersetzt die ältere API für Wiederholungsrichtlinien (und in). RetryPolicy RetryCondition software.amazon.awssdk.core.retry Bestehende RetryPolicy Konfigurationen funktionieren weiterhin — das SDK passt sie an eine Wiederholungsstrategie an — aber neuer Code sollte a verwenden. RetryStrategy Das AWS SDK for Java 2.x bietet drei integrierte Strategien:

Weitere Informationen finden Sie unter Konfigurieren des Wiederholungsverhaltens im AWS SDK for Java 2.x.

Wenn ein Client auf einen wiederholbaren Fehler stößt, z B. eine Drosselung oder einen temporären Serverfehler, wiederholt das SDK die Anfrage automatisch. Sie können steuern, wie oft und wie schnell diese Wiederholungsversuche erfolgen, indem Sie die Wiederholungsstrategie wie folgt anpassen:

Der folgende Code konfiguriert einen DynamoDB-Client mit einer standardmäßigen Wiederholungsstrategie, die auf maximal sechs Versuche (der erste Versuch plus fünf Wiederholungen) und einem exponentiellen Backoff, der bei 100 ms beginnt und auf eine Sekunde begrenzt ist, angepasst ist.

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

Die Timeout-Eigenschaften, die nicht durch ClientOverrideConfiguration oder RetryMode gesteuert werden, werden in der Regel implizit über die Angabe eines DefaultsMode konfiguriert.

Mit AWS SDK for Java 2.x (Version 2.17.102 oder höher) wurde die Unterstützung für eingeführt. DefaultsMode Diese Funktion bietet eine Reihe von Standardwerten für häufig konfigurierbare Einstellungen, z. B. HTTP-Kommunikationseinstellungen, Wiederholungsverhalten, regionale Endpunkteinstellungen des Dienstes und möglicherweise jede Konfiguration. SDK-related Wenn Sie dieses Feature verwenden, können Sie neue Konfigurationsstandardwerte abrufen, die auf gängige Nutzungsszenarien zugeschnitten sind.

Die Standardmodi sind für alle AWS SDKs standardisiert. Das SDK for Java 2.x unterstützt die folgenden Wiederholungsmodi:

Sie können den Standardmodus folgendermaßen konfigurieren:

Unter Smart-Konfigurationsstandardwerte im Referenzhandbuch für AWS -SDKs und Tools wird eine Liste der Konfigurationseigenschaften und ihrer Standardwerte in den verschiedenen Standardmodi bereitgestellt.

Sie wählen den Standardmoduswert auf der Grundlage der Eigenschaften Ihrer Anwendung und der Art, mit der AWS-Service die Anwendung interagiert.

Bei der Konfiguration dieser Werte wurde eine breite Palette von Faktoren berücksichtigt AWS-Services . Für eine typische DynamoDB-Bereitstellung, bei der sowohl Ihre DynamoDB-Tabellen als auch Ihre Anwendung in derselben Region bereitgestellt sind, ist der Modus in-region unter den standard-Standardmodi am relevantesten.

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 Konfiguration

Durch die Aktivierung von Keepalive können Latenzen reduziert werden, indem Verbindungen wiederverwendet werden. Es gibt zwei verschiedene Arten von Keep-Alive: HTTP Keep-Alive und TCP. Keep-Alive

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

Auf URLConnection basierender HTTP-Client

Jeder synchrone Client, der den URLConnection-basierten HTTP-Client HttpURLConnection verwendet, verfügt nicht über einen Mechanismus zur Aktivierung von Keepalive.

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

Fehlerbehandlung

Bei der Ausnahmebehandlung werden Laufzeitausnahmen (ungeprüfte) AWS SDK for Java 2.x verwendet.

Die Basisausnahme, die alle SDK-Ausnahmen abdeckt, ist SdkServiceException, die von der Java-Laufzeitklasse RuntimeException erbt. Wenn Sie diese Ausnahme abfangen, fangen Sie alle vom SDK ausgelösten Ausnahmen ab.

SdkServiceException hat eine Unterklasse namens AwsServiceException. Diese Unterklasse weist auf Probleme bei der Kommunikation mit dem AWS-Service hin. Eine weitere Unterklasse ist DynamoDbException, die auf ein Problem bei der Kommunikation mit DynamoDB hinweist. Wenn Sie diese Ausnahme abfangen, fangen Sie alle DynamoDB-bezogenen Ausnahmen, jedoch keine anderen SDK-Ausnahmen ab.

Unter DynamoDbException gibt es noch spezifischere Ausnahmetypen. Einige betreffen Operationen auf Steuerungsebene, z. B. TableAlreadyExistsException. Andere gelten für Operationen auf Datenebene. Ein häufiges Beispiel für eine Ausnahme auf Datenebene ist:

In anderen Situationen ist keine spezifische Ausnahme definiert. Wenn Ihre Anfrage z. B. gedrosselt wird, kann entweder die spezifische ProvisionedThroughputExceededException oder die allgemeinere DynamoDbException ausgelöst werden. In beiden Fällen können Sie feststellen, ob die Drosselung die Ausnahme verursacht hat, indem Sie überprüfen, ob isThrottlingException() den Wert true zurückgibt.

Je nach den Anforderungen Ihrer Anwendung können Sie alle Instances von AwsServiceException oder DynamoDbException abfangen. Oft ist jedoch ein unterschiedliches Verhalten je nach Situation erforderlich. Die Logik zur Behandlung eines Bedingungsfehlers unterscheidet sich von der zur Behandlung einer Drosselung. Definieren Sie, welche Ausnahmepfade Sie behandeln möchten, und testen Sie die Alternativen. So stellen Sie sicher, dass Ihre Anwendung mit allen relevanten Szenarien umgehen kann.

Eine Übersicht häufiger Fehler, auf die Sie stoßen könnten, finden Sie unter Fehlerbehandlung mit DynamoDB. Siehe auch Häufig auftretende Fehler in der Amazon DynamoDB-API-Referenz. Die API-Referenz enthält auch die genauen Fehler, die für jeden API-Vorgang möglich sind, z. B. für die Query-Operation. Informationen zur Behandlung von Ausnahmen finden Sie unter Ausnahmebehandlung für die AWS SDK for Java 2.x im AWS SDK for Java 2.x -Entwicklerhandbuch.

AWS Anforderungs-ID

Jede Anfrage enthält eine Anfrage-ID, die hilfreich sein kann, wenn Sie mit dem AWS Support zusammenarbeiten, um ein Problem zu diagnostizieren. Jede Ausnahme, die von SdkServiceException abgeleitet ist, verfügt über die Methode requestId(), mit der Sie die Anfrage-ID abrufen können.

Protokollierung

Die vom SDK bereitgestellte Protokollierung kann sowohl zum Erfassen wichtiger Nachrichten aus den Client-Bibliotheken als auch für tiefgehende Debugging-Zwecke nützlich sein. Logger sind hierarchisch aufgebaut und das SDK verwendet software.amazon.awssdk als Root-Logger. Sie können die Protokollierungsebene mit einem der folgenden Werte konfigurieren: TRACE, DEBUG, INFO, WARN, ERROR, ALL oder OFF. Die konfigurierte Ebene gilt für diesen Logger und alle untergeordneten Logger in der Hierarchie.

Für die Protokollierung AWS SDK for Java 2.x verwendet der die Simple Logging Façade for Java (SLF4J). Diese dient als Abstraktionsschicht über anderen Loggern, sodass Sie den Logger Ihrer Wahl einbinden können. Anleitungen zum Anschließen von Loggern finden Sie im SLF4J-Benutzerhandbuch.

Jeder Logger verhält sich unterschiedlich. Standardmäßig erstellt der Log4j 2.x-Logger einen ConsoleAppender, der Protokollereignisse an System.out anhängt und die Protokollierungsebene ERROR verwendet.

Der in SLF4J enthaltene SimpleLogger Logger gibt standardmäßig auf der Protokollebene aus System.err und verwendet diese standardmäßig. INFO

Für produktive Umgebungen empfehlen wir, die Ebene für software.amazon.awssdk auf WARN zu setzen, um wichtige SDK-Meldungen zu erfassen und gleichzeitig die Ausgabemenge zu begrenzen.

Wenn SLF4J keinen unterstützten Logger im Klassenpfad findet (keine SLF4J-Bindung), wird standardmäßig eine No-Op-Implementierung verwendet. Diese führt zu Meldungen an System.err, die erklären, dass SLF4J keine Logger-Implementierung im Klassenpfad finden konnte. Um diese Situation zu verhindern, müssen Sie eine Logger-Implementierung hinzufügen. Dazu können Sie in Ihrem Apache Maven pom.xml eine Abhängigkeit von Artefakten wie org.slf4j.slf4j-simple oder org.apache.logging.log4j.log4j-slf4j2-imp hinzufügen.

Weitere Informationen zur Konfiguration der Protokollierung im SDK, einschließlich der Einbindung von Logging-Abhängigkeiten in Ihre Anwendungskonfiguration, finden Sie unter Protokollieren mit dem SDK für Java 2.x im AWS SDK für Java -Entwicklerhandbuch.

Die folgende Konfiguration in der Log4j2.xml-Datei zeigt, wie Sie das Protokollierungsverhalten anpassen können, wenn Sie den Apache Log4j 2-Logger verwenden. Diese Konfiguration legt die Root-Logger-Ebene auf WARN fest. Alle Logger in der Hierarchie erben diese Protokollebene, einschließlich des software.amazon.awssdk-Loggers.

Standardmäßig geht die Ausgabe an System.out. Im folgenden Beispiel überschreiben wir noch immer den standardmäßigen Log4j-Appender für die Ausgabe, um ein maßgeschneidertes Log4j-PatternLayout anzuwenden.

Beispiel für ein Log4j2.xml Konfigurationsdatei

Die folgende Konfiguration protokolliert Meldungen auf der Konsole auf den Ebenen ERROR und WARN für alle Logger-Hierarchien.

<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 ID-Protokollierung anfordern

Wenn mal etwas schiefgeht, finden Sie die Anfrage-IDs in den Ausnahmen. Wenn Sie jedoch die Anfrage-IDs für Anfragen benötigen, die keine Ausnahmen generieren, können Sie die Protokollierung verwenden.

Der software.amazon.awssdk.request-Logger gibt Anfrage-IDs auf der DEBUG-Ebene aus. Das folgende Beispiel erweitert die vorherige configuration example, indem es die Root-Logger-Ebene auf ERROR, den software.amazon.awssdk auf die Ebene WARN und den Logger software.amazon.awssdk.request auf DEBUG setzt. Diese Einstellungen helfen dabei, Anfrage-IDs und andere anfragebezogene Details wie Endpunkt und Statuscode zu erfassen.

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

Hier finden Sie ein Beispiel für die Protokollausgabe:

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

Paginierung

Einige Anfragen, wie Query und Scan begrenzen die Datenmenge, die mit einer einzelnen Anfrage zurückgegeben wird, und erfordern wiederholte Anfragen, um nachfolgende Seiten abzurufen.

Mit dem Limit-Parameter können Sie die maximale Anzahl von Elementen steuern, die für jede Seite gelesen werden sollen. Sie können den Limit-Parameter beispielsweise verwenden, um nur die letzten 10 Elemente abzurufen. Dieser Grenzwert gibt an, wie viele Elemente aus der Tabelle gelesen werden sollen, bevor eine Filterung angewendet wird. Wenn Sie nach dem Filtern genau 10 Elemente benötigen, können Sie dies nicht angeben. Sie können nur die Anzahl der vorgefilterten Elemente steuern und clientseitig überprüfen, ob Sie tatsächlich 10 Elemente abgerufen haben. Unabhängig vom Grenzwert haben Antworten immer eine maximale Größe von 1 MB.

In der API-Antwort kann ein LastEvaluatedKey enthalten sein. Dies weist darauf hin, dass die Antwort beendet wurde, weil sie eine Anzahl- oder Größenbeschränkung erreicht hat. Dieser Schlüssel ist der letzte Schlüssel, der für diese Antwort ausgewertet wurde. Durch direkte Interaktion mit der API können Sie diesen LastEvaluatedKey abrufen und an einen Folgeaufruf als ExclusiveStartKey weitergeben, um den nächsten Abschnitt von diesem Startpunkt aus zu lesen. Wenn kein LastEvaluatedKey zurückgegeben wird, bedeutet das, dass keine weiteren Elemente zum Query- oder Scan-API-Aufruf passen.

Im folgenden Beispiel wird die Low-Level-Schnittstelle verwendet, um die Anzahl der Elemente auf Basis des keyConditionExpression-Parameters auf 100 zu beschränken.

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 Sie können diese Interaktion mit DynamoDB vereinfachen, indem sie automatische Paginierungsmethoden bereitstellen, die mehrere Serviceaufrufe tätigen, um automatisch die nächsten Ergebnisseiten für Sie abzurufen. Dies vereinfacht Ihren Code, nimmt Ihnen jedoch die Kontrolle über die Ressourcennutzung, die Sie beim manuellen Lesen von Seiten behalten würden.

Mithilfe der im DynamoDB-Client verfügbaren Iterable-Methoden wie QueryPaginator und ScanPaginator kümmert sich das SDK um die Paginierung. Der Rückgabetyp dieser Methoden ist ein benutzerdefiniertes iterierbares Objekt, mit dem Sie durch alle Seiten iterieren können. Das SDK bearbeitet für Sie Serviceanfragen intern. Mithilfe der Java Stream API können Sie das Ergebnis von QueryPaginator wie im folgenden Beispiel gezeigt verarbeiten.

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

Annotationen für Datenklassen

Das Java SDK stellt mehrere Annotationen bereit, die Sie auf die Attribute Ihrer Datenklasse anwenden können. Diese Annotationen beeinflussen, wie das SDK mit den Attributen interagiert. Durch das Hinzufügen einer Annotation kann ein Attribut beispielsweise als impliziter unteilbarer Zähler fungieren, einen automatisch generierten Zeitstempelwert speichern oder eine Versionsnummer eines Elements nachverfolgen. Weitere Informationen finden Sie unter Annotationen für Datenklassen.