Description Requêtes Réponses Erreurs spéciales Exemples Actions connexes

UpdateItem

Important

This section refers to API version 2011-12-05, which is deprecated and should not be used for new applications.

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

Description

Modifie les attributs d'un élément existant. Vous pouvez effectuer une mise à jour conditionnelle (insérer une nouvelle paire nom-valeur d'attribut si elle n'existe pas, ou remplacer une paire nom-valeur existante si elle a certaines valeurs d'attribut attendues).

Note

Vous ne pouvez pas mettre à jour les attributs de la clé primaire à l'aide de UpdateItem. Supprimez plutôt l'élément et utilisez-le PutItem pour créer un nouvel article avec de nouveaux attributs.

L' UpdateItem opération inclut un Action paramètre qui définit le mode d'exécution de la mise à jour. Vous pouvez insérer, supprimer ou ajouter des valeurs d'attribut.

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 erreur ValidationException.

Si un élément existant possède la clé primaire spécifiée :

PUT – Ajoute l'attribut spécifié. Si l'attribut existe, il est remplacé par la nouvelle valeur.
DELETE – Si aucune valeur n'est spécifiée, l'attribut et sa valeur sont supprimés. Si un ensemble de valeurs est spécifié, les valeurs dans l'ensemble spécifié sont supprimées de l'ancien ensemble. Ainsi, si la valeur d'attribut contient [a,b,c] et si l'action de suppression contient [a,c], la valeur d'attribut finale est [b]. Le type de la valeur spécifiée doit correspondre au type de valeur existant. La spécification d'un ensemble vide n'est pas valide.
ADD – N'utilisez l'action d'ajout que pour des nombres ou si l'attribut cible est un ensemble (y compris un ensemble de chaîne). L'action ADD ne fonctionne pas si l'attribut cible est une valeur de chaîne unique ou une valeur binaire scalaire. La valeur spécifiée est ajoutée à une valeur numérique (incrémentant ou décrémentant la valeur numérique existante), ou ajoutée en tant que valeur supplémentaire dans un ensemble de chaîne. Si un ensemble de valeurs est spécifié, les valeurs sont ajoutées à l'ensemble existant. Par exemple, si l'ensemble d'origine est [1,2] et si la valeur fournie est [3], après l'opération d'ajout, l'ensemble est [1,2,3], non [4,5]. Une erreur se produit si une action d'ajout est spécifiée pour un attribut d'ensemble et si le type d'attribut spécifié ne correspond pas au type d'ensemble existant.

Si vous utilisez l'action ADD pour un attribut qui n'existe pas, l'attribut et ses valeurs sont ajoutés à l'élément.

Si aucun élément ne correspond à la clé primaire spécifiée :

PUT – Crée un élément avec la clé primaire spécifiée. Ajoute ensuite l'attribut spécifié.
DELETE – Il ne se passe rien.
ADD – Crée un élément avec la clé primaire et le numéro (ou un ensemble de numéros) fournis pour la valeur d'attribut. Non valide pour un type chaîne ou binaire.

Note

