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.
Exécution d'une opération de vente d'articles en vrac
Vous indiquez un emplacement Amazon S3 pour les fichiers d'entrée et une table cible. DynamoDB signale les éléments qu'il n'a pas pu écrire dans un compartiment de sortie que vous fournissez. Vous pouvez choisir le contenu du rapport de sortie via OutputType paramètre : demande ERROR pour les articles dont la validation a échoué, CONDITION_CHECK_FAILURE pour les articles qui ne répondaient pas à leur condition, ou les deux.
Vous pouvez exécuter une opération de vente en gros d'articles à l'aide du AWS CLI ou le AWS SDK. Pour utiliser le AWS CLI, installez-le d'abord et configurez-le avec votre AWS informations d'identification. Pour plus d’informations, consultez Accès à DynamoDB.
Ne modifiez pas les objets Amazon S3 pendant que l'opération est en cours. La modification des objets d'entrée peut entraîner l'échec de l'opération.
Rubriques
Démarrage d'une opération de vente d'articles en vrac
Pour démarrer une opération de vente en gros d'articles, appelez StartBulkPutItems et fournissez les entrées requises suivantes :
-
TableName — Le nom ou l'ARN de la table cible. La table doit être
ACTIVE, ouUPDATINGavec une modification qui n'entre pas en conflit avec les écritures en masse. Pour plus de détails, consultez Exigences relatives à l'état du tableau. -
Configuration des entrées 3 — L'emplacement Amazon S3 de vos fichiers d'entrée. Vous devez spécifier Seau S3 et InputFormat. Spécifiez éventuellement S3BucketOwner, S3KeyPrefix, et InputCompressionType.
-
Configuration des sorties 3 — Emplacement Amazon S3 pour le rapport de sortie. Vous devez spécifier à la fois
S3BucketetOutputType. Une configuration de sortie est obligatoire.
Les paramètres facultatifs suivants sont également disponibles :
-
PerformanceTier — Choisissez
STANDARD(par défaut) ouACCELERATED. Standard convient à la plupart des opérations où le délai de réalisation est flexible. Accelerated est conçu pour les charges de travail dont le temps d'exécution est plus rigide et vise un débit plus élevé que le standard, afin que les opérations de grande envergure puissent être terminées plus rapidement. Pour plus d’informations, consultez Niveaux de performance. -
MaxWriteRequestUnits — Dans le cadre de l'exploitation en vrac, MaxWriteRequestUnits est le nombre maximum d'unités de demande d'écriture par seconde avec lesquelles l'opération groupée peut écrire. La limite s'applique au nombre total d'unités de demande d'écriture que l'opération consomme sur la table et sur tous ses index. Par exemple, sur une table comportant deux index secondaires globaux qui projettent tous deux l'élément, une limite de 1 024 autorise environ 340 éléments de 1 Ko par seconde. Il doit être utilisé si vos opérations en aval sont sensibles à des débits d'écriture plus élevés. Ce paramètre s'applique uniquement aux opérations groupées et n'a aucun rapport avec la capacité provisionnée ou à la demande de la table. La valeur minimale est de 1 024.
-
ClientToken — Un jeton d'idempotence. Si vous réessayez une demande avec le même jeton client, DynamoDB renvoie l'opération existante au lieu d'en créer une nouvelle. DynamoDB conserve le jeton pendant 8 heures.
Formats d’entrée pris en charge
InputFormat accepte les valeurs suivantes :
DYNAMODB_JSONION
InputCompressionType accepte les valeurs suivantes :
GZIPZSTDNONE
Types de sortie
OutputType est une liste et vous pouvez demander l'un des types de rapports suivants ou les deux :
ERROR— Fournit un rapport sur les éléments qui ont échoué pour des raisons déterministes, telles que des erreurs de validation.CONDITION_CHECK_FAILURE— Fournit un rapport sur les éléments dont l'expression de condition par élément n'a pas été respectée.
Démarrage d'une opération (AWS CLI)
L'exemple suivant démarre une opération de mise en bloc d'éléments qui lit les fichiers JSON DynamoDB à partir d'un compartiment Amazon S3 et génère le rapport vers un compartiment distinct.
aws dynamodb start-bulk-put-items \ --table-name MusicCollection \ --input-s3-configuration '{ "S3Bucket": "amzn-s3-demo-bucket", "S3KeyPrefix": "daily/", "InputFormat": "DYNAMODB_JSON", "InputCompressionType": "NONE" }' \ --output-s3-configuration '{ "OutputType": ["ERROR"], "S3Bucket": "amzn-s3-demo-bucket1", "S3KeyPrefix": "bulk-put-items-output/" }' \ --performance-tier STANDARD
Démarrage d'une opération (Python)
L'exemple suivant utilise le AWS SDK pour Python (Boto3) permettant de démarrer une opération de mise en bloc d'éléments.
import boto3 client = boto3.client("dynamodb") response = client.start_bulk_put_items( TableName="MusicCollection", InputS3Configuration={ "S3Bucket": "amzn-s3-demo-bucket", "S3KeyPrefix": "daily/", "InputFormat": "DYNAMODB_JSON", "InputCompressionType": "NONE", }, OutputS3Configuration={ "S3Bucket": "amzn-s3-demo-bucket1", "OutputType": ["ERROR", "CONDITION_CHECK_FAILURE"], }, PerformanceTier="STANDARD", ) bulk_operation_arn = response["BulkOperationDescription"]["BulkOperationArn"] print(f"Started operation: {bulk_operation_arn}")
Surveillance de la progression
Appel DescribeBulkOperation pour suivre la progression d'une opération de vente d'articles en vrac. Trois domaines font état de progrès :
-
ProcessedItemCount — Le nombre d'enregistrements d'entrée lus jusqu'à présent, y compris les enregistrements dont la validation ou la vérification de l'état ont échoué. Il s'agit d'un décompte des enregistrements lus, et non des éléments écrits.
-
ProcessedInputBytes — Nombre d'octets lus et traités depuis Amazon S3 jusqu'à présent.
-
TotalInputBytes — Taille totale de tous les objets d'entrée dans Amazon S3.
Pour estimer les progrès, comparez ProcessedInputBytes pour TotalInputBytes. Par exemple, si votre saisie totalise 50 Go et ProcessedInputBytes affiche 35 Go, l'opération est terminée à environ 70 %.
TotalInputBytes est absent de la réponse jusqu'à ce que DynamoDB calcule le total lors de la validation initiale des entrées. Le temps de calcul varie en fonction des conditions de fonctionnement et de service. Sondage DescribeBulkOperation jusqu'à ce que le champ soit présent.
Les champs de progression sont mis à jour régulièrement et peuvent être mis à jour à différents moments. Ce ne sont pas des compteurs en direct. Ne vous fiez pas à un intervalle de rafraîchissement fixe.
Valeurs de statut
Le BulkOperationStatus Le champ renvoie l'une des valeurs suivantes :
IN_PROGRESS— L'opération consiste à lire les éléments de saisie et à écrire des éléments.COMPLETED— Toutes les entrées ont été lues etFailedItemCountest égal à 0. Les articles peuvent tout de même avoir échoué à la vérification de leur état. Si vous l'avez demandé, lisez leCONDITION_CHECK_FAILUREfaites un rapport pour les retrouver.COMPLETED_WITH_ERRORS— Toutes les entrées ont été lues etFailedItemCountest supérieur à 0. Passez en revue leERRORrapport.CANCELLING— Une demande d'annulation est en cours d'application.CANCELLED— L'opération s'est arrêtée en réponse à une demande d'annulation. Les éléments déjà écrits restent dans le tableau.CANCELLEDne signifie pas que des données sont manquantes. Le manifeste d'achèvement enregistre ce qui a été traité.FailureCodeestRequestCancelled.FAILED— L'opération n'a pas pu être terminée. Consultez le code d'échec.
Si une opération dépasse la durée de traitement maximale, DynamoDB arrête l'ingestion et l'opération prend fin FAILED avec code d'échec Timeout et le message « L'opération groupée a dépassé le temps de traitement maximum autorisé ». Le délai d'attente est un résultat attendu pour une entrée très volumineuse ou pour une opération dont le taux est plafonné avec MaxWriteRequestUnits, plutôt qu'un défaut. Les éléments déjà écrits restent dans le tableau et le manifeste d'achèvement indique dans quelle mesure chaque objet a été traité. Vous pouvez donc soumettre à nouveau le reste. Élever MaxWriteRequestUnits dans le StartBulkPutItems appeler ou diviser l'entrée en plusieurs objets réduit le risque d'un délai d'attente.
Le tableau suivant répertorie les codes d'erreur qu'un FAILED l'opération peut être signalée.
| Code d'échec | Cause | Que faire |
|---|---|---|
|
L'opération a dépassé le temps de traitement maximal |
Soumettez à nouveau le reste du manifeste d'achèvement |
|
Une erreur a empêché DynamoDB de lire un objet d'entrée et DynamoDB n'a pas pu confirmer qu'il avait lu tous les octets d'entrée stockés |
Corrigez l'enregistrement, puis soumettez-le à nouveau avec les enregistrements extérieurs |
|
Un objet d'entrée dépasse 5 Go |
Divisez l'objet |
|
Plus de 50 000 objets d'entrée |
Réduire le nombre d'objets ou demander une augmentation du quota |
|
Entrée totale supérieure à la limite par demande (100 Go pour la version standard, 1 To pour la version accélérée) |
Divisez l'entrée ou utilisez Accelerated |
|
Un objet d'entrée modifié au cours de l'exécution |
Conserver les objets d'entrée inchangés pendant l'exécution de l'opération |
|
DynamoDB n'a pas pu utiliser AWS Clé KMS pour la table ou les objets Amazon S3 pendant l'opération |
Vérifiez l'état de la clé et les autorisations clés de l'appelant |
|
DynamoDB s'est vu refuser l'accès à l'emplacement d'entrée ou de sortie dans Amazon S3. Ce code apparaît également lorsque |
Vérifiez les autorisations Amazon S3 de l'appelant, la politique en matière de compartiment et |
|
Une autre opération sur la même table a déjà commencé |
Attendez la fin de cette opération, puis recommencez |
|
La table n'a pas été trouvée ou n'était pas accessible |
Vérifiez le nom et l'état de la table |
|
L'appelant n'est plus autorisé à écrire dans la table |
Restaurer |
|
Une collection d'articles sur une table avec un index secondaire local a dépassé la limite de taille |
Réduire les données pour cette valeur de clé de partition |
Si DynamoDB ne parvient pas à générer le manifeste de complétion vers l'emplacement de sortie, l'opération s'arrête FAILED même si chaque article était écrit. Le message d'échec commence par « Le manifeste n'est pas disponible ». et le code de panne identifie la cause, par exemple S3AccessDenied. Les éléments déjà écrits restent dans le tableau. Vérifiez le Amazon S3 de l'appelant et AWS Autorisations KMS pour le préfixe de sortie, puis comparez le tableau avec votre entrée pour trouver ce qui a été écrit.
Décrire une opération (AWS CLI)
aws dynamodb describe-bulk-operation \ --bulk-operation-arn arn:aws:dynamodb:us-east-1:111122223333:bulk-operation/01759414677739-041d6d92
Décrire une opération (Python)
import boto3 client = boto3.client("dynamodb") response = client.describe_bulk_operation( BulkOperationArn="arn:aws:dynamodb:us-east-1:111122223333:bulk-operation/01759414677739-041d6d92" ) status = response["BulkOperationDescription"]["BulkOperationStatus"] processed_items = response["BulkOperationDescription"].get("ProcessedItemCount", 0) processed_bytes = response["BulkOperationDescription"].get("ProcessedInputBytes", 0) total_bytes = response["BulkOperationDescription"].get("TotalInputBytes") print(f"Status: {status}") print(f"Items processed: {processed_items}") if total_bytes: pct = (processed_bytes / total_bytes) * 100 print(f"Progress: {pct:.1f}%")
Liste des opérations en masse
Appel ListBulkOperations pour récupérer une liste paginée des opérations groupées de votre compte. Chaque page renvoie un maximum de 25 opérations.
Opérations de référencement (AWS CLI)
aws dynamodb list-bulk-operations
Le AWS CLI pagine automatiquement et imprime toutes les pages disponibles. Pour effectuer une page manuellement, désactivez la pagination automatique et utilisez --max-items avec --starting-token.
aws dynamodb list-bulk-operations \ --max-items 25 \ --starting-token "token-from-a-previous-NextToken"
Opérations de référencement (Python)
import boto3 client = boto3.client("dynamodb") paginator = client.get_paginator("list_bulk_operations") for page in paginator.paginate(): for op in page["BulkOperationsSummaryList"]: print(f"{op['BulkOperationArn']} - {op['BulkOperationStatus']}")
Annulation d'une opération
Appel CancelBulkOperation pour arrêter une opération en cours. L'opération passe à CANCELLING puis à CANCELLED.
Les articles déjà rédigés avant l'annulation sont pas annulé. Ils restent dans le tableau et sont immédiatement lisibles.
Alors que le statut est CANCELLING, les compteurs de progression peuvent être inférieurs aux valeurs finales. Attendre CANCELLED avant de vérifier vos résultats. Dans le manifeste, un objet partiellement traité a le statut PARTIALLY_PROCESSED, et processedRanges répertorie les enregistrements traités par DynamoDB. Enregistrements à l'extérieur processedRanges n'ont pas été traités. Soumettez-les à nouveau, ainsi que tous les enregistrements du ERROR rapport que vous avez corrigé.
Annulation d'une opération (AWS CLI)
aws dynamodb cancel-bulk-operation \ --bulk-operation-arn arn:aws:dynamodb:us-east-1:111122223333:bulk-operation/01759414677739-041d6d92
Annulation d'une opération (Python)
import boto3 client = boto3.client("dynamodb") client.cancel_bulk_operation( BulkOperationArn="arn:aws:dynamodb:us-east-1:111122223333:bulk-operation/01759414677739-041d6d92" ) print("Cancellation requested. Items already written remain in the table.")
Concurrence et quotas
Pour les quotas applicables aux opérations de vente en gros, voir Articles en vrac.
Vous ne pouvez pas démarrer une opération de placement groupé d'éléments sur une table qui crée un index. Si vous tentez de le faire, vous renvoyez un ResourceInUseException.
Une table ne peut contenir qu'une seule opération de mise en bloc d'articles en cours à la fois. Si une autre opération est en cours sur la table, StartBulkPutItems renvoie un ResourceInUseException. Si vous lancez plusieurs opérations sur la même table en même temps, chaque appel peut renvoyer un ARN. Une opération s'exécute alors et les autres échouent avec FailureCode ResourceInUseException. Appel DescribeBulkOperation pour confirmer que votre opération est en cours d'exécution. Pour charger plusieurs tables en même temps, lancez une opération pour chaque table.