BatchWriteItem - 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.

BatchWriteItem

Important

Cette section fait référence à l'API version 2011-12-05 qui est obsolète et ne doit pas être utilisée pour de nouvelles applications.

Pour une documentation sur l'API de bas niveau actuelle, consultez la Référence d'API Amazon DynamoDB.

Description

Cette opération vous permet d'insérer et de supprimer plusieurs éléments dans plusieurs tables en un seul appel.

Pour charger un élément, vous pouvez utiliser PutItem. Et pour supprimer un élément, vous pouvez utiliser DeleteItem. Toutefois, lorsque vous souhaitez charger ou supprimer de grandes quantités de données, par exemple en chargeant des données d'Amazon EMR (Amazon EMR) ou en migrant des données d'une autre base de données vers DynamoDB, BatchWriteItem offre une alternative efficace.

Si vous utilisez des langages tels que Java, vous pouvez utiliser des unités d'exécution pour charger des éléments en parallèle. Cela rend votre application plus complexe en lien avec la gestion des unités d'exécution. D'autres langages ne prennent pas en charge les unités d'exécution. Par exemple, si vous utilisez PHP, vous devez charger ou supprimer les éléments un par un. Dans les deux cas, BatchWriteItem fournit une alternative où les actions d'insertion et de suppression d'éléments spécifiées sont traitées en parallèle. Vous bénéficiez ainsi de la puissance de l'approche de groupe d'unités d'exécution sans avoir à introduire de la complexité dans votre application.

Notez que chaque action d'insertion ou de suppression spécifiée dans une opération BatchWriteItem a le même coût en termes d'unités de capacité consommées. Cependant, BatchWriteItem effectuant les actions spécifiées en parallèle, vous bénéficiez d'une latence plus faible. Les actions de suppression d'éléments inexistants consomment 1 unité de capacité d'écriture. Pour plus d'informations sur les unités de capacité consommées, consultez Utilisation des tables et des données dans DynamoDB.

Lorsque vous utilisez BatchWriteItem, notez les limitations suivantes :

  • Nombre maximum d'actions dans une seule demande – Vous pouvez spécifier jusqu'à 25 actions d'insertion ou de suppression. Toutefois, la taille totale de la demande ne peut pas dépasser 1 Mo (charge utile HTTP).

  • Vous pouvez utiliser l'opération BatchWriteItem uniquement pour insérer et supprimer des éléments. Vous ne pouvez pas l'utiliser pour mettre à jour des éléments existants.

  • Opération non atomique – Les actions individuelles spécifiées dans une opération BatchWriteItem sont atomiques. Cependant, une opération BatchWriteItem en tant que tout, est une opération effectuée sur la base du meilleur effort, non une opération atomique. Autrement dit, dans une demande BatchWriteItem, certaines opérations peuvent réussir et d'autres échouer. Les opérations ayant échoué sont renvoyées dans un champ UnprocessedItems dans la réponse. Certains de ces échecs peuvent résulter d'un dépassement du débit approvisionné configuré pour la table, ou d'un échec temporaire tel qu'une erreur réseau. Vous pouvez examiner et éventuellement renvoyer les demandes. En règle générale, vous appelez l'opération BatchWriteItem dans une boucle et, dans chaque itération, vérifiez les éléments non traités, puis soumettez une nouvelle demande BatchWriteItem avec ceux-ci.

  • Ne renvoie aucun élément – L'opération BatchWriteItem est conçue pour charger efficacement de grandes quantités de données. Il ne présente pas le même niveau de sophistication que les opérations PutItem et DeleteItem. Par exemple, l'opération DeleteItem prend en charge le champ ReturnValues dans le corps de votre demande pour demander l'élément supprimé dans la réponse. L'opération BatchWriteItem ne renvoie aucun élément dans la réponse.

  • Contrairement aux opérations PutItem et DeleteItem, l'opération BatchWriteItem ne vous permet pas de spécifier des conditions sur des demandes d'écriture individuelles dans l'opération.

  • Les valeurs d'attribut ne peuvent pas être nulles, les attributs de type chaîne et binaire doivent avoir une longueur supérieure à zéro, et les attributs de type ensemble ne peuvent pas être vides. Les demandes comprenant des valeurs vides sont rejetées avec une valeur ValidationException.

DynamoDB rejette toute l'opération d'écriture par lot si l'une des conditions suivantes est vraie :

  • Si une ou plusieurs tables spécifiées dans la demande BatchWriteItem n'existent pas.

  • Si les attributs de clé primaire spécifiés sur un élément dans la demande ne correspondent pas au schéma de clé primaire de la table correspondante.

  • Si vous essayez d'effectuer plusieurs opérations sur le même élément dans la même demande BatchWriteItem. Par exemple, vous ne pouvez pas insérer et supprimer le même élément dans la même demande BatchWriteItem.

  • Si la taille totale de la demande dépasse la limite de 1 Mo (charge utile HTTP).

  • Si un élément individuel dans un lot dépasse la limite de taille d'élément de 64 Ko.

Requêtes

Syntaxe