Si vous utilisez l'action ADD pour incrémenter ou décrémenter une valeur numérique pour un élément qui n'existe pas avant la mise à jour, DynamoDB utilise 0 comme valeur initiale. Par ailleurs, si vous mettez à jour un élément en utilisant l'action ADD pour incrémenter ou décrémenter une valeur numérique pour un attribut qui n'existe pas avant la mise à jour (tandis que l'élément existe), DynamoDB utilise 0 comme valeur initiale. Par exemple, vous utilisez l'action ADD pour ajouter +3 à un attribut qui n'existait pas avant la mise à jour. DynamoDB utilise 0 comme valeur initiale, et la valeur après la mise à jour est 3.

Pour plus d'informations sur l'utilisation de cette opération, consultez Utilisation d'éléments et d'attributs dans DynamoDB.

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.UpdateItem
content-type: application/x-amz-json-1.0

{"TableName":"Table1",
    "Key":
        {"HashKeyElement":{"S":"AttributeValue1"},
        "RangeKeyElement":{"N":"AttributeValue2"}},
    "AttributeUpdates":{"AttributeName3":{"Value":{"S":"AttributeValue3_New"},"Action":"PUT"}},
    "Expected":{"AttributeName3":{"Value":{"S":"AttributeValue3_Current"}}},
    "ReturnValues":"ReturnValuesConstant"
}

Name (Nom)	Description	Obligatoire
`TableName`	Nom de la table contenant l'élément à mettre à jour. Type : String	Oui
`Key`	Clé primaire définissant l'élément. Pour plus d'informations sur les clés primaires, consultez Clé primaire. Type : mappage de `HashKeyElement` à sa valeur, et de `RangeKeyElement` à sa valeur.	Oui
`AttributeUpdates`	Mappage de nom d'attribut à la nouvelle valeur, et d'une action pour la mise à jour. Les noms d'attribut spécifient les attributs à modifier, et ne peuvent pas contenir d'attributs de clé primaire. Type : mappage de nom d'attribut, de valeur et d'une action pour la mise à jour.
`AttributeUpdates`:`Action`	Spécifie comment effectuer la mise à jour. Valeurs possibles : `PUT` (par défaut), `ADD` ou `DELETE`. La sémantique est expliquée dans la UpdateItem description. Type : String Par défaut : `PUT`	Non
`Expected`	Désigne un attribut pour une mise à jour conditionnelle. Le paramètre `Expected` vous permet de fournir un nom d'attribut et de spécifier si DynamoDB doit ou non vérifier si la valeur d'attribut existe, ou existe et a une valeur particulière, avant de modifier l'attribut. Type : mappage de noms d'attribut.	Non
`Expected:AttributeName`	Nom de l'attribut pour l'insertion conditionnelle. Type : String	Non
`Expected:AttributeName: ExpectedAttributeValue`	Utilisez ce paramètre pour spécifier si une valeur existe déjà pour la paire nom-valeur de l'attribut. La notation JSON suivante met à jour l'élément si l'attribut « Color » (Couleur) n'existe pas pour cet élément : `"Expected" : {"Color":{"Exists":false}}` La notation JSON suivante vérifie si l'attribut « Color » (Couleur) a une valeur existante de « Yellow » (Jaune) avant de mettre à jour l'élément : `"Expected" : {"Color":{"Exists":true},{"Value":{"S":"Yellow"}}}` Par défaut, si vous utilisez le paramètre `Expected` et fournissez une `Value`, DynamoDB suppose que l'attribut existe et a une valeur actuelle à remplacer. Vous n'avez donc pas à spécifier `{"Exists":true}`, car c'est implicite. Vous pouvez raccourcir la demande pour : `"Expected" : {"Color":{"Value":{"S":"Yellow"}}}` Note Si vous spécifiez `{"Exists":true}` sans valeur d'attribut à vérifier, DynamoDB renvoie une erreur.	Non
`ReturnValues`	Utilisez ce paramètre si vous souhaitez obtenir les paires nom-valeur d'attribut avant leur mise à jour avec la demande `UpdateItem`. Les valeurs de paramètre possibles sont `NONE` (par défaut) ou `ALL_OLD`, `UPDATED_OLD`, `ALL_NEW` ou `UPDATED_NEW`. Si `ALL_OLD` est spécifié et si l'opération `UpdateItem` a remplacé une paire nom-valeur d'attribut, le contenu de l'ancien élément est renvoyé. Si ce paramètre n'est pas fourni ou est `NONE`, rien n'est retourné. Si `ALL_NEW` est spécifié, tous les attributs de la nouvelle version de l'élément sont renvoyés. Si `UPDATED_NEW` est spécifié, les nouvelles versions uniquement des attributs mis à jour sont renvoyées. Type : String	Non

Réponses

Syntaxe

L'exemple de syntaxe suivant part du principe que la demande a spécifié un paramètre ReturnValues dont la valeur est ALL_OLD. Sinon, la réponse ne contient que l'élément ConsumedCapacityUnits.


HTTP/1.1 200 
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375 
content-type: application/x-amz-json-1.0
content-length: 140

{"Attributes":{
	"AttributeName1":{"S":"AttributeValue1"},
	"AttributeName2":{"S":"AttributeValue2"},
	"AttributeName3":{"S":"AttributeValue3"},
	"AttributeName5":{"B":"dmFsdWU="}
	},
"ConsumedCapacityUnits":1
}

Nom Description

Nom	Description
`Attributes`	Mappage de paires nom-valeur d'attribut, mais uniquement si le paramètre `ReturnValues` est spécifié comme autre chose que `NONE` dans la demande. Type : mappage de paires nom-valeur d'attribut.
`ConsumedCapacityUnits`	Nombre d'unités de capacité d'écriture consommées par l'opération. Cette valeur indique le nombre appliqué à votre débit approvisionné. Pour plus d'informations, voir Mode de capacité provisionnée DynamoDB. Type : nombre

Attributes

Mappage de paires nom-valeur d'attribut, mais uniquement si le paramètre ReturnValues est spécifié comme autre chose que NONE dans la demande.

Type : mappage de paires nom-valeur d'attribut.

ConsumedCapacityUnits

Nombre d'unités de capacité d'écriture consommées par l'opération. Cette valeur indique le nombre appliqué à votre débit approvisionné. Pour plus d'informations, voir Mode de capacité provisionnée DynamoDB.

Type : nombre

Erreurs spéciales

Erreur	Description
`ConditionalCheckFailedException`	Le contrôle conditionnel a échoué. La valeur (« + name + ») de l'attribut est (« + value + ») mais la valeur attendue était (« + ExpValue + »)
`ResourceNotFoundExceptions`	L'élément ou l'attribut spécifiés n'ont pas été trouvés.

Exemples

Pour des exemples d'utilisation du AWS SDK, consultezUtilisation d'éléments et d'attributs dans DynamoDB.

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.UpdateItem
content-type: application/x-amz-json-1.0 

{"TableName":"comp5",
    "Key":
        {"HashKeyElement":{"S":"Julie"},"RangeKeyElement":{"N":"1307654350"}},
    "AttributeUpdates":
        {"status":{"Value":{"S":"online"},
        "Action":"PUT"}},
    "Expected":{"status":{"Value":{"S":"offline"}}},
    "ReturnValues":"ALL_NEW"
}

Exemple de réponse


HTTP/1.1 200 OK
x-amzn-RequestId: 5IMHO7F01Q9P7Q6QMKMMI3R3QRVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 121
Date: Fri, 26 Aug 2011 21:05:00 GMT

{"Attributes":
    {"friends":{"SS":["Lynda, Aaron"]},
    "status":{"S":"online"},
    "time":{"N":"1307654350"},
    "user":{"S":"Julie"}},
"ConsumedCapacityUnits":1
}

Actions connexes

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Analyser

UpdateTable