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 end-of-support für 1.x wurde am 12. Januar 2024 angekündigt. Es wird am 31. Juli 2024 in den Wartungsmodus wechseln und end-of-support ist am 31. Dezember 2025 fällig. 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 finden Sie in den AWS SDKs Wartungsrichtlinien für AWS SDK und Tools sowie in der Matrix zur Unterstützung der Tools-Versionen im Referenzhandbuch AWS SDKs und im Tools-Referenzhandbuch.AWS SDKs

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-Releases mit langfristigem Support (LTS).

Erste Schritte mit 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-Instance verwendet eine Instance des Apache-basierten 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.

Durchsicht 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 one-to-one 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. Im folgenden Beispiel wird ein Element mithilfe der Low-Level-Schnittstelle PutItemeingefügt.

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 mit unveränderlichen Datenklassen

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 mit unveränderlichen Datenklassen und externen Bibliotheken zur Generierung von Boilerplate-Code

Unveränderliche Datenklassen (wie im vorherigen Beispiel gezeigt) erfordern etwas Boilerplate-Code. Beispielsweise die Getter- und Setter-Logik in den Datenklassen sowie zugehörige Builder-Klassen. Externe Bibliotheken wie Project Lombok können dabei helfen, diese Art von Boilerplate-Code 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. Das AWS SDKs Referenzhandbuch zu Tools enthält weitere Details und Beispiele zur Verwendung benutzerdefinierter Konverter. 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:

Vergleichen von Schnittstellen anhand eines Query-Beispiels

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 bei hoher Parallelität über wenige Threads effizient mit I/O-Anfragen umgehen kann und dabei nur minimale Rechenressourcen benötigt. Dies verbessert den Durchsatz und die Reaktionsfähigkeit.

Der AWS SDK for Java 2.x verwendet die native Unterstützung für nicht blockierende I/O. Die Version AWS SDK für Java 1.x musste nicht blockierende I/O simulieren.

Die synchronen Methoden reagieren, bevor eine Antwort verfügbar ist. Daher benötigen Sie eine Möglichkeit, die Antwort zu erhalten, sobald sie bereitsteht. Die asynchronen 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-basierter HTTP-Client

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

URLConnection-basierter HTTP-Client

Die UrlConnectionHttpClient-Klasse ist eine weitere Option für synchrone Clients. Sie lädt schneller als der Apache-basierte HTTP-Client, bietet jedoch weniger Funktionen. Informationen zur Konfiguration der UrlConnectionHttpClient Klasse finden Sie unter Configure the URLConnection -based HTTP-Client im AWS SDK for Java 2.x Developer Guide.

Netty-basierter HTTP-Client

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

AWS CRT-basierter HTTP-Client

Die neueren AwsCrtAsyncHttpClient Klassen AwsCrtHttpClient und 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-basierten HTTP-Clients im AWS SDK for Java 2.x Entwicklerhandbuch.

Der AWS CRT-basierte 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-basierten HTTP-Client sowohl für synchrone als auch asynchrone Zwecke zu verwenden.

Eine Einführung in den AWS CRT-basierten HTTP-Client finden Sie unter Ankündigung der Verfügbarkeit des CRT-HTTP-Clients im Developer AWS Tools-Blog. AWS SDK for Java 2.xAWS

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 erweiterte Definition dieser Wiederholungsmodi finden Sie im Thema Wiederholungsverhalten im Referenzhandbuch AWS SDKs und im Tools-Referenzhandbuch.

Wiederholungsrichtlinien

Alle RetryMode-Konfigurationen haben eine RetryPolicy, die auf einer oder mehreren RetryCondition-Konfigurationen basiert. Die TokenBucketRetryCondition ist besonders wichtig für das Wiederholungsverhalten der Implementierung des DynamoDB-SDK-Clients. Diese Bedingung begrenzt die Anzahl der Wiederholungen, die das SDK mithilfe eines Token-Bucket-Algorithmus durchführt. Je nach gewähltem Retry-Modus können Drosselungsfehler Token aus dem TokenBucket entfernen oder auch nicht.

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 Wiederholungen erfolgen.

Bei der Konfiguration eines Clients können Sie eine RetryPolicy bereitstellen, die unter anderem die folgenden Parameter unterstützt:

Der folgende Code bietet eine alternative Wiederholungsrichtlinie. Diese gibt insgesamt fünf Wiederholungen an (insgesamt sechs Anfragen). Die erste Wiederholung sollte nach einer Verzögerung von etwa 100 ms erfolgen, wobei jeder weitere Versuch diese Zeit exponentiell verdoppelt, bis zu einer maximalen Verzögerung von einer Sekunde.

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

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, wie HTTP-Kommunikationseinstellungen, Wiederholungsverhalten, regionale Endpunkteinstellungen des Dienstes und potenziell jede SDK-bezogene Konfiguration. Wenn Sie dieses Feature verwenden, können Sie neue Konfigurationsstandardwerte abrufen, die auf gängige Nutzungsszenarien zugeschnitten sind.

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

Sie können den Standardmodus folgendermaßen konfigurieren:

Die Smart-Konfigurationsstandardwerte im Referenzhandbuch AWS SDKs und im Tools-Referenzhandbuch enthalten eine Liste der Konfigurationseigenschaften und ihrer Standardwerte in den verschiedenen Standardmodi.

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

Keepalive-Konfigurierung

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

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

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

Wenn es um die Ausnahmebehandlung geht, 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 für Java (SLF4J). Diese dient als Abstraktionsschicht über anderen Loggern, sodass Sie den Logger Ihrer Wahl einbinden können. Anweisungen 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 SLF4 J enthaltene SimpleLogger Logger gibt standardmäßig auf 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 SLF4 J im Klassenpfad keinen unterstützten Logger finden kann (keine SLF4 J-Bindung), wird standardmäßig eine Implementierung ohne Operation verwendet. Diese Implementierung führt dazu, dass Meldungen protokolliert werden, die System.err erklären SLF4, dass ich im Klassenpfad keine Logger-Implementierung 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 einer 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 etwas schief geht, können Sie die Anfrage IDs innerhalb von Ausnahmen finden. Wenn Sie die Anfrage jedoch IDs für Anfragen verwenden möchten, die keine Ausnahmen generieren, können Sie die Protokollierung verwenden.

Der software.amazon.awssdk.request Logger gibt die 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. Das Festlegen dieser Stufen hilft dabei, die Anfrage IDs und andere anforderungsbezogene Details wie den Endpunkt und den Statuscode abzufangen.

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