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

Dieses Programmierhandbuch bietet Programmierern, die Amazon DynamoDB mit Java verwenden möchten, eine Orientierung. Das Handbuch behandelt verschiedene Konzepte, darunter Abstraktionsebenen, Konfigurationsmanagement, Fehlerbehandlung, Steuerung von Wiederholungsrichtlinien und Verwaltung von Keep-Alive.

Über den AWS SDK for Java 2.x

Sie können von Java aus mit dem offiziellen auf DynamoDB zugreifen. AWS SDK for Java SDKFür Java gibt es zwei Versionen: 1.x und 2.x. Die 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 Neuentwicklungen empfehlen wir dringend, 2.x zu verwenden, das erstmals 2018 veröffentlicht wurde. Dieses Handbuch bezieht sich ausschließlich auf 2.x und konzentriert sich nur auf die Teile der Version, die für DynamoDB SDK relevant sind.

Informationen zu Wartung und Support für die AWS SDKs Tools finden Sie unter Wartungsrichtlinien für Tools AWS SDK und Support-Matrix für Tools-Versionen im ReferenzhandbuchAWS SDKs für Tools.AWS SDKs

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

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

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

Das folgende Tutorial zeigt Ihnen, wie Sie Apache Maven verwenden, um Abhängigkeiten 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 Entwicklerhandbuch.AWS SDK for Java 2.x Wir haben dieses Tutorial so bearbeitet, dass DynamoDB statt Amazon S3 aufgerufen wird.

Schritt 1: Richten Sie sich für dieses Tutorial ein

Bevor Sie mit diesem Tutorial beginnen, benötigen Sie Folgendes:

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

Schritt 2: Erstellen Sie das Projekt

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 Eingaben eingegeben und bestätigt wurden, beendet Maven den Aufbau des Projekts, indem es eine pom.xml Datei erstellt und Stub-Java-Dateien erstellt.

Maven erstellt einen Projektordner, der auf dem von Ihnen artifactId eingegebenen Wert getstarted basiert. Suchen Sie innerhalb des getstarted Ordners nach einer Datei mit dem Namen, 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

Im Folgenden wird der Inhalt der pom.xml Projektdatei gezeigt.

<?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 Sie den Code

Der folgende Code zeigt die App Klasse, die Maven erstellt. Die main Methode ist der Einstiegspunkt in die Anwendung, die eine Instanz 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 DynamoDbClientInstanz erstellt und zurückgibt. Die DynamoDbClient Instanz verwendet eine Instanz des HTTP Apache-basierten Clients. Dies liegt daran, dass Sie angegeben habenapache-client, wann Maven Sie nach dem HTTP zu verwendenden 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 in der App Klasse eine Instanz von erstellt Handler wird, stellt DependencyFactory sie den DynamoDbClient Service-Client bereit. Ihr Code verwendet die DynamoDbClient Instanz, um DynamoDB aufzurufen.

Maven generiert die folgende Handler Klasse mit einem Kommentar. TODO Der nächste Schritt im Tutorial ersetzt den TODOKommentar 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 auszufüllen, ersetzen Sie den gesamten Inhalt der Handler Klasse durch den folgenden Code. Die sendRequest Methode wird ausgefüllt 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: Erstellen Sie die Anwendung und führen Sie sie aus

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 für Java 2.x erstellt.

Bereinigen

Um die Ressourcen zu bereinigen, die Sie in diesem Tutorial erstellt haben, löschen Sie den Projektordnergetstarted.

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

Das AWS SDK for Java 2.x Entwicklerhandbuch deckt alle Aspekte von SDK Across All AWS-Services ab. Wir empfehlen Ihnen, sich mit den folgenden Themen vertraut zu machen:

Unterstützte Schnittstellen

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

Schnittstelle auf niedriger Ebene