// This header is abbreviated. For a sample of a complete header, see API de bas niveau de DynamoDB. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.BatchGetItem content-type: application/x-amz-json-1.0 { "RequestItems" : RequestItems } RequestItems { "TableName1" : [ Request, Request, ... ], "TableName2" : [ Request, Request, ... ], ... } Request ::= PutRequest | DeleteRequest PutRequest ::= { "PutRequest" : { "Item" : { "Attribute-Name1" : Attribute-Value, "Attribute-Name2" : Attribute-Value, ... } } } DeleteRequest ::= { "DeleteRequest" : { "Key" : PrimaryKey-Value } } PrimaryKey-Value ::= HashTypePK | HashAndRangeTypePK HashTypePK ::= { "HashKeyElement" : Attribute-Value } HashAndRangeTypePK { "HashKeyElement" : Attribute-Value, "RangeKeyElement" : Attribute-Value, } Attribute-Value ::= String | Numeric| Binary | StringSet | NumericSet | BinarySet Numeric ::= { "N": "Number" } String ::= { "S": "String" } Binary ::= { "B": "Base64 encoded binary data" } StringSet ::= { "SS": [ "String1", "String2", ... ] } NumberSet ::= { "NS": [ "Number1", "Number2", ... ] } BinarySet ::= { "BS": [ "Binary1", "Binary2", ... ] }

Dans le corps de la demande, l'objet JSON RequestItems décrit les opérations que vous souhaitez effectuer. Les opérations sont regroupées par tables. Vous pouvez utiliser une opération BatchWriteItem pour mettre à jour ou supprimer plusieurs éléments dans plusieurs tables. Pour chaque demande d'écriture, vous devez identifier le type de demande (PutItem, DeleteItem), suivi d'informations détaillées sur l'opération.

  • Pour une opération PutRequest, vous fournissez l'élément, c'est-à-dire une liste d'attributs avec leurs valeurs.

  • Pour une opération DeleteRequest, vous indiquez le nom et la valeur de la clé primaire.

Réponses

Syntaxe

Voici la syntaxe du corps JSON renvoyé dans la réponse.

{ "Responses" : ConsumedCapacityUnitsByTable "UnprocessedItems" : RequestItems } ConsumedCapacityUnitsByTable { "TableName1" : { "ConsumedCapacityUnits", : NumericValue }, "TableName2" : { "ConsumedCapacityUnits", : NumericValue }, ... } RequestItems This syntax is identical to the one described in the JSON syntax in the request.

Erreurs spéciales

Aucune erreur spécifique à cette opération.

Exemples

L'exemple suivant illustre une requête HTTP POST et la réponse d'une opération BatchWriteItem. La requête spécifie les opérations suivantes sur les tables Reply et Thread :

  • Insérer et supprimer un élément dans la table Reply

  • Insérer un élément dans la table Thread

Pour des exemples d'utilisation du kit SDK AWS, consultez Utilisation des éléments et des attributs.

Exemple de demande

// This header is abbreviated. For a sample of a complete header, see API de bas niveau de DynamoDB. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.BatchGetItem content-type: application/x-amz-json-1.0 { "RequestItems":{ "Reply":[ { "PutRequest":{ "Item":{ "ReplyDateTime":{ "S":"2012-04-03T11:04:47.034Z" }, "Id":{ "S":"DynamoDB#DynamoDB Thread 5" } } } }, { "DeleteRequest":{ "Key":{ "HashKeyElement":{ "S":"DynamoDB#DynamoDB Thread 4" }, "RangeKeyElement":{ "S":"oops - accidental row" } } } } ], "Thread":[ { "PutRequest":{ "Item":{ "ForumName":{ "S":"DynamoDB" }, "Subject":{ "S":"DynamoDB Thread 5" } } } } ] } }

Exemple de réponse

L'exemple de réponse suivant montre une opération d'insertion sur les tables Thread et Reply réussie, et une opération de suppression sur la table Reply ayant échoué (pour une raison telle qu'une limitation résultant du dépassement du débit approvisionné sur la table). Dans la réponse JSON, notez ce qui suit :

  • L'objet Responses montre qu'une unité de capacité a été consommée sur les deux tables Thread et Reply suite à l'opération d'insertion réussie sur chacune d'elles.

  • L'objet UnprocessedItems montre l'opération de suppression ayant échoué sur la table Reply. Vous pouvez ensuite émettre un nouvel appel BatchWriteItem pour traiter ces demandes non traitées.

HTTP/1.1 200 OK x-amzn-RequestId: G8M9ANLOE5QA26AEUHJKJE0ASBVV4KQNSO5AEMVJF66Q9ASUAAJG Content-Type: application/x-amz-json-1.0 Content-Length: 536 Date: Thu, 05 Apr 2012 18:22:09 GMT { "Responses":{ "Thread":{ "ConsumedCapacityUnits":1.0 }, "Reply":{ "ConsumedCapacityUnits":1.0 } }, "UnprocessedItems":{ "Reply":[ { "DeleteRequest":{ "Key":{ "HashKeyElement":{ "S":"DynamoDB#DynamoDB Thread 4" }, "RangeKeyElement":{ "S":"oops - accidental row" } } } } ] } }