PutItem - Amazon DynamoDB
DescriptionRequêtesRéponsesErreurs spécialesExemplesActions connexes

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.

PutItem

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

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 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.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 : String

 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 : 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 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 : 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: 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, voir Mode de capacité provisionné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 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.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
}