Die Low-Level-Schnittstelle bietet eine one-to-one Zuordnung zum zugrunde liegenden Dienst. API Jede DynamoDB API ist über diese Schnittstelle verfügbar. Das bedeutet, dass die Low-Level-Schnittstelle vollständige Funktionalität bieten kann, sie ist jedoch häufig ausführlicher und komplexer zu verwenden. Beispielsweise müssen Sie die Funktionen zum Speichern von Zeichenketten und die .s() .n() Funktionen zum Speichern von Zahlen verwenden. Das folgende Beispiel für das PutItemEinfügen eines Elements mithilfe der Low-Level-Schnittstelle.

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

Schnittstelle auf hoher Ebene

Die High-Level-Schnittstelle im AWS SDK for Java 2.x wird als DynamoDB Enhanced Client bezeichnet. Diese Schnittstelle bietet eine idiomatischere Erfahrung beim Verfassen von Code.

Der erweiterte Client bietet eine Möglichkeit, clientseitige Datenklassen und DynamoDB-Tabellen zuzuordnen, in denen diese Daten gespeichert werden sollen. Sie definieren die Beziehungen zwischen Tabellen und ihren jeweiligen Modellklassen im Code. Anschließend können Sie sich darauf verlassen, dass die Manipulation des SDK Datentyps verwaltet wird. Weitere Informationen zum erweiterten Client finden Sie unter DynamoDB Enhanced Client API im AWS SDK for Java 2.x Developer Guide.

Das folgende Beispiel PutItemverwendet die High-Level-Schnittstelle. In diesem Beispiel YourItem erstellt der DynamoDbBean Name eineTableSchema, die seine direkte Verwendung als Eingabe für den putItem() Anruf 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 for Java Version 1.x hat eine eigene High-Level-Schnittstelle, auf die oft mit ihrer Hauptklasse DynamoDBMapper verwiesen 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 Java 2.x SDK wird oft mit seiner Hauptklasse bezeichnet. DynamoDbEnhancedClient

High-Level-Schnittstelle mit unveränderlichen Datenklassen

Die Mapping-Funktion des erweiterten DynamoDB-Clients funktioniert API auch mit unveränderlichen Datenklassen. Eine unveränderliche Klasse hat nur Getter und benötigt eine Builder-Klasse, die dann SDK verwendet wird, um Instanzen der Klasse zu erstellen. Unveränderlichkeit in Java ist ein häufig verwendeter Stil, mit dem Entwickler Klassen ohne Nebenwirkungen erstellen können. Diese Klassen sind in ihrem Verhalten in komplexen Multithread-Anwendungen vorhersehbarer. Anstatt die @DynamoDbBean Annotation zu verwenden, wie in der gezeigtHigh-level interface example, verwenden unveränderliche Klassen die @DynamoDbImmutable Annotation, die die Builder-Klasse als Eingabe verwendet.

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

Das folgende Beispiel zeigt die unveränderliche Datenklasse.

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

Schnittstelle auf hoher Ebene, die unveränderliche Datenklassen und Bibliotheken zur Generierung von Textbausteinen von Drittanbietern verwendet

Unveränderliche Datenklassen (im vorherigen Beispiel gezeigt) erfordern etwas Standardcode. Zum Beispiel die Getter- und Setter-Logik für die Datenklassen zusätzlich zu den Klassen. Builder Bibliotheken von Drittanbietern, 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 benötigt wird. AWS SDK Dies führt weiter zu einer verbesserten Produktivität und Lesbarkeit Ihres Codes. Weitere Informationen finden Sie im AWS SDK for Java 2.x Entwicklerhandbuch unter Verwenden von Bibliotheken von Drittanbietern wie Lombok.

Das folgende Beispiel zeigt, wie Project Lombok den Code vereinfacht, der für die Verwendung des erweiterten DynamoDB-Clients erforderlich ist. API

