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.
Amazon S3-Eingabeformate für Artikel in großen Mengen
DynamoDB Bulk Put Items liest Eingabedaten aus Amazon S3 in zwei Formaten: DynamoDB JSON und Amazon Ion. Sie können ein einzelnes Amazon S3-Objekt oder mehrere Objekte unter demselben Namen bereitstellen Amazon S3-Schlüsselpräfix.
Jede Eingabedatei kann optional Bedingungsausdrücke pro Element enthalten, die steuern, ob Elemente in die Tabelle geschrieben werden. In den folgenden Abschnitten werden die unterstützten Formate, Komprimierungsoptionen und das Bedingungsausdrucksmodell beschrieben.
Themen
Unterstützte Formate und Komprimierung
Geben Sie das Eingabeformat an, wenn Sie anrufen StartBulkPutItems indem Sie das einstellen InputFormat Feld ein Gibt die S3-Konfiguration ein, der Anforderungsparameter, der beschreibt, wo Ihre Eingabe in Amazon S3 gespeichert ist und wie sie formatiert wird. Alle Anforderungsparameter finden Sie unter Starten eines Massen-Put-Vorgangs für Artikel.
| Format | Description |
|---|---|
|
DynamoDB hat JSON gemarshallt. Ein JSON-Objekt pro Zeile (JSON-Zeilen |
|
Amazon Ion Textformat. Jeder Datensatz ist eine Ion-Struktur, die eine enthält |
Stellen Sie das ein InputCompressionType Feld, um anzugeben, wie Ihre Amazon S3-Objekte komprimiert werden.
| Komprimierungsart | Description |
|---|---|
|
Objekte sind GZIP-compressed. |
|
Objekte sind Zstandard-compressed. |
|
Objekte sind unkomprimiert. |
DynamoDB JSON
Eine Datei im DynamoDB-JSON-Format besteht aus einem JSON-Objekt pro Zeile (JSON-ZeilenItem Feld in DynamoDB gemarshalltes JSON und optionale Bedingungsfelder. Verwenden Sie keine Zeilenumbrüche innerhalb eines einzelnen Datensatzes. Informationen zur Funktionsweise der Bedingungsfelder finden Sie unter Per-item Bedingungsausdrücke.
Bedingungsloses Put (Standardverhalten)
Wenn Sie Bedingungsfelder weglassen, überschreibt jedes Element jedes vorhandene Element mit demselben Primärschlüssel:
{"Item":{"id":{"S":"item-1"},"name":{"S":"Widget A"},"price":{"N":"9.99"}}} {"Item":{"id":{"S":"item-2"},"name":{"S":"Widget B"},"price":{"N":"14.99"}}} {"Item":{"id":{"S":"item-3"},"name":{"S":"Widget C"},"price":{"N":"4.99"}}}
Einfache Bedingung — nur einfügen
Hinzufügen attribute_not_exists( um Überschreibungen zu verhindern. Ersetzen pk)pk mit dem Namen Ihres Partitionsschlüsselattributs:
{"Item":{"id":{"S":"item-1"},"name":{"S":"Widget A"},"price":{"N":"9.99"}},"ConditionExpression":"attribute_not_exists(id)"} {"Item":{"id":{"S":"item-2"},"name":{"S":"Widget B"},"price":{"N":"14.99"}},"ConditionExpression":"attribute_not_exists(id)"}
Benannter Ausdruck mit Substitutionstoken
Verwenden ExpressionAttributeNames und ExpressionAttributeValues wenn Ihre Bedingung auf reservierte Wörter verweist oder Attributwerte ersetzt:
{"Item":{"id":{"S":"item-2"},"status":{"S":"ACTIVE"},"version":{"N":"3"}},"ConditionExpression":"#s = :v","ExpressionAttributeNames":{"#s":"status"},"ExpressionAttributeValues":{":v":{"S":"ACTIVE"}}} {"Item":{"id":{"S":"item-5"},"status":{"S":"PENDING"},"version":{"N":"2"}},"ConditionExpression":"#ver < :newver","ExpressionAttributeNames":{"#ver":"version"},"ExpressionAttributeValues":{":newver":{"N":"2"}}}
Im ersten Datensatz wird das Element nur geschrieben, wenn das vorhandene Element status Attribut ist gleich ACTIVE. Im zweiten Datensatz wird das Element nur geschrieben, wenn das vorhandene Element version ist kleiner als 2.
Gemischte Bedingungen in einer einzigen Datei
Verschiedene Datensätze in derselben Datei können unterschiedliche Bedingungen oder gar keine Bedingungen enthalten:
{"Item":{"id":{"S":"new-1"},"data":{"S":"hello"}},"ConditionExpression":"attribute_not_exists(id)"} {"Item":{"id":{"S":"existing-1"},"data":{"S":"updated"}},"ConditionExpression":"#v = :expected","ExpressionAttributeNames":{"#v":"version"},"ExpressionAttributeValues":{":expected":{"N":"5"}}} {"Item":{"id":{"S":"overwrite-1"},"data":{"S":"replaced"}}}
In diesem Beispiel verwendet der erste Datensatz eine reine Einfüge-Semantik. Der zweite Datensatz verwendet einen Versionsschutz. Der dritte Datensatz wird bedingungslos überschrieben, da er keine Bedingung hat.
Amazon Ion
Amazon Ion
Jeder Datensatz ist eine Ion-Struktur, die eine Item Feld- und optionale Bedingungsfelder, getrennt durch Zeilenumbrüche. Jede Zeile beginnt mit einer Ion-Versionsmarkierung.
Bedingungslos gesetzt
Im folgenden Beispiel werden Elemente mehrzeilig formatiert, um die Lesbarkeit zu verbessern. In tatsächlichen Eingabedateien befindet sich jeder Datensatz in einer einzelnen Zeile.
$ion_1_0 { Item:{ id:"order-001", amount:99.95, status:"PENDING" } } $ion_1_0 { Item:{ id:"order-002", amount:149.00, status:"SHIPPED" } }
Mit Bedingungsausdruck pro Artikel
$ion_1_0 { Item:{ id:"order-001", amount:99.95, status:"PENDING" }, ConditionExpression:"attribute_not_exists(id)" } $ion_1_0 { Item:{ id:"order-002", amount:149.00, status:"SHIPPED" }, ConditionExpression:"#s = :v", ExpressionAttributeNames:{"#s":"status"}, ExpressionAttributeValues:{":v":"ACTIVE"} }
Die folgende Tabelle zeigt, wie Ion-Datentypen DynamoDB-Datentypen zugeordnet werden.
| Ion-Datentyp | DynamoDB-Darstellung |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Layout der Quelldaten in Amazon S3
Sie können Ihre Eingabe als einzelnes Amazon S3-Objekt oder als mehrere Objekte angeben, die unter demselben S3-Schlüsselpräfix gespeichert sind. Wenn Sie das einstellen S3KeyPrefix Feld ein InputS3Configuration, DynamoDB liest alle Objekte unter diesem S3-Schlüsselpräfix. Eine Anleitung zum Aufteilen Ihrer Eingabe finden Sie unter Bewährte Methoden für Bulk-Put-Artikel in DynamoDB.
Alle Objekte unter dem angegebenen S3-Schlüsselpräfix müssen dasselbe Format und denselben Komprimierungstyp verwenden. Sie können DynamoDB-JSON- und Ion-Objekte nicht mischen oder komprimierte und unkomprimierte Objekte in einem einzigen Bulk-Put-Elementvorgang mischen.
Per-item Bedingungsausdrücke
Bedingungsausdrücke für Bulk-Out-Artikel sind angegeben pro Element, innerhalb der Eingabedatei. Sie verwenden dieselbe Syntax wie Bedingungsausdrücke für PutItem Betrieb. Die vollständige Syntax finden Sie unter CLI-Beispiel für DynamoDB-Bedingungsausdrücke. Die unterstützten Operatoren und Funktionen finden Sie unter Bedingungs- und Filterausdrücke, Operatoren und Funktionen in DynamoDB.
Jeder Datensatz in Ihrer Eingabedatei enthält die folgenden Felder:
Item(erforderlich) — Das zu schreibende Element im DynamoDB-Marshalled-JSON- oder Ion-Format.ConditionExpression(optional) — Ein Bedingungsausdruck, der als wahr ausgewertet werden muss, damit das Element geschrieben werden kann.ExpressionAttributeNames(optional) — Eine Zuordnung von Substitutionstoken für Attributnamen im Bedingungsausdruck.ExpressionAttributeValues(optional) — Eine Karte von Substitutionstoken für Attributwerte im Bedingungsausdruck.
Verhalten bei der Bewertung von Zuständen
In der folgenden Tabelle wird beschrieben, wie DynamoDB Bedingungsausdrücke während eines Bulk-Put-Vorgangs für Elemente auswertet.
| Szenario | Behavior |
|---|---|
Keine Bedingung für einen Datensatz |
Das Element wird bedingungslos geschrieben, wobei alle vorhandenen Elemente mit demselben Primärschlüssel überschrieben werden. |
|
Insert-only Semantik für diesen Datensatz. Das Element wird nur geschrieben, wenn in der Tabelle noch kein Element mit demselben Primärschlüssel vorhanden ist. |
Per-item Versionswächter |
Sie können eine Bedingung angeben, die ein Versionsattribut überprüft, zum Beispiel |
Bedingung nicht erfüllt |
Der Artikel wurde übersprungen. DynamoDB meldet das übersprungene Element nur, wenn Sie das anfordern |
Artikel, die eine Zustandsprüfung nicht bestehen, werden trotzdem in Rechnung gestellt. Details hierzu finden Sie unter Abrechnung für Berichte und fehlgeschlagene Artikel.
Um eine Semantik zu erreichen, bei der nur neue Artikel eingefügt werden
Da die Bedingungen pro Element gelten, müssen Sie eine angeben ConditionExpression für jeden Datensatz, wenn Sie das Verhalten put-if-not-exists für die gesamte Datei verwenden möchten. Das folgende Beispiel zeigt eine DynamoDB-JSON-Eingabedatei, in der jeder Datensatz Folgendes enthält attribute_not_exists(id) um Überschreibungen zu verhindern:
{"Item":{"id":{"S":"order-001"},"amount":{"N":"99.95"},"status":{"S":"PENDING"}},"ConditionExpression":"attribute_not_exists(id)"} {"Item":{"id":{"S":"order-002"},"amount":{"N":"149.00"},"status":{"S":"SHIPPED"}},"ConditionExpression":"attribute_not_exists(id)"} {"Item":{"id":{"S":"order-003"},"amount":{"N":"25.50"},"status":{"S":"DELIVERED"}},"ConditionExpression":"attribute_not_exists(id)"}
Wenn Sie Eingabedateien aus einer ETL-Pipeline generieren, fügen Sie die ConditionExpression Feld zu Ihrer Datensatzvorlage. Wenn Sie bereits Dateien ohne Bedingungen haben, verarbeiten Sie sie erneut, um die Bedingung einzufügen, bevor Sie den Vorgang starten.
Meldung von Zustandsfehlern
Wenn Sie Ihren Amazon S3-Ausgabestandort konfigurieren, geben Sie Folgendes an CONDITION_CHECK_FAILURE in der OutputType Liste. DynamoDB gibt Datensätze für Elemente, die ihren Bedingungsausdruck nicht erfüllt haben, in Ihren Amazon S3-Ausgabe-Bucket aus. Sie können diese Ausgabedateien analysieren, um festzustellen, welche Elemente übersprungen wurden, und Korrekturmaßnahmen ergreifen. Wenn Ihre Eingabe Bedingungsausdrücke verwendet, fordern Sie CONDITION_CHECK_FAILURE übersprungene Elemente werden also gemeldet, da DynamoDB ohne sie weder aufzeichnet noch zählt.
Ein wiederholter oder wiederaufgenommener Vorgang kann einen Konflikt bei der Zustandsprüfung für ein Element melden, das der Vorgang selbst zuvor geschrieben hat. Um dies von einem Konflikt mit bereits vorhandenen Daten zu unterscheiden, vergleichen Sie das vorhandene Bild im Bericht mit dem von Ihnen angegebenen Element. Wenn sie identisch sind, wurde das Element durch den Vorgang geschrieben, und der Konflikt wird erwartet.
Die hier gemeldeten Elemente wurden bei dem Versuch, der den Datensatz erzeugt hat, nicht geschrieben. Sie werden immer noch in Rechnung gestellt. Weitere Informationen finden Sie unter Abrechnung für Berichte und fehlgeschlagene Artikel. Verwenden Sie die Amazon S3-Ausgabedateien zusammen mit dem DescribeBulkOperation zählt. Den vollständigen Arbeitsablauf finden Sie unter Ergebnisse abgleichen.
Validierungsfehler, die ein Objekt stoppen
Einige Fehler verhindern, dass DynamoDB die nächste Datensatzgrenze findet. Zu diesen Fehlern gehören falsch formatierte oder gekürzte JSON- oder Ion-Dateien, eine ungültige Datensatzstruktur, ein fehlendes oder doppeltes Item Feld, ein unbekanntes Feld der obersten Ebene, ungültige DynamoDB-Werte, ungültig UTF-8, Eingabe, die das Verschachtelungslimit des Parsers erreicht, ein Datensatz, der das Leselimit des Parsers überschreitet, Dekomprimierungsfehler, eine Nichtübereinstimmung bei der Komprimierung und einige Amazon S3-Objektlesefehler. Ein Datensatz darf nur die folgenden Felder der obersten Ebene enthalten: Item, ConditionExpression, ExpressionAttributeNames, und ExpressionAttributeValues.
Wenn einer dieser Fehler auftritt, erzeugt DynamoDB ein Fehlerergebnis und stoppt das Lesen des Amazon S3-Objekts. Andere Eingabeobjekte können fortfahren. Wenn Sie darum gebeten haben ERROR Ausgabe, die Berichtszeile enthält itemLocation.inputSourceArn und errorMessages, aber es enthält nicht itemLocation.itemIndex. Ein Validierungsfehler, der für einen vollständigen Datensatz gilt, umfasst itemIndex und stoppt den Rest des Objekts nicht.
Das Abschlussmanifest markiert das Objekt PARTIALLY_PROCESSED und listet abgeschlossene Datensätze auf processedRanges. Wenn DynamoDB nicht bestätigen kann, dass alle gespeicherten Eingabebytes gelesen wurden, wird der Vorgang beendet FAILED mit Fehlercode ValidationException. Wenn DynamoDB alle gespeicherten Bytes liest, bevor der Fehler erkannt wird, kann der Vorgang beendet werden COMPLETED_WITH_ERRORS mit ProcessedInputBytes gleich TotalInputBytes. Benutze den endgültigen Status, ERROR Bericht und Abschlussmanifest zusammen, um Datensätze zu identifizieren, die korrigiert oder erneut eingereicht werden müssen. DynamoDB stellt keine Datensätze in Rechnung, die bei der Validierung beim Schreiben einer Tabelle abgelehnt werden. Weitere Informationen finden Sie unter Abrechnung für Berichte und fehlgeschlagene Artikel.