

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](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_OutputS3Configuration.html#DDB-Type-OutputS3Configuration-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](AccessingDynamoDB.md#Tools.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](AccessingDynamoDB.md).

**Note**  
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.

**Topics**
+ [Démarrage d'une opération de vente d'articles en vrac](#BulkPutItems.Requesting.Start)
+ [Surveillance de la progression](#BulkPutItems.Requesting.Describe)
+ [Liste des opérations en masse](#BulkPutItems.Requesting.List)
+ [Annulation d'une opération](#BulkPutItems.Requesting.Cancel)
+ [Concurrence et quotas](#BulkPutItems.Requesting.Limits)

## Démarrage d'une opération de vente d'articles en vrac
<a name="BulkPutItems.Requesting.Start"></a>

Pour démarrer une opération de vente en gros d'articles, appelez [StartBulkPutItems](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_StartBulkPutItems.html) et fournissez les entrées requises suivantes :
+ [TableName](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_StartBulkPutItems.html#DDB-StartBulkPutItems-request-TableName) — Le nom ou l'ARN de la table cible. La table doit être `ACTIVE`, ou `UPDATING` avec 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](BulkPutItems.Considerations.md#BulkPutItems.Considerations.TableState).
+ [Configuration des entrées 3](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_InputS3Configuration.html) — L'emplacement Amazon S3 de vos fichiers d'entrée. Vous devez spécifier [Seau S3](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_InputS3Configuration.html#DDB-Type-InputS3Configuration-S3Bucket) et [InputFormat](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_InputS3Configuration.html#DDB-Type-InputS3Configuration-InputFormat). Spécifiez éventuellement [S3BucketOwner](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_InputS3Configuration.html#DDB-Type-InputS3Configuration-S3BucketOwner), [S3KeyPrefix](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_InputS3Configuration.html#DDB-Type-InputS3Configuration-S3KeyPrefix), et [InputCompressionType](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_InputS3Configuration.html#DDB-Type-InputS3Configuration-InputCompressionType).
+ [Configuration des sorties 3](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_OutputS3Configuration.html) — Emplacement Amazon S3 pour le rapport de sortie. Vous devez spécifier à la fois `S3Bucket` et `OutputType`. Une configuration de sortie est obligatoire.

Les paramètres facultatifs suivants sont également disponibles :
+ [PerformanceTier](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_StartBulkPutItems.html#DDB-StartBulkPutItems-request-PerformanceTier) — Choisissez `STANDARD` (par défaut) ou `ACCELERATED`. 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](BulkPutItems.Tiers.md).
+ **MaxWriteRequestUnits** — Dans le cadre de l'exploitation en vrac, [MaxWriteRequestUnits](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_StartBulkPutItems.html#DDB-StartBulkPutItems-request-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](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_StartBulkPutItems.html#DDB-StartBulkPutItems-request-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
<a name="BulkPutItems.Requesting.Start.Formats"></a>

`InputFormat` accepte les valeurs suivantes :
+ `DYNAMODB_JSON`
+ `ION`

`InputCompressionType` accepte les valeurs suivantes :
+ `GZIP`
+ `ZSTD`
+ `NONE`

### Types de sortie
<a name="BulkPutItems.Requesting.Start.OutputType"></a>

`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)
<a name="BulkPutItems.Requesting.Start.CLI"></a>

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)
<a name="BulkPutItems.Requesting.Start.Python"></a>

L'exemple suivant utilise le AWS SDK pour Python (Boto3) permettant de démarrer une opération de mise en bloc d'éléments.

```python
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
<a name="BulkPutItems.Requesting.Describe"></a>

Appel [DescribeBulkOperation](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeBulkOperation.html) pour suivre la progression d'une opération de vente d'articles en vrac. Trois domaines font état de progrès :
+ [ProcessedItemCount](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BulkOperationDescription.html#DDB-Type-BulkOperationDescription-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](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BulkOperationDescription.html#DDB-Type-BulkOperationDescription-ProcessedInputBytes) pour [TotalInputBytes](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BulkOperationDescription.html#DDB-Type-BulkOperationDescription-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
<a name="BulkPutItems.Requesting.Describe.Status"></a>

Le [BulkOperationStatus](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BulkOperationDescription.html#DDB-Type-BulkOperationDescription-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 et `FailedItemCount` est égal à 0. Les articles peuvent tout de même avoir échoué à la vérification de leur état. Si vous l'avez demandé, lisez le `CONDITION_CHECK_FAILURE` faites un rapport pour les retrouver.
+ `COMPLETED_WITH_ERRORS` — Toutes les entrées ont été lues et `FailedItemCount` est supérieur à 0. Passez en revue le `ERROR` rapport.
+ `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. `CANCELLED` ne signifie pas que des données sont manquantes. Le manifeste d'achèvement enregistre ce qui a été traité. `FailureCode` est `RequestCancelled`.
+ `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 | 
| --- | --- | --- | 
| `Timeout` | L'opération a dépassé le temps de traitement maximal | Soumettez à nouveau le reste du manifeste d'achèvement | 
| `ValidationException` | 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 `processedRanges` | 
| `InputObjectTooLarge` | Un objet d'entrée dépasse 5 Go | Divisez l'objet | 
| `S3ObjectsCountLimitExceeded` | Plus de 50 000 objets d'entrée | Réduire le nombre d'objets ou demander une augmentation du quota | 
| `SizeLimitExceeded` | 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 | 
| `ObjectModifiedInS3DuringImport` | 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 | 
| `KmsAccessDeniedException`, `KmsDisabledException`, `KmsNotFoundException`, `KmsInvalidKeyUsageException`, `KmsInvalidStateException` | 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 | 
| `S3AccessDenied` | 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 `S3BucketOwner` ne correspond pas au propriétaire du bucket. | Vérifiez les autorisations Amazon S3 de l'appelant, la politique en matière de compartiment et `S3BucketOwner`. | 
| `ResourceInUseException` | Une autre opération sur la même table a déjà commencé | Attendez la fin de cette opération, puis recommencez | 
| `DynamoDBResourceNotFoundException` | La table n'a pas été trouvée ou n'était pas accessible | Vérifiez le nom et l'état de la table | 
| `DynamoDBAccessDeniedException` | L'appelant n'est plus autorisé à écrire dans la table | Restaurer `dynamodb:BulkPutItems` sur la table, puis soumettez à nouveau le reste | 
| `DynamoDBItemCollectionSizeLimitExceededException` | 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)
<a name="BulkPutItems.Requesting.Describe.CLI"></a>

```
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)
<a name="BulkPutItems.Requesting.Describe.Python"></a>

```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
<a name="BulkPutItems.Requesting.List"></a>

Appel [ListBulkOperations](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_ListBulkOperations.html) 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)
<a name="BulkPutItems.Requesting.List.CLI"></a>

```
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)
<a name="BulkPutItems.Requesting.List.Python"></a>

```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
<a name="BulkPutItems.Requesting.Cancel"></a>

Appel [CancelBulkOperation](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_CancelBulkOperation.html) pour arrêter une opération en cours. L'opération passe à `CANCELLING` puis à `CANCELLED`.

**Important**  
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)
<a name="BulkPutItems.Requesting.Cancel.CLI"></a>

```
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)
<a name="BulkPutItems.Requesting.Cancel.Python"></a>

```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
<a name="BulkPutItems.Requesting.Limits"></a>

Pour les quotas applicables aux opérations de vente en gros, voir [Articles en vrac](ServiceQuotas.md#limits-bulk-put-items).

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.