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
<a name="API_PutItem_v20111205"></a>

**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](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/).**

## Description
<a name="API_PutItem_Description"></a>

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](WorkingWithItems.md).

## Requêtes
<a name="API_PutItem_RequestParameters"></a>

### Syntaxe
<a name="API_PutItem_RequestParameters.syntax"></a>

```
// 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](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey).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 :<pre>"Expected" :<br />	{"Color":{"Exists":false}}</pre>La notation JSON suivante vérifie si l'attribut « Color » (Couleur) a une valeur existante de « Yellow » (Jaune) avant de remplacer l'élément : <pre>"Expected" : <br />	{"Color":{"Exists":true,{"Value":{"S":"Yellow"}}}</pre>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 :<pre>"Expected" : <br />	{"Color":{"Value":{"S":"Yellow"}}}</pre> 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
<a name="API_PutItem_CommonResponseElements"></a>

### Syntaxe
<a name="API_PutItem_CommonResponseElements.syntax"></a>

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 [Mode de capacité provisionnée DynamoDB](provisioned-capacity-mode.md). Type : nombre | 

## Erreurs spéciales
<a name="API_PutItem_SpecialErrors"></a>


****  

|  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
<a name="API_PutItem_Examples"></a>

Pour des exemples d'utilisation du kit SDK AWS, consultez [Utilisation d’éléments et d’attributs dans DynamoDB](WorkingWithItems.md).

### Exemple de demande
<a name="API_PutItem_Examples_Request"></a>

```
// 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
<a name="API_PutItem_Examples_Response"></a>

```
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
<a name="API_PutItem_Related_Actions"></a>
+  [UpdateItem](API_UpdateItem_v20111205.md) 
+  [DeleteItem](API_DeleteItem_v20111205.md) 
+  [GetItem](API_GetItem_v20111205.md) 
+  [BatchGetItem](API_BatchGetItem_v20111205.md)