PutItem

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

Crée un élément ou remplace un ancien élément par un nouveau (en incluant tous les attributs). S'il existe déjà un élément dans la table spécifiée avec la même clé primaire, le nouvel élément remplace complètement l'élément existant. Vous pouvez effectuer une insertion conditionnelle (insérer un nouvel élément s'il n'existe pas de clé primaire spécifiée), ou remplacer un élément existant s'il possède certaines 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.

Note

Pour vous assurer qu'un nouvel élément ne remplace pas un élément existant, utilisez une opération d'insertion conditionnelle avec une valeur Exists définie sur false pour l'attribut de clé primaire ou les attributs.

Pour plus d'informations sur l'utilisation de PutItem, consultez Utilisation des éléments et des attributs.

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

{"TableName":"Table1",
    "Item":{
        "AttributeName1":{"S":"AttributeValue1"},
        "AttributeName2":{"N":"AttributeValue2"},
        "AttributeName5":{"B":"dmFsdWU="}
    },
    "Expected":{"AttributeName3":{"Value": {"S":"AttributeValue"}, "Exists":Boolean}},
    "ReturnValues":"ReturnValuesConstant"}

Name (Nom)	Description	Obligatoire
TableName	Nom de la table devant contenir l'élément. Type : chaîne	Oui
Item	Mappage des attributs pour l'élément, qui doit inclure les valeurs de clé primaire qui définissent l'élément. D'autres paires nom-valeur d'attribut peuvent être fournies pour l'élément. Pour plus d'informations sur les clés primaires, consultez Clé primaire. Type : mappage de noms d'attribut à des valeurs d'attribut.	Oui
Expected	Désigne un attribut pour une insertion 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 d'un nom d'attribut à une valeur d'attribut et vérification de l'existence de l'attribut.	Non
Expected:AttributeName	Nom de l'attribut pour l'insertion conditionnelle. Type : chaîne	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 remplace 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 remplacer 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 PutItem. Les valeurs de paramètre possibles sont NONE (par défaut) ou ALL_OLD. Si ALL_OLD est spécifié et si l'opération PutItem 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é. Type : chaîne	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: 85

{"Attributes":
	{"AttributeName3":{"S":"AttributeValue3"},
	"AttributeName2":{"SS":"AttributeValue2"},
	"AttributeName1":{"SS":"AttributeValue1"},
	},
"ConsumedCapacityUnits":1
}

Nom	Description
Attributes	Valeurs d'attribut avant l'opération d'insertion, mais uniquement si le paramètre ReturnValues a la valeur ALL_OLD 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, consultez Gestion de paramètres sur des tables à capacité allouée DynamoDB. Type : nombre

Erreurs spéciales

Erreur	Description
ConditionalCheckFailedException	Le contrôle conditionnel a échoué. La valeur d'attribut attendue n'a pas été trouvée.
ResourceNotFoundException	L'élément ou l'attribut spécifiés n'ont pas été trouvés.

Exemples

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

{"TableName":"comp5",
	"Item":
		{"time":{"N":"300"},
		"feeling":{"S":"not surprised"},
		"user":{"S":"Riley"}
		},
	"Expected":
		{"feeling":{"Value":{"S":"surprised"},"Exists":true}}
	"ReturnValues":"ALL_OLD"
}

Exemple de réponse

HTTP/1.1 200 
x-amzn-RequestId: 8952fa74-71e9-11e0-a498-71d736f27375 
content-type: application/x-amz-json-1.0
content-length: 84

{"Attributes":
	{"feeling":{"S":"surprised"},
	"time":{"N":"300"},
	"user":{"S":"Riley"}},
"ConsumedCapacityUnits":1
}

Actions connexes

• UpdateItem

• DeleteItem

• GetItem

• BatchGetItem