View a markdown version of this page

Formats d'entrée Amazon S3 pour les articles vendus en vrac - Amazon DynamoDB

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Formats d'entrée Amazon S3 pour les articles vendus en vrac

DynamoDB Bulk Put Items lit les données d'entrée d'Amazon S3 dans deux formats : DynamoDB JSON et Amazon Ion. Vous pouvez fournir un seul objet Amazon S3 ou plusieurs objets sous le même objet. Préfixe de clé Amazon S3.

Chaque fichier d'entrée peut éventuellement contenir des expressions de condition par élément qui contrôlent si les éléments sont écrits dans la table. Les sections suivantes décrivent les formats pris en charge, les options de compression et le modèle d'expression conditionnelle.

Formats et compression pris en charge

Spécifiez le format d'entrée lorsque vous appelez StartBulkPutItems en réglant le InputFormat champ dans Configuration des entrées 3, le paramètre de demande qui décrit l'endroit où votre entrée est stockée dans Amazon S3 et comment elle est formatée. Pour tous les paramètres de demande, voir Démarrage d'une opération de vente d'articles en vrac.

Format Description

DYNAMODB_JSON

DynamoDB a compilé le JSON. Un objet JSON par ligne (Lignes JSON format). Chaque ligne contient un Item champ et champs de condition facultatifs.

ION

Format de texte Amazon Ion. Chaque enregistrement est une structure ionique contenant un Item champ et champs de condition facultatifs, délimités par des nouvelles lignes.

Réglez le InputCompressionType champ pour indiquer comment vos objets Amazon S3 sont compressés.

Type de compression Description

GZIP

Les objets sont GZIP-compressed.

ZSTD

Les objets sont Zstandard-compressed.

NONE

Les objets sont décompressés.

JSON DynamoDB

Un fichier au format JSON DynamoDB se compose d'un objet JSON par ligne (Lignes JSON format). Chaque ligne contient un Item champ au format JSON marshalled de DynamoDB et champs conditionnels facultatifs. N'utilisez pas de nouvelles lignes dans un seul enregistrement. Pour savoir comment fonctionnent les champs de condition, voir Per-item expressions de condition.

Put inconditionnel (comportement par défaut)

Lorsque vous omettez des champs de condition, chaque élément remplace tout élément existant par la même clé primaire :

{"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"}}}

État simple — insert uniquement

Ajouter attribute_not_exists(pk) pour éviter les écrasements. Remplacer pk avec le nom de l'attribut de votre clé de partition :

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

Expression nommée avec jetons de substitution

Utiliser ExpressionAttributeNames et ExpressionAttributeValues lorsque votre condition fait référence à des mots réservés ou remplace des valeurs d'attributs :

{"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"}}}

Dans le premier enregistrement, l'élément n'est écrit que si l'élément existant est status attribut est égal ACTIVE. Dans le deuxième enregistrement, l'élément n'est écrit que si l'élément existant est version est inférieur à 2.

Conditions mixtes dans un seul fichier

Différents enregistrements d'un même fichier peuvent comporter des conditions différentes, voire aucune condition :

{"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"}}}

Dans cet exemple, le premier enregistrement utilise une sémantique d'insertion uniquement. Le deuxième enregistrement utilise une protection de version. Le troisième enregistrement est remplacé inconditionnellement car il ne comporte aucune condition.

Amazon Ion

Amazon Ion est un format de sérialisation de données hiérarchique richement typé et autodescriptif. Lorsque vous utilisez le format Ion pour des éléments mis en lot, les types de données Ion sont mappés aux types de données DynamoDB dans la table cible.

Chaque enregistrement est une structure ionique contenant un Item champ et champs de condition facultatifs, délimités par des nouvelles lignes. Chaque ligne commence par un marqueur de version Ion.

Put inconditionnel

Note

Dans l'exemple suivant, les éléments sont mis en forme sur plusieurs lignes pour améliorer la lisibilité. Dans les fichiers d'entrée réels, chaque enregistrement se trouve sur une seule ligne.

$ion_1_0 { Item:{ id:"order-001", amount:99.95, status:"PENDING" } } $ion_1_0 { Item:{ id:"order-002", amount:149.00, status:"SHIPPED" } }

Avec expression de condition par article

$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"} }

Le tableau suivant montre comment les types de données Ion sont mappés aux types de données DynamoDB.

Type de données Ion Représentation DynamoDB

string

String (S)

bool

Boolean (BOOL)

decimal

Number (N)

blob

Binary (B)

list (avec annotation) $dynamodb_SS, $dynamodb_NS, ou $dynamodb_BS)

Set (SS, NS, BS)

list

List (L)

struct

Map (M)

Disposition des données sources dans Amazon S3

Vous pouvez fournir votre saisie sous la forme d'un seul objet Amazon S3 ou de plusieurs objets stockés sous le même préfixe de clé S3. Lorsque vous réglez le S3KeyPrefix champ dans InputS3Configuration, DynamoDB lit tous les objets situés sous ce préfixe de clé S3. Pour obtenir des conseils sur la façon de fractionner votre saisie, voir Meilleures pratiques pour les articles en vrac dans DynamoDB.

Note

Tous les objets sous le préfixe de clé S3 spécifié doivent utiliser le même format et le même type de compression. Vous ne pouvez pas mélanger des objets DynamoDB JSON et Ion, ni mélanger des objets compressés et non compressés en une seule opération de mise en bloc d'éléments.

Per-item expressions de condition

Les expressions de condition pour les articles vendus en vrac sont spécifiées par rubrique, dans le fichier d'entrée. Elles utilisent la même syntaxe que les expressions de condition pour PutItem opération. Pour la syntaxe complète, voir Exemple de commande CLI d’expression de condition DynamoDB. Pour les opérateurs et les fonctions pris en charge, voir Expressions de condition et de filtre, opérateurs et fonctions dans DynamoDB.

Chaque enregistrement de votre fichier d'entrée contient les champs suivants :

  • Item (obligatoire) : élément à écrire, au format JSON ou Ion Marshalled DynamoDB.

  • ConditionExpression (facultatif) — Expression de condition qui doit être évaluée à true pour que l'élément soit écrit.

  • ExpressionAttributeNames (facultatif) — Carte des jetons de substitution pour les noms d'attributs dans l'expression de condition.

  • ExpressionAttributeValues (facultatif) — Carte des jetons de substitution pour les valeurs d'attribut dans l'expression de condition.

Comportement d'évaluation des conditions

Le tableau suivant décrit la manière dont DynamoDB évalue les expressions de condition lors d'une opération de mise en lot d'éléments.

Scénario Comportement

Aucune condition sur un dossier

L'élément est écrit de manière inconditionnelle, remplaçant tout élément existant par la même clé primaire.

attribute_not_exists(pk)

Insert-only sémantique pour cet enregistrement. L'élément est écrit uniquement si aucun élément avec la même clé primaire n'existe déjà dans la table.

Per-item version guard

Vous pouvez spécifier une condition qui vérifie un attribut de version, par exemple #v = :expected. Cela permet une migration interrégionale sécurisée et des cas d'utilisation de synchronisation incrémentielle. Pour écrire à la fois de nouveaux articles et des versions plus récentes, utilisez attribute_not_exists(#v) OR #v < :new.

Condition non remplie

L'élément est ignoré. DynamoDB signale l'élément ignoré uniquement si vous demandez CONDITION_CHECK_FAILURE type de sortie. Pour plus d’informations, consultez Signalement des défaillances.

Important

Les articles qui ne sont pas soumis à un contrôle d'état sont toujours facturés. Pour plus de détails, consultez Facturation pour les rapports et les articles ayant échoué.

Pour obtenir une sémantique d'insertion de nouveaux éléments uniquement

Comme les conditions sont définies par élément, vous devez inclure un ConditionExpression sur chaque enregistrement si vous souhaitez un comportement d'ajout s'il n'existe pas dans l'ensemble du fichier. L'exemple suivant montre un fichier d'entrée JSON DynamoDB dans lequel chaque enregistrement contient attribute_not_exists(id) pour éviter les écrasements :

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

Si vous générez des fichiers d'entrée à partir d'un pipeline ETL, ajoutez le ConditionExpression champ de votre modèle d'enregistrement. Si vous avez des fichiers existants sans conditions, retraitez-les pour injecter la condition avant de démarrer l'opération.

Signalement des défaillances

Lorsque vous configurez votre emplacement Amazon S3 de sortie, incluez CONDITION_CHECK_FAILURE dans le OutputType liste. DynamoDB génère les enregistrements des éléments qui ne satisfaisaient pas à leur expression de condition dans votre compartiment Amazon S3 de sortie. Vous pouvez analyser ces fichiers de sortie pour identifier les éléments qui ont été ignorés et prendre des mesures correctives. Lorsque votre saisie utilise des expressions de condition, demandez CONDITION_CHECK_FAILURE les éléments ignorés sont donc signalés, car sans cela, DynamoDB n'en conserve aucun enregistrement ni aucun décompte.

Une nouvelle tentative ou une reprise d'une opération peut signaler un conflit de vérification de l'état d'un élément que l'opération elle-même avait écrit précédemment. Pour distinguer cela d'un conflit avec des données préexistantes, comparez l'image existante dans le rapport avec l'élément que vous avez fourni. S'ils sont égaux, l'opération a écrit cet élément et le conflit est attendu.

Les éléments rapportés ici n'ont pas été écrits lors de la tentative qui a produit l'enregistrement. Ils sont toujours facturés. Pour plus d’informations, consultez Facturation pour les rapports et les articles ayant échoué. Pour réconcilier les résultats d'une opération d'achat groupé d'articles, utilisez les fichiers de sortie Amazon S3 ainsi que DescribeBulkOperation compte. Pour le flux de travail complet, voir Concilier les résultats.

Erreurs de validation qui arrêtent un objet

Certaines erreurs empêchent DynamoDB de localiser la limite d'enregistrement suivante. Ces erreurs incluent un JSON ou un Ion mal formé ou tronqué, une structure d'enregistrement non valide, un fichier manquant ou dupliqué Item champ, champ de premier niveau inconnu, valeurs DynamoDB non valides, non valides UTF-8, une entrée qui atteint la limite d'imbrication de l'analyseur, un enregistrement qui dépasse la limite de lecture de l'analyseur, des erreurs de décompression, une non-concordance de compression et certaines erreurs de lecture d'objets Amazon S3. Un enregistrement ne peut contenir que les champs de niveau supérieur suivants : Item, ConditionExpression, ExpressionAttributeNames, et ExpressionAttributeValues.

Lorsque l'une de ces erreurs se produit, DynamoDB génère un résultat d'erreur et arrête de lire cet objet Amazon S3. Les autres objets de saisie peuvent continuer. Si vous avez demandé ERROR sortie, la ligne du rapport contient itemLocation.inputSourceArn et errorMessages, mais il ne contient pas itemLocation.itemIndex. Une erreur de validation qui s'applique à un enregistrement complet comprend itemIndex et n'arrête pas le reste de l'objet.

Le manifeste de complétion marque l'objet PARTIALLY_PROCESSED et répertorie les enregistrements complétés dans processedRanges. Si DynamoDB ne peut pas confirmer qu'il a lu tous les octets d'entrée stockés, l'opération s'arrête FAILED avec code d'échec ValidationException. Si DynamoDB lit tous les octets stockés avant de détecter l'erreur, l'opération peut prendre fin COMPLETED_WITH_ERRORS avec ProcessedInputBytes égal à TotalInputBytes. Utilisez le statut final, ERROR rapport et manifeste de complétion combinés pour identifier les enregistrements à corriger ou à soumettre à nouveau. DynamoDB ne facture pas les enregistrements rejetés lors de la validation lors de l'écriture de tables. Pour plus d'informations, consultez Facturation pour les rapports et les articles ayant échoué.