import org.slf4j.*;
import software.amazon.awssdk.enhanced.dynamodb.*;
import software.amazon.awssdk.enhanced.dynamodb.model.*;
import software.amazon.awssdk.services.dynamodb.model.ReturnConsumedCapacity;

public class DynamoDbEnhancedClientImmutableLombokPutItem {

    private static final DynamoDbEnhancedClient ENHANCED_DYNAMODB_CLIENT = DynamoDbEnhancedClient.builder().build();
    private static final DynamoDbTable<YourImmutableLombokItem> DYNAMODB_TABLE = ENHANCED_DYNAMODB_CLIENT.table("YourTableName", TableSchema.fromImmutableClass(YourImmutableLombokItem.class));
    private static final Logger LOGGER = LoggerFactory.getLogger(DynamoDbEnhancedClientImmutableLombokPutItem.class);

    private void putItem() {
        PutItemEnhancedResponse<YourImmutableLombokItem> response = DYNAMODB_TABLE.putItemWithResponse(PutItemEnhancedRequest.builder(YourImmutableLombokItem.class)
                .item(YourImmutableLombokItem.builder()
                        .pk("123")
                        .sk("cart#123")
                        .itemData("YourItemData")
                        .inventory(500)
                        .build())
                .returnConsumedCapacity(ReturnConsumedCapacity.TOTAL)
                .build());
        LOGGER.info("PutItem call consumed [" + response.consumedCapacity().capacityUnits() + "] Write Capacity Unites (WCU)");
    }
}

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 The bereitstellen: AWS SDK

Dokumentschnittstelle

Die AWS SDK for Java 2.x Dokumentschnittstelle macht die Angabe von Datentypdeskriptoren überflüssig. Die Datentypen werden durch die Semantiken der Daten selber bereitgestellt. Diese Dokumentschnittstelle ähnelt der Dokumentschnittstelle von AWS SDK for Java 1.x, verfügt jedoch über eine neu gestaltete Oberfläche.

Im Folgenden wird der über die Document-Schnittstelle ausgedrückte PutItem Aufruf Document interface example dargestellt. Das Beispiel verwendet auch EnhancedDocument. Um mithilfe des erweiterten Dokuments Befehle für eine DynamoDB-Tabelle auszuführenAPI, müssen Sie die Tabelle zunächst Ihrem Dokumenttabellenschema zuordnen, um ein DynamoDBTable Ressourcenobjekt zu erstellen. Der Schemagenersteller für Dokumenttabellen benötigt den primären Indexschlüssel und die Anbieter für den Attributkonverter.

Sie können ihn verwendenAttributeConverterProvider.defaultProvider(), um Dokumentattribute von Standardtypen zu konvertieren. Sie können das allgemeine Standardverhalten mit einer benutzerdefinierten AttributeConverterProvider Implementierung ändern. Sie können den Konverter auch für ein einzelnes Attribut ändern. Das AWS SDKsReferenzhandbuch für Tools enthält weitere Informationen und Beispiele zur Verwendung benutzerdefinierter Konverter. Sie werden hauptsächlich für Attribute Ihrer Domainklassen verwendet, für die kein Standardkonverter verfügbar ist. Mithilfe eines benutzerdefinierten Konverters können Sie die SDK erforderlichen Informationen zum Schreiben oder Lesen in DynamoDB bereitstellen.

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 und aus den nativen Amazon DynamoDB DynamoDB-Datentypen zu konvertieren, können Sie die folgenden Hilfsmethoden verwenden:

Schnittstellen anhand eines Query Beispiels vergleichen

Dieser Abschnitt zeigt den gleichen QueryAufruf, 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;
        }
    }
}

Zusätzliche Codebeispiele

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

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 DynamoDbEnhancedClient Klassen DynamoDbClient und stellen synchrone Methoden bereit, die die Ausführung Ihres Threads blockieren, bis der Client eine Antwort vom Dienst erhält. Dieser Client ist die einfachste Art der Interaktion mit DynamoDB, wenn Sie keine asynchronen Operationen benötigen.

