Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # Programmieren von Amazon DynamoDB mit JavaScript Dieses Handbuch bietet Programmierern, die Amazon DynamoDB mit verwenden möchten, eine Orientierung. JavaScript Erfahren Sie mehr über die verfügbaren Abstraktionsebenen AWS SDK für JavaScript, die Konfiguration von Verbindungen, den Umgang mit Fehlern, die Definition von Wiederholungsrichtlinien, die Verwaltung von Keep-Alive und mehr. **Topics** + [Über AWS SDK für JavaScript](#programming-with-javascript-about) + [Verwenden von AWS SDK für JavaScript V3](#programming-with-javascript-using-the-sdk) + [Zugriff auf die JavaScript Dokumentation](#programming-with-javascript-documentation) + [Abstraktionsebenen](#programming-with-javascript-abstraction-layers) + [Verwenden der Hilfsfunktion Marshall](#programming-with-javascript-using-marshall-utility) + [Lesen von Elementen](#programming-with-javascript-reading-items) + [Bedingte Schreibvorgänge](#programming-with-javascript-conditional-writes) + [Paginierung](#programming-with-javascript-pagination) + [Angeben der Konfiguration](#programming-with-javascript-config) + [Waiter](#programming-with-javascript-waiters) + [Fehlerbehandlung](#programming-with-javascript-error-handling) + [Protokollierung](#programming-with-javascript-logging) + [Überlegungen](#programming-with-javascript-considerations) ## Über AWS SDK für JavaScript Das AWS SDK für JavaScript bietet Zugriff auf die AWS-Services Verwendung von Browserskripten oder Node.js. Diese Dokumentation konzentriert sich auf die neueste SDK-Version (V3). Die AWS SDK für JavaScript Version 3 wird von AWS als [Open-Source-Projekt verwaltet, das auf GitHub gehostet wird](https://github.com/aws/aws-sdk-js-v3). Probleme und Funktionsanfragen sind öffentlich und Sie können auf der Problemseite des GitHub Repositorys darauf zugreifen. JavaScript V2 ähnelt V3, enthält jedoch Syntaxunterschiede. V3 ist modularer aufgebaut, was es einfacher macht, kleinere Abhängigkeiten zu versenden, und bietet erstklassigen TypeScript Support. Wir empfehlen die neueste SDK-Version zu verwenden. ## Verwenden von AWS SDK für JavaScript V3 Mit dem Node Package Manager können Sie das SDK zu Ihrer Node.js-Anwendung hinzufügen. Die folgenden Beispiele zeigen, wie Sie die gängigsten SDK-Pakete für die Arbeit mit DynamoDB hinzufügen. + `npm install @aws-sdk/client-dynamodb` + `npm install @aws-sdk/lib-dynamodb` + `npm install @aws-sdk/util-dynamodb` Die Installation von Paketen fügt Verweise im Abschnitt „Abhängigkeiten“ zu Ihrer package.json-Projektdatei hinzu. Sie haben die Möglichkeit, die neuere ECMAScript Modulsyntax zu verwenden. Weitere Informationen zu diesen beiden Ansätzen finden Sie im Abschnitt „Überlegungen“. ## Zugriff auf die JavaScript Dokumentation Beginnen Sie mit der JavaScript Dokumentation mit den folgenden Ressourcen: + Die JavaScript Kerndokumentation finden Sie im [Entwicklerhandbuch](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html). Installationsanweisungen finden Sie im Abschnitt **Einrichtung**. + In der [API-Referenzdokumentation](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/introduction/) können Sie sich mit allen verfügbaren Klassen und Methoden vertraut machen. + Das SDK für JavaScript unterstützt viele AWS-Services andere als DynamoDB. Gehen Sie wie folgt vor, um eine spezifische API-Abdeckung für DynamoDB zu finden: 1. Wählen Sie unter **Services** die Option **DynamoDB und Bibliotheken** aus. Hier wird der Low-Level-Client dokumentiert. 1. Wählen Sie **lib-dynamodb** aus. Hier wird der High-Level-Client dokumentiert. Die beiden Clients stellen zwei verschiedene Abstraktionsebenen dar, die Sie verwenden können. Weitere Informationen zu Abstraktionsebenen finden Sie im folgenden Abschnitt. ## Abstraktionsebenen Das SDK für JavaScript V3 hat einen Low-Level-Client (`DynamoDBClient`) und einen High-Level-Client (). `DynamoDBDocumentClient` **Topics** + [Low-Level-Client (`DynamoDBClient`)](#programming-with-javascript-low-level-client) + [High-Level-Client (`DynamoDBDocumentClient`)](#programming-with-javascript-high-level-client) ### Low-Level-Client (`DynamoDBClient`) Der Low-Level-Client bietet keine zusätzlichen Abstraktionen gegenüber dem zugrunde liegenden Wire-Protokoll. Es bietet Ihnen volle Kontrolle über alle Aspekte der Kommunikation, aber da keine Abstraktionen vorhanden sind, müssen Sie beispielsweise Elementdefinitionen im DynamoDB-JSON-Format bereitstellen. Wie das folgende Beispiel zeigt, müssen bei diesem Format die Datentypen explizit angegeben werden. Ein *S* steht für einen Zeichenkettenwert und ein *N* steht für einen Zahlenwert. Zahlen werden beim Übertragen stets als Zeichenketten gesendet, die als Zahlentypen gekennzeichnet sind, um einen Präzisionsverlust zu vermeiden. Low-Level-API-Aufrufe haben ein Benennungsmuster wie `PutItemCommand` und `GetItemCommand`. Im folgenden Beispiel wird der Low-Level-Client mit einem `Item` verwendet, das im DynamoDB-JSON-Format definiert ist: ``` const { DynamoDBClient, PutItemCommand } = require("@aws-sdk/client-dynamodb"); const client = new DynamoDBClient({}); async function addProduct() { const params = { TableName: "products", Item: { "id": { S: "Product01" }, "description": { S: "Hiking Boots" }, "category": { S: "footwear" }, "sku": { S: "hiking-sku-01" }, "size": { N: "9" } } }; try { const data = await client.send(new PutItemCommand(params)); console.log('result : ' + JSON.stringify(data)); } catch (error) { console.error("Error:", error); } } addProduct(); ``` ### High-Level-Client (`DynamoDBDocumentClient`) Der DynamoDB-Dokumentenclient auf hoher Ebene bietet integrierte Komfortfunktionen, z. B. macht das manuelle Marshalling von Daten überflüssig und ermöglicht direkte Lese- und Schreibvorgänge mithilfe von Standardobjekten. JavaScript Die [Dokumentation zu `lib-dynamodb`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-lib-dynamodb/) enthält eine Liste der Vorteile. Um den `DynamoDBDocumentClient` zu instanziieren, erstellen Sie zunächst einen Low-Level-`DynamoDBClient` und umschließen ihn anschließend mit einem `DynamoDBDocumentClient`. Die Namenskonventionen der Funktionen unterscheiden sich leicht zwischen den beiden Paketen. Der Low-Level-Client verwendet beispielsweise `PutItemCommand`, während der High-Level-Client `PutCommand` verwendet. Durch die unterschiedlichen Namen können beide Funktionssets im selben Kontext koexistieren, sodass Sie sie innerhalb desselben Skripts kombinieren können. ``` const { DynamoDBClient } = require("@aws-sdk/client-dynamodb"); const { DynamoDBDocumentClient, PutCommand } = require("@aws-sdk/lib-dynamodb"); const client = new DynamoDBClient({}); const docClient = DynamoDBDocumentClient.from(client); async function addProduct() { const params = { TableName: "products", Item: { id: "Product01", description: "Hiking Boots", category: "footwear", sku: "hiking-sku-01", size: 9, }, }; try { const data = await docClient.send(new PutCommand(params)); console.log('result : ' + JSON.stringify(data)); } catch (error) { console.error("Error:", error); } } addProduct(); ``` Das Verwendungsmuster ist konsistent, wenn Sie Elemente mithilfe von API-Operationen wie `GetItem`, `Query` oder `Scan` lesen. ## Verwenden der Hilfsfunktion Marshall Sie können den Low-Level-Client verwenden und die Datentypen selbst mit marshall oder unmarshall konvertieren. Das Hilfspaket [util-dynamodb](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-util-dynamodb/) enthält eine `marshall()`-Hilfsfunktion, die JSON entgegennimmt und DynamoDB-JSON erzeugt, sowie eine `unmarshall()`-Funktion, die den umgekehrten Vorgang ausführt. Im folgenden Beispiel wird der Low-Level-Client verwendet, wobei die Datenkonvertierung durch den Aufruf von `marshall()` erfolgt. ``` const { DynamoDBClient, PutItemCommand } = require("@aws-sdk/client-dynamodb"); const { marshall } = require("@aws-sdk/util-dynamodb"); const client = new DynamoDBClient({}); async function addProduct() { const params = { TableName: "products", Item: marshall({ id: "Product01", description: "Hiking Boots", category: "footwear", sku: "hiking-sku-01", size: 9, }), }; try { const data = await client.send(new PutItemCommand(params)); } catch (error) { console.error("Error:", error); } } addProduct(); ``` ## Lesen von Elementen Um ein einzelnes Element aus DynamoDB zu lesen, verwenden Sie die API-Operation `GetItem`. Ähnlich wie beim `PutItem`-Befehl haben Sie die Wahl zwischen dem Low-Level-Client und dem High-Level-Dokument-Client. Das folgende Beispiel zeigt, wie Sie mit dem High-Level-Dokument-Client ein Element abrufen. ``` const { DynamoDBClient } = require("@aws-sdk/client-dynamodb"); const { DynamoDBDocumentClient, GetCommand } = require("@aws-sdk/lib-dynamodb"); const client = new DynamoDBClient({}); const docClient = DynamoDBDocumentClient.from(client); async function getProduct() { const params = { TableName: "products", Key: { id: "Product01", }, }; try { const data = await docClient.send(new GetCommand(params)); console.log('result : ' + JSON.stringify(data)); } catch (error) { console.error("Error:", error); } } getProduct(); ``` Verwenden Sie die `Query`-API-Operation, um mehrere Elemente zu lesen. Sie können den Low-Level-Client oder den Dokument-Client verwenden. Im folgenden Beispiel wird der High-Level-Dokument-Client verwendet. ``` const { DynamoDBClient } = require("@aws-sdk/client-dynamodb"); const { DynamoDBDocumentClient, QueryCommand, } = require("@aws-sdk/lib-dynamodb"); const client = new DynamoDBClient({}); const docClient = DynamoDBDocumentClient.from(client); async function productSearch() { const params = { TableName: "products", IndexName: "GSI1", KeyConditionExpression: "#category = :category and begins_with(#sku, :sku)", ExpressionAttributeNames: { "#category": "category", "#sku": "sku", }, ExpressionAttributeValues: { ":category": "footwear", ":sku": "hiking", }, }; try { const data = await docClient.send(new QueryCommand(params)); console.log('result : ' + JSON.stringify(data)); } catch (error) { console.error("Error:", error); } } productSearch(); ``` ## Bedingte Schreibvorgänge DynamoDB-Schreibvorgänge können eine logische Bedingungsausdruck angeben, der als true ausgewertet werden muss, damit der Schreibvorgang ausgeführt wird. Wenn die Bedingung nicht als wahr ausgewertet wird, erzeugt die Schreiboperation eine Ausnahme. Der Bedingungsausdruck kann überprüfen, ob das Element bereits existiert oder ob seine Attribute bestimmten Beschränkungen entsprechen. `ConditionExpression = "version = :ver AND size(VideoClip) < :maxsize" ` Wenn der Bedingungsausdruck fehlschlägt, können Sie `ReturnValuesOnConditionCheckFailure` verwenden, um anzufordern, dass die Fehlermeldung das Element enthält, das die Bedingungen nicht erfüllt hat. So können Sie leichter nachvollziehen, worin das Problem bestand. Weitere Informationen finden Sie unter [Behandeln von bedingten Schreibfehlern in Szenarien mit hoher Parallelität mit Amazon DynamoDB](https://aws.amazon.com/blogs/database/handle-conditional-write-errors-in-high-concurrency-scenarios-with-amazon-dynamodb/). ``` try { const response = await client.send(new PutCommand({ TableName: "YourTableName", Item: item, ConditionExpression: "attribute_not_exists(pk)", ReturnValuesOnConditionCheckFailure: "ALL_OLD" })); } catch (e) { if (e.name === 'ConditionalCheckFailedException') { console.log('Item already exists:', e.Item); } else { throw e; } } ``` [Zusätzliche Codebeispiele, die andere Aspekte der Verwendung von JavsScript SDK V3 zeigen, sind in der [JavaScript SDK V3-Dokumentation](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/javascript_dynamodb_code_examples.html) und im Repository verfügbar. DynamoDB-SDK-Examples GitHub ](https://github.com/aws-samples/aws-dynamodb-examples/tree/master/examples/SDK/node.js) ## Paginierung **Topics** + [Verwenden der `paginateScan`-Komfortmethode](#using-the-paginatescan-convenience-method) Leseanfragen wie `Scan` oder `Query` geben wahrscheinlich mehrere Elemente in einem Datensatz zurück. Wenn Sie einen `Scan` oder eine `Query` mit einem `Limit`-Parameter durchführen, sendet das System nach dem Lesen dieser Anzahl von Elementen eine Teilantwort, und Sie müssen die Ergebnisse paginieren, um weitere Elemente abzurufen. Das System liest pro Anfrage maximal 1 Megabyte an Daten. Wenn Sie einen `Filter`-Ausdruck verwenden, liest das System weiterhin maximal ein Megabyte von der Festplatte, gibt jedoch nur die Elemente dieses Megabytes zurück, die dem Filter entsprechen. Die Filteroperation kann für eine Seite null Elemente zurückgeben, erfordert aber dennoch eine weitere Paginierung, bevor die Suche abgeschlossen ist. Sie sollten im Antwortobjekt nach dem `LastEvaluatedKey` suchen und diesen als `ExclusiveStartKey`-Parameter in einer nachfolgenden Anfrage verwenden, um die Datenabfrage fortzusetzen. Dies dient als eine Art Lesezeichen, wie im folgenden Beispiel gezeigt. **Anmerkung** Im Beispiel wird beim ersten Durchlauf ein null-Wert für `lastEvaluatedKey` als `ExclusiveStartKey` übergeben, und das ist zulässig. Beispiel - Verwenden des `LastEvaluatedKey`: ``` const { DynamoDBClient, ScanCommand } = require("@aws-sdk/client-dynamodb"); const client = new DynamoDBClient({}); async function paginatedScan() { let lastEvaluatedKey; let pageCount = 0; do { const params = { TableName: "products", ExclusiveStartKey: lastEvaluatedKey, }; const response = await client.send(new ScanCommand(params)); pageCount++; console.log(`Page ${pageCount}, Items:`, response.Items); lastEvaluatedKey = response.LastEvaluatedKey; } while (lastEvaluatedKey); } paginatedScan().catch((err) => { console.error(err); }); ``` ### Verwenden der `paginateScan`-Komfortmethode Das SDK stellt Komfortmethoden namens `paginateScan` und `paginateQuery` bereit, die diese Arbeit für Sie übernehmen und die wiederholten Anfragen im Hintergrund ausführen. Die maximale Anzahl der pro Anfrage zu lesenden Elemente geben Sie über den Standardparameter `Limit` an. ``` const { DynamoDBClient, paginateScan } = require("@aws-sdk/client-dynamodb"); const client = new DynamoDBClient({}); async function paginatedScanUsingPaginator() { const params = { TableName: "products", Limit: 100 }; const paginator = paginateScan({client}, params); let pageCount = 0; for await (const page of paginator) { pageCount++; console.log(`Page ${pageCount}, Items:`, page.Items); } } paginatedScanUsingPaginator().catch((err) => { console.error(err); }); ``` **Anmerkung** Regelmäßige vollständige Tabellenscans sind kein empfohlenes Zugriffsmuster, es sei denn, die Tabelle ist klein. ## Angeben der Konfiguration **Topics** + [Config für Timeouts](#programming-with-javascript-config-timeouts) + [Config für Keepalive](#programming-with-javascript-config-keep-alive) + [Config für Wiederholungsversuche](#programming-with-javascript-config-retries) Beim Einrichten des `DynamoDBClient` können Sie verschiedene Konfigurationsüberschreibungen festlegen, indem Sie ein Konfigurationsobjekt an den Konstruktor übergeben. Beispielsweise können Sie die Region angeben, mit der eine Verbindung hergestellt werden soll, falls sie dem aufrufenden Kontext nicht bereits bekannt ist, oder die zu verwendende Endpunkt-URL. Dies ist besonders nützlich, wenn Sie eine lokale DynamoDB-Instance für Entwicklungszwecke ansprechen möchten. ``` const client = new DynamoDBClient({ region: "eu-west-1", endpoint: "http://localhost:8000", }); ``` ### Config für Timeouts DynamoDB verwendet HTTPS für die Client-Server-Kommunikation. Sie können einige Aspekte der HTTP-Ebene steuern, indem Sie ein `NodeHttpHandler`-Objekt bereitstellen. Beispielsweise können Sie die wichtigsten Timeout-Werte `connectionTimeout` und `requestTimeout` anpassen. `connectionTimeout` ist die maximale Dauer in Millisekunden, die der Client beim Versuch, eine Verbindung herzustellen, wartet, bevor er aufgibt. `requestTimeout` legt fest, wie lange der Client nach dem Senden einer Anfrage auf eine Antwort wartet, ebenfalls in Millisekunden. Die Standardwerte für beide Parameter sind null, was bedeutet, dass kein Timeout aktiviert ist und der Client unbegrenzt auf eine Antwort wartet, falls diese nicht eintrifft. Es ist empfehlenswert, sinnvolle Timeout-Werte zu setzen, damit bei Netzwerkproblemen ein Fehler ausgelöst wird und eine neue Anfrage gestartet werden kann. Beispiel: ``` import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; import { NodeHttpHandler } from "@smithy/node-http-handler"; const requestHandler = new NodeHttpHandler({ connectionTimeout: 2000, requestTimeout: 2000, }); const client = new DynamoDBClient({ requestHandler }); ``` **Anmerkung** Im bereitgestellten Beispiel wird der [Smithy](https://smithy.io/2.0/index.html)-Import verwendet. Smithy ist eine Sprache zur Definition von Diensten und ist eine Open-Source-Sprache SDKs, die von verwaltet wird. AWS Zusätzlich zur Konfiguration von Timeout-Werten können Sie die maximale Anzahl von Sockets festlegen, was eine höhere Anzahl gleichzeitiger Verbindungen pro Ursprung ermöglicht. Der Entwicklerleitfaden enthält [Details zur Konfiguration des Parameters `maxSockets`](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/node-configuring-maxsockets.html). ### Config für Keepalive Bei der Verwendung von HTTPS erfordert die erste Anfrage immer eine gewisse back-and-forth Kommunikation, um eine sichere Verbindung herzustellen. HTTP Keepalive ermöglicht es, dass nachfolgende Anfragen die bereits aufgebaute Verbindung wiederverwenden, wodurch die Effizienz steigt und die Latenz sinkt. HTTP Keep-Alive ist standardmäßig mit JavaScript V3 aktiviert. Es gibt jedoch eine Begrenzung, wie lange eine inaktive Verbindung aufrechterhalten werden kann. Wenn Sie eine Verbindung im Leerlauf haben, die für die nächste Anfrage wiederverwendet werden soll, sollten Sie in Erwägung ziehen, regelmäßig Anfragen zu senden, z. B. einmal pro Minute. **Anmerkung** Beachten Sie, dass in der älteren V2-Version des SDK Keepalive standardmäßig deaktiviert war, was bedeutet, dass jede Verbindung unmittelbar nach der Nutzung geschlossen wurde. Wenn Sie V2 verwenden, können Sie diese Einstellung überschreiben. ### Config für Wiederholungsversuche Wenn das SDK eine Fehlermeldung erhält und der Fehler laut SDK als wiederholbar gilt, z. B. bei einer Drosselungsausnahme oder einem temporären Service-Ausnahmefehler, wird automatisch ein erneuter Versuch gestartet. Dies geschieht für den Aufrufer unsichtbar, außer dass die Anfrage möglicherweise etwas länger dauert, bis sie erfolgreich ist. Das SDK für JavaScript V3 stellt standardmäßig insgesamt 3 Anfragen, bevor es aufgibt und den Fehler an den aufrufenden Kontext weitergibt. Sie können sowohl die Anzahl als auch die Frequenz dieser Wiederholungen anpassen. Der Konstruktor des `DynamoDBClient` akzeptiert die Einstellung `maxAttempts`, mit der Sie die maximale Anzahl von Versuchen festlegen können. Im folgenden Beispiel wird der Wert von standardmäßig 3 auf insgesamt 5 erhöht. Wenn Sie ihn auf 0 oder 1 setzen, bedeutet das, dass Sie keine automatischen Wiederholungen wünschen und wiederholbare Fehler selbst im catch-Block behandeln möchten. ``` const client = new DynamoDBClient({ maxAttempts: 5, }); ``` Sie können das Timing der Wiederholungen mit einer benutzerdefinierten Wiederholungsstrategie steuern. Dazu importieren Sie das Hilfspaket `util-retry` und erstellen eine benutzerdefinierte Backoff-Funktion, die die Wartezeit zwischen den Wiederholungen basierend auf der aktuellen Anzahl der Versuche berechnet. Im folgenden Beispiel sind maximal 5 Versuche vorgesehen, mit Verzögerungen von 15, 30, 90 und 360 Millisekunden, falls der erste Versuch fehlschlägt. Die benutzerdefinierte Backoff-Funktion ` calculateRetryBackoff` nimmt die Nummer des Wiederholungsversuchs entgegen (beginnend mit 1 für den ersten Wiederholungsversuch) und gibt die Anzahl der Millisekunden zurück, die vor dem nächsten Versuch gewartet werden sollen. ``` const { ConfiguredRetryStrategy } = require("@aws-sdk/util-retry"); const calculateRetryBackoff = (attempt) => { const backoffTimes = [15, 30, 90, 360]; return backoffTimes[attempt - 1] || 0; }; const client = new DynamoDBClient({ retryStrategy: new ConfiguredRetryStrategy( 5, // max attempts. calculateRetryBackoff // backoff function. ), }); ``` ## Waiter Der DynamoDB-Client enthält außerdem zwei nützliche [Waiter-Funktionen](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/dynamodb/wait/index.html#cli-aws-dynamodb-wait), die beim Erstellen, Ändern oder Löschen von Tabellen verwendet werden können, wenn der Code erst fortfahren soll, nachdem die Tabellenoperation abgeschlossen ist. Beispielsweise können Sie eine Tabelle bereitstellen, die Funktion `waitUntilTableExists` aufrufen, und der Code blockiert dann, bis die Tabelle in den Status **ACTIVE** wechselt. Der Waiter fragt den DynamoDB-Service alle 20 Sekunden intern über `describe-table` ab. ``` import {waitUntilTableExists, waitUntilTableNotExists} from "@aws-sdk/client-dynamodb"; … const results = await waitUntilTableExists({client: client, maxWaitTime: 180}, {TableName: "products"}); if (results.state == 'SUCCESS') { return results.reason.Table } console.error(`${results.state} ${results.reason}`); ``` Die Funktion `waitUntilTableExists` gibt die Kontrolle erst dann zurück, wenn ein `describe-table`-Befehl erfolgreich ausgeführt werden kann, der den Tabellenstatus als **ACTIVE** bestätigt. Dadurch können Sie `waitUntilTableExists` nicht nur verwenden, um auf die vollständige Erstellung einer Tabelle zu warten, sondern auch auf Änderungen wie das Hinzufügen eines GSI-Index, dessen Anwendung einige Zeit in Anspruch nehmen kann, bevor die Tabelle wieder den Status **ACTIVE** erreicht. ## Fehlerbehandlung In den bisherigen Beispielen wurden alle Fehler pauschal abgefangen. In praktischen Anwendungen ist es jedoch wichtig, zwischen verschiedenen Fehlertypen zu unterscheiden und eine präzisere Fehlerbehandlung zu implementieren. Fehlermeldungen von DynamoDB enthalten Metadaten, darunter den Namen des Fehlers. Sie können Fehler abfangen und anhand der möglichen Fehlerbezeichnungen entscheiden, wie weiter vorzugehen ist. Bei serverseitigen Fehlern können Sie den Operator `instanceof` zusammen mit den im Paket `@aws-sdk/client-dynamodb` exportierten Fehlertypen verwenden, um die Fehlerbehandlung effizient zu gestalten. Beachten Sie, dass diese Fehler erst auftreten, nachdem alle Wiederholungsversuche ausgeschöpft wurden. Wenn ein Fehler erneut versucht und schließlich erfolgreich abgeschlossen wird, erscheint aus Sicht des Codes kein Fehler, sondern nur eine leicht erhöhte Latenz. Wiederholungen werden in den CloudWatch Amazon-Diagrammen als erfolglose Anfragen angezeigt, z. B. Drosselungs- oder Fehleranfragen. Wenn der Client die maximale Anzahl an Wiederholungen erreicht, gibt er auf und löst eine Ausnahme aus. Dies signalisiert, dass keine weiteren Wiederholungen erfolgen werden. Im Folgenden sehen Sie einen Codeausschnitt, der zeigt, wie Sie einen Fehler abfangen und je nach Fehlertyp entsprechend reagieren können. ``` import { ResourceNotFoundException ProvisionedThroughputExceededException, DynamoDBServiceException, } from "@aws-sdk/client-dynamodb"; try { await client.send(someCommand); } catch (e) { if (e instanceof ResourceNotFoundException) { // Handle ResourceNotFoundException } else if (e instanceof ProvisionedThroughputExceededException) { // Handle ProvisionedThroughputExceededException } else if (e instanceof DynamoDBServiceException) { // Handle DynamoDBServiceException } else { // Other errors such as those from the SDK if (e.name === "TimeoutError") { // Handle SDK TimeoutError. } else { // Handle other errors. } } } ``` Allgemeine Fehlerzeichenfolgen finden Sie unter [Fehlerbehandlung mit DynamoDB](Programming.Errors.md) im *DynamoDB-Entwicklerhandbuch*. Die genauen Fehler, die bei einem bestimmten API-Aufruf auftreten können, finden Sie in der Dokumentation zu diesem API-Aufruf, z. B. in den [Abfrage-API-Dokumenten](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html). Die Metadaten von Fehlern enthalten je nach Fehler zusätzliche Eigenschaften. Bei einem ` TimeoutError` enthält die Fehlermeldung Metadaten wie die Anzahl der durchgeführten Versuche und die `totalRetryDelay`, wie im Folgenden gezeigt. ``` { "name": "TimeoutError", "$metadata": { "attempts": 3, "totalRetryDelay": 199 } } ``` Wenn Sie Ihre eigene Wiederholungsrichtlinie verwalten, sollten Sie zwischen Drosselungen und Fehlern unterscheiden: + Eine **Drosselung** (gekennzeichnet durch ` ProvisionedThroughputExceededException` oder `ThrottlingException`) weist auf einen fehlerfreien Service hin, der Sie darüber informiert, dass Sie Ihre Lese- oder Schreibkapazität in einer DynamoDB-Tabelle oder Partition überschritten haben. Mit jeder Millisekunde, die vergeht, wird etwas mehr Lese- oder Schreibkapazität zur Verfügung gestellt, sodass Sie schnell, z. B. alle 50 ms, erneut versuchen können, auf die neu freigegebene Kapazität zuzugreifen. Bei Drosselungen ist kein exponentieller Backoff erforderlich, da Drosselungen für DynamoDB leichtgewichtig sind und keine Gebühren pro Anfrage anfallen. Exponentielles Backoff weist längere Wartezeiten jenen Client-Threads zu, die bereits am längsten gewartet haben, wodurch sich die statistischen Kennzahlen p50 und p99 weiter nach außen verschieben. + Ein **Fehler** (z. B. ` InternalServerError` oder `ServiceUnavailable`) weist auf ein vorübergehendes Problem mit dem Service, möglicherweise der gesamten Tabelle oder nur mit der Partition hin, aus der Sie lesen oder in die Sie schreiben. Bei Fehlern sollten Sie längere Pausen zwischen den Wiederholungsversuchen einlegen (etwa 250 ms oder 500 ms) und Jitter verwenden, um die Wiederholungen zeitlich zu staffeln. ## Protokollierung Aktivieren Sie die Protokollierung, um mehr Details darüber zu erhalten, was das SDK im Hintergrund tut. Sie können dazu einen Parameter im `DynamoDBClient` setzen, wie im folgenden Beispiel gezeigt. Zusätzliche Protokollinformationen erscheinen in der Konsole und enthalten Metadaten wie den Statuscode und die verbrauchte Kapazität. Wenn Sie den Code lokal in einem Terminalfenster ausführen, erscheinen die Protokolle dort. Wenn Sie den Code ausführen und CloudWatch Amazon-Logs eingerichtet haben, wird die Konsolenausgabe dort geschrieben. AWS Lambda ``` const client = new DynamoDBClient({ logger: console }); ``` Sie können auch in die internen Aktivitäten des SDK eingreifen und benutzerdefinierte Protokollierung durchführen, sobald bestimmte Ereignisse eintreten. Das folgende Beispiel verwendet den `middlewareStack` des Clients, um jede Anfrage abzufangen, während sie vom SDK gesendet wird, und sie in Echtzeit zu protokollieren. ``` const client = new DynamoDBClient({}); client.middlewareStack.add( (next) => async (args) => { console.log("Sending request from AWS SDK", { request: args.request }); return next(args); }, { step: "build", name: "log-ddb-calls", } ); ``` Der `MiddlewareStack` bietet eine leistungsstarke Schnittstelle, um das Verhalten des SDK zu beobachten und zu steuern. Weitere Informationen finden Sie im Blog [Introducing Middleware Stack in Modular AWS SDK für JavaScript](https://aws.amazon.com/blogs/developer/middleware-stack-modular-aws-sdk-js/). ## Überlegungen Bei der Implementierung AWS SDK für JavaScript in Ihrem Projekt sollten Sie folgende weitere Faktoren berücksichtigen. **Modulsysteme** Das SDK unterstützt zwei Modulsysteme, CommonJS und ES (ECMAScript). CommonJS verwendet die `require`-Funktion, während ES das `import`-Schlüsselwort verwendet. 1. **Common JS** – `const { DynamoDBClient, PutItemCommand } = require("@aws-sdk/client-dynamodb");` 1. **ES (ECMAScript**— `import { DynamoDBClient, PutItemCommand } from "@aws-sdk/client-dynamodb";` Der Projekttyp bestimmt, welches Modulsystem verwendet wird, und wird im Abschnitt Typ Ihrer package.json-Datei angegeben. Standardmäßig ist dies CommonJS. Verwenden Sie `"type": "module"`, um ein ES-Projekt zu kennzeichnen. Wenn Sie ein bestehendes Node.js-Projekt haben, das das CommonJS-Paketformat verwendet, können Sie dennoch Funktionen mit der moderneren Import-Syntax von SDK V3 hinzufügen, indem Sie Ihre Funktionsdateien mit der Endung .mjs benennen. Dadurch kann die Codedatei als ES (ECMAScript) behandelt werden. **Asynchrone Operationen** Viele Codebeispiele verwenden Callbacks und Promises, um die Ergebnisse von DynamoDB-Operationen zu verarbeiten. In der heutigen Zeit wird JavaScript diese Komplexität nicht mehr benötigt und Entwickler können die Vorteile der prägnanteren und lesbareren async/await Syntax für asynchrone Operationen nutzen. **Laufzeit des Webbrowsers** Web- und Mobilentwickler, die mit React oder React Native bauen, können das SDK für ihre JavaScript Projekte verwenden. Mit der früheren Version V2 des SDK mussten Webentwickler das vollständige SDK in den Browser laden und dabei auf ein SDK-Image verweisen, das unter https://sdk.amazonaws.com/js/ gehostet wird. Mit V3 ist es möglich, mit Webpack nur die erforderlichen V3-Client-Module und alle erforderlichen JavaScript Funktionen in einer einzigen JavaScript Datei zu bündeln und sie in einem Skript-Tag auf Ihren HTML-Seiten hinzuzufügen, wie im Abschnitt [Erste Schritte in einem Browserskript](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-started-browser.html) der SDK-Dokumentation beschrieben. `` **DAX-Operationen auf Datenebene** Die Datenebenenoperationen von Amazon DynamoDB Streams Accelerator (DAX) werden vom SDK für JavaScript V3 unterstützt.