Die DynamoDbEnhancedAsyncClient Klassen DynamoDbAsyncClient und stellen asynchrone Methoden bereit, die sofort zurückkehren und dem aufrufenden Thread die Kontrolle zurückgeben, ohne auf eine Antwort warten zu müssen. 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 nicht blockierende I/O. Die Version AWS SDK for Java 1.x musste nicht blockierende I/O simulieren.

Die synchronen 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. Die asynchronen Methoden AWS SDK for Java geben ein CompletableFutureObjekt zurück, das die Ergebnisse der asynchronen Operation in der future enthält. Wenn Sie get() oder join() für diese CompletableFuture Objekte aufrufen, wird Ihr Code blockiert, bis das Ergebnis verfügbar ist. Wenn Sie diese gleichzeitig aufrufen, während Sie die Anfrage stellen, ähnelt das Verhalten einem einfachen synchronen Aufruf.

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

HTTPKunden

Für die Unterstützung jedes Kunden gibt es einen HTTP Kunden, der die Kommunikation mit dem übernimmt AWS-Services. Sie können alternative HTTP Clients hinzufügen und einen auswählen, der die Eigenschaften aufweist, die am besten zu Ihrer Anwendung passen. Einige sind leichter, andere bieten mehr Konfigurationsoptionen.

Einige HTTP Clients unterstützen nur die synchrone Verwendung, während andere nur die asynchrone Verwendung unterstützen. Ein Flussdiagramm, das Ihnen bei der Auswahl des optimalen HTTP Clients für Ihren Workload helfen kann, finden Sie in den HTTPKundenempfehlungen im AWS SDK for Java 2.x Developer Guide.

In der folgenden Liste sind einige der möglichen HTTP Clients aufgeführt:

Apache-basierter Client HTTP

Die ApacheHttpClientKlasse unterstützt synchrone Dienstclients. Es ist der HTTP Standardclient für die synchrone Verwendung. Informationen zur Konfiguration der ApacheHttpClient Klasse finden Sie unter Konfiguration des Apache-basierten HTTP Clients im Entwicklerhandbuch.AWS SDK for Java 2.x

URLConnectionHTTP-basierter Client

Die UrlConnectionHttpClientKlasse ist eine weitere Option für synchrone Clients. Sie wird schneller geladen als der Apache-basierte HTTP Client, hat aber 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 Client HTTP

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 Configure the Netty-based HTTP client im AWS SDK for Java 2.x Developer Guide.

AWS CRT-basierter Client HTTP

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

Informationen zur Konfiguration der AwsCrtAsyncHttpClient Klassen AwsCrtHttpClient und finden Sie unter Configure the AWS CRT -based HTTP clients im AWS SDK for Java 2.x Developer Guide.

Der AWS CRT basierte HTTP Client ist nicht die Standardeinstellung, 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 für asynchrone Zwecke zu verwenden.

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

Konfigurieren eines HTTP-Clients

Bei der Konfiguration eines Clients können Sie verschiedene Konfigurationsoptionen angeben, darunter:

Sie steuern die Konfiguration, indem Sie der Service-Client-Klasse ein ClientOverrideConfigurationObjekt zur Verfügung stellen. Builder Sie werden dies in einigen Codebeispielen in den folgenden Abschnitten sehen.

Das ClientOverrideConfiguration bietet Standardkonfigurationsoptionen. Die verschiedenen steckbaren HTTP Clients verfügen ebenfalls über implementierungsspezifische Konfigurationsmöglichkeiten.

Timeout-Konfiguration

Sie können die Client-Konfiguration anpassen, um verschiedene Timeouts im Zusammenhang mit den Serviceaufrufen zu kontrollieren. DynamoDB bietet im Vergleich zu anderen Systemen geringere Latenzen. AWS-Services Daher sollten Sie diese Eigenschaften an niedrigere Timeout-Werte anpassen, damit Sie bei Netzwerkproblemen schnell ausfallen können.

Sie können das latenzbezogene Verhalten ClientOverrideConfiguration auf dem DynamoDB-Client anpassen oder indem Sie die detaillierten Konfigurationsoptionen in der zugrunde liegenden HTTP Client-Implementierung ändern.

Sie können die folgenden wirkungsvollen Eigenschaften konfigurieren, indem Sie: ClientOverrideConfiguration

Das AWS SDK for Java 2.x stellt Standardwerte für einige Timeout-Optionen bereit, z. B. Verbindungs-Timeout und Socket-Timeouts. Das stellt SDK keine Standardwerte für Zeitüberschreitungen bei API Anrufen oder Zeitüberschreitungen für einzelne API Anrufversuche bereit. Wenn diese Timeouts nicht in der festgelegt sindClientOverrideConfiguration, SDK verwendet der stattdessen den Socket-Timeout-Wert für das gesamte Anruf-Timeout. API Das Socket-Timeout hat einen Standardwert von 30 Sekunden.

RetryMode

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

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

Eine erweiterte Definition dieser Wiederholungsmodi finden Sie im Thema Wiederholungsverhalten im Referenzhandbuch AWS SDKsund im Tools-Referenzhandbuch.

Richtlinien für Wiederholungsversuche

Alle RetryMode Konfigurationen haben eine RetryPolicy, die auf einer oder mehreren RetryConditionKonfigurationen basiert. Dies TokenBucketRetryConditionist besonders wichtig für das Wiederholungsverhalten der SDK DynamoDB-Clientimplementierung. Diese Bedingung begrenzt die Anzahl der Wiederholungen, die er mithilfe eines SDK Token-Bucket-Algorithmus durchführt. Je nach ausgewähltem Wiederholungsmodus können Drosselungsausnahmen Tokens vom subtrahieren oder auch nicht. TokenBucket

Wenn ein Client auf einen Fehler stößt, der wiederholt werden kann, z. B. eine Drosselungsausnahme oder einen temporären Serverfehler, versucht er die Anfrage automatisch erneut. SDK Sie können steuern, wie oft und wie schnell diese Wiederholungen erfolgen.

Bei der Konfiguration eines Clients können Sie einen angeben, der RetryPolicy die folgenden Parameter unterstützt:

Der folgende Code bietet eine alternative Wiederholungsrichtlinie. Es 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 that ClientOverrideConfiguration und RetryMode don't manage werden in der Regel implizit durch Angabe von a konfiguriert. DefaultsMode

Die AWS SDK for Java 2.x (Version 2.17.102 oder höher) führte die Unterstützung für ein. 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 SDK zugehörige Konfiguration. Wenn Sie diese Funktion verwenden, können Sie neue Konfigurationsstandardwerte abrufen, die auf allgemeine Nutzungsszenarien zugeschnitten sind.

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

Sie können den Standardmodus auf folgende Weise konfigurieren:

Die Smart-Konfigurationsstandardwerte im Referenzhandbuch AWS SDKsund 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 einer Region bereitgestellt werden, ist der in-region Standardmodus unter den Standardmodi am relevantesten. standard

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

Keep-Alive-Konfiguration

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

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

URLConnectionHTTPbasierter Client

Jeder synchrone Client, der den URLConnection basierten HTTP Client verwendet, HttpURLConnectionverfügt nicht über einen Mechanismus zur Aktivierung von Keep-Alive.

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

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

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

Fehlerbehandlung

Wenn es um die Ausnahmebehandlung geht, AWS SDK for Java 2.x verwendet er (ungeprüfte) Laufzeitausnahmen.

Die Basisausnahme, die alle SDK Ausnahmen abdeckt, ist SdkServiceException, dass sie von Java aus RuntimeException ungeprüft ist. Wenn du das erwischst, fängst du alle Ausnahmen ab, die das SDK wirft.

SdkServiceExceptionhat eine Unterklasse namens. AwsServiceException Diese Unterklasse weist auf Probleme bei der Kommunikation mit dem hin. AWS-Service Sie hat eine Unterklasse namens DynamoDbException, die auf ein Problem bei der Kommunikation mit DynamoDB hinweist. Wenn Sie das erkennen, catch Sie alle Ausnahmen ab, die sich auf DynamoDB beziehen, aber keine anderen SDK Ausnahmen.

Spezifischere Ausnahmetypen finden Sie unter. DynamoDbException Einige dieser Ausnahmetypen gelten für Operationen auf Steuerungsebenen wie. TableAlreadyExistsException Andere gelten für Operationen auf Datenebene. Im Folgenden finden Sie ein Beispiel für eine häufige Ausnahme auf Datenebene:

Für andere Situationen ist keine spezifische Ausnahme definiert. Wenn Ihre Anfragen beispielsweise gedrosselt werden, ProvisionedThroughputExceededException kann es sein, dass die spezifischen Anfragen geworfen werden, während in anderen Fällen die allgemeinere ausgelöst DynamoDbException wird. In beiden Fällen können Sie feststellen, ob die Drosselung die Ausnahme verursacht hat, indem Sie überprüfen, ob die Rückgabe zurückgegeben wird. isThrottlingException() true

Abhängig von Ihren Anwendungsanforderungen können Sie alle AwsServiceException oder DynamoDbException Instanzen catch. In verschiedenen Situationen benötigen Sie jedoch häufig ein anderes Verhalten. Die Logik für den Umgang mit einer fehlgeschlagenen Zustandsprüfung unterscheidet sich von der für die Drosselung. Definieren Sie, mit welchen außergewöhnlichen Pfaden Sie sich befassen möchten, und stellen Sie sicher, dass Sie die alternativen Pfade testen. Auf diese Weise können Sie sicherstellen, dass Sie mit allen relevanten Szenarien umgehen können.

Eine Liste der häufigsten Fehler, auf die Sie möglicherweise stoßen können, finden Sie unterFehlerbehandlung mit DynamoDB. Weitere Informationen finden Sie auch unter Häufig auftretende Fehler in der Amazon DynamoDB DynamoDB-Referenz API. Die API Referenz enthält auch die genauen Fehler, die für jeden API Vorgang möglich sind, z. B. für den QueryVorgang. Informationen zur Behandlung von Ausnahmen finden Sie AWS SDK for Java 2.x im AWS SDK for Java 2.x Entwicklerhandbuch unter Ausnahmebehandlung für.

AWS ID anfordern

Jede Anfrage enthält eine Anforderungs-ID, deren Abruf nützlich sein kann, wenn Sie damit arbeiten, ein Problem AWS Support zu diagnostizieren. Für jede davon abgeleitete Ausnahme SdkServiceException steht eine requestId()Methode zum Abrufen der Anforderungs-ID zur Verfügung.

Protokollierung

Die Verwendung der bereitgestellten Protokollierung kann sowohl für das SDK Abfangen wichtiger Nachrichten aus den Clientbibliotheken als auch für detailliertere Debugging-Zwecke nützlich sein. Logger sind hierarchisch aufgebaut und werden software.amazon.awssdk als Root-Logger SDK verwendet. Sie können die Ebene mit einem vonTRACE,,DEBUG, INFO WARN ERRORALL, oder konfigurieren. OFF Die konfigurierte Ebene gilt für diesen Logger und für die gesamte Logger-Hierarchie.

Für die Protokollierung AWS SDK for Java 2.x verwendet der die Simple Logging Façade for Java (SLF4J). Dies dient als Abstraktionsebene für andere Logger, und Sie können damit den Logger anschließen, den Sie bevorzugen. Anweisungen zum Anschließen von Loggern finden Sie im Benutzerhandbuch. SLF4J

Jeder Logger hat ein bestimmtes Verhalten. Standardmäßig erstellt der Log4j 2.x-Logger einenConsoleAppender, der Protokollereignisse an die Protokollebene anhängt System.out und diese standardmäßig verwendet. ERROR

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

Wir empfehlen, die Stufe für alle Produktionsbereitstellungen auf WARN software.amazon.awssdk for festzulegen, um wichtige Nachrichten aus den Clientbibliotheken SDK von abzufangen und gleichzeitig die Ausgabemenge zu begrenzen.

Wenn im Klassenpfad kein unterstützter Logger gefunden werden SLF4J kann (keine SLF4J Bindung), wird standardmäßig eine Implementierung ohne Operation verwendet. Diese Implementierung führt dazu, dass Meldungen protokolliert werden, die System.err erklären, dass keine Logger-Implementierung im Klassenpfad gefunden werden SLF4J 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.

Informationen zur Konfiguration der Protokollierung inSDK, einschließlich des Hinzufügens von Protokollierungsabhängigkeiten zu Ihrer Anwendungskonfiguration, finden Sie unter Logging with the SDK for Java 2.x im AWS SDK for Java Developer Guide.

Die folgende Konfiguration in der Log4j2.xml Datei zeigt, wie Sie das Logging-Verhalten anpassen können, wenn Sie den Apache Log4j 2-Logger verwenden. Diese Konfiguration legt die Root-Logger-Ebene auf fest. WARN 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 immer noch den standardmäßigen Log4j-Appender für die Ausgabe, um ein maßgeschneidertes Log4j anzuwenden. PatternLayout

Beispiel für eine Konfigurationsdatei Log4j2.xml

Die folgende Konfiguration protokolliert Meldungen auf der Konsole auf den WARN Ebenen ERROR und 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 das vorherigeconfiguration example, um den Root-Logger auf der EbeneERROR, der software.amazon.awssdk at-Ebene WARN und der software.amazon.awssdk.request at-Ebene zu belassenDEBUG. 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 z. B. Queryund Scan, begrenzen die Größe der Daten, die bei einer einzelnen Anfrage zurückgegeben werden, und erfordern, dass Sie wiederholte Anfragen stellen, 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 müssen, 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 Limit haben Antworten immer eine maximale Größe von 1 MB.

A LastEvaluatedKey könnte in der API Antwort 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. Wenn Sie direkt mit dem interagierenAPI, können Sie ihn abrufen LastEvaluatedKey und an einen Folgeanruf weiterleitenExclusiveStartKey, um den nächsten Abschnitt von diesem Startpunkt aus zu lesen. Wenn nein zurückgegeben LastEvaluatedKey wird, bedeutet dies, dass es keine weiteren Elemente gibt, die dem Query Scan API OR-Aufruf entsprechen.

Im folgenden Beispiel wird die Low-Level-Schnittstelle verwendet, um die Anzahl der Elemente auf der Grundlage 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 QueryPaginatorund ScanPaginatorSDKkümmert sich der um die Paginierung. Der Rückgabetyp dieser Methoden ist eine benutzerdefinierte Iterable, die Sie verwenden können, um durch alle Seiten zu iterieren. Der bearbeitet SDK intern Serviceanfragen für Sie. Mit dem 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();

Anmerkungen zur Datenklasse

Das Java SDK bietet mehrere Anmerkungen, die Sie den Attributen Ihrer Datenklasse hinzufügen können. Diese Anmerkungen beeinflussen, wie sie mit den SDK Attributen interagieren. Durch Hinzufügen einer Anmerkung können Sie festlegen, dass sich ein Attribut wie ein impliziter Atomzähler verhält, einen automatisch generierten Zeitstempelwert beibehalten oder die Versionsnummer eines Elements verfolgen. Weitere Informationen finden Sie unter Anmerkungen zu Datenklassen.