# PutItem
<a name="API_PutItem_v20111205"></a>

**importante**  
***Esta sección se refiere a la versión 2011-12-05 del API, que está obsoleta y no debe utilizarse para nuevas aplicaciones.***  
 **Para consultar la documentación sobre la API de bajo nivel actual, consulte la [Referencia de la API de Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/).**

## Descripción
<a name="API_PutItem_Description"></a>

Crea un elemento nuevo o sustituye uno antiguo por uno nuevo (incluyendo todos los atributos). Si ya existe un elemento con la misma clave principal en la tabla especificada, el nuevo elemento sustituye por completo al existente. Puede realizar una colocación condicional (insertar un nuevo elemento solamente si no existe otro con la clave principal especificada) o bien sustituir un elemento existente si sus atributos tienen determinados valores. 

Los valores de los atributos no pueden ser null; los atributos de tipo cadena y binario deben tener una longitud superior a cero; y los atributos de tipo conjunto no pueden estar vacíos. Las solicitudes con valores vacíos se rechazan con la excepción `ValidationException`.

**nota**  
Para garantizar que un nuevo elemento no sustituya un elemento existente, utilice una operación de colocación condicional con `Exists` establecido en `false` para el o los atributos de clave principal.

Para obtener más información acerca del uso de `PutItem`, consulte [Uso de elementos y atributos en DynamoDB](WorkingWithItems.md).

## Solicitudes
<a name="API_PutItem_RequestParameters"></a>

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

```
// This header is abbreviated.
// For a sample of a complete header, see API de bajo nivel 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"}
```


****  

|  Nombre  |  Descripción  |  Obligatorio | 
| --- | --- | --- | 
|  TableName  |  Nombre de la tabla que contendrá el elemento. Tipo: cadena  |  Sí  | 
|  Item  | Mapa de los atributos del elemento, que debe incluir los valores de clave principal que definen el elemento. Se pueden indicar otros pares de nombre-valor de los atributos del elemento. Para obtener más información sobre claves principales, consulte [Clave principal](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey).Tipo: Map, mapa de los nombres de atributos a los valores de atributos. | Sí | 
| Expected  | Designa un atributo para una colocación condicional. El parámetro `Expected` le permite proporcionar un nombre de atributo e indicar si DynamoDB debe verificar si el valor del atributo ya existe; o bien si el valor del atributo existe y tiene un valor determinado antes de cambiarlo.Tipo: Map, mapa de nombres de un atributo a valores de un atributo e indicación de si existe. | No | 
| Expected:AttributeName  | Nombre del atributo para la operación Put condicional.Tipo: cadena | No | 
| Expected:AttributeName: ExpectedAttributeValue | Use este parámetro para especificar si ya existe un valor del par de nombre-valor del atributo. En la siguiente notación JSON, se sustituye el elemento si todavía no existe el atributo "Color" para ese elemento:<pre>"Expected" :<br />	{"Color":{"Exists":false}}</pre>En la siguiente notación JSON se comprueba si el atributo denominado "Color" tiene el valor "Yellow" antes de sustituir el elemento: <pre>"Expected" : <br />	{"Color":{"Exists":true,{"Value":{"S":"Yellow"}}}</pre>De forma predeterminada, si utiliza el parámetro `Expected` y le proporciona un `Value`, DynamoDB da por hecho que el atributo existe y que posee un valor que hay que sustituir. Por lo tanto, no es preciso especificar `{"Exists":true}`, porque se considera implícito. Puede reducir la solicitud a:<pre>"Expected" : <br />	{"Color":{"Value":{"S":"Yellow"}}}</pre> Si especifica `{"Exists":true}` sin un valor de atributo que verificar, DynamoDB devuelve un error.  | No | 
| ReturnValues  | Use este parámetro si desea obtener los pares de nombre-valor de los atributos antes de actualizarlos mediante la solicitud `PutItem`. Los valores posibles de los parámetros son `NONE` (predeterminado) o `ALL_OLD`. Si se especifica `ALL_OLD` y `PutItem` ha sobrescrito un par de nombre-valor del atributo, se devuelve el contenido del elemento anterior. Si este parámetro no se proporciona o si su valor es `NONE`, no se devuelve nada.Tipo: cadena | No | 

## Respuestas
<a name="API_PutItem_CommonResponseElements"></a>

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

En el ejemplo de sintaxis siguiente se supone que la solicitud ha especificado un parámetro `ReturnValues` de `ALL_OLD`; en caso contrario, la respuesta solo contiene la entrada `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
}
```


****  

|  Nombre  |  Descripción  | 
| --- | --- | 
|  Attributes  | Valores de los atributos antes de la operación de colocación, pero solamente si el parámetro `ReturnValues` se especifica como `ALL_OLD` en la solicitud.Tipo: Map, mapa de pares de nombre-valor del atributo. | 
| ConsumedCapacityUnits | Cantidad de unidades de capacidad de escritura consumidas por la operación. Este valor muestra el número aplicado al rendimiento aprovisionado. Para obtener más información, consulte [Modo de capacidad aprovisionada de DynamoDB](provisioned-capacity-mode.md). Tipo: Number | 

## Errores especiales
<a name="API_PutItem_SpecialErrors"></a>


****  

|  Error  |  Descripción  | 
| --- | --- | 
|  ConditionalCheckFailedException  | Error en la verificación condicional. No se encontró un valor de atributo esperado.  | 
| ResourceNotFoundException  | No se encontró el elemento o atributo especificado. | 

## Ejemplos
<a name="API_PutItem_Examples"></a>

Para obtener ejemplos sobre cómo usar el SDK de AWS, consulte [Uso de elementos y atributos en DynamoDB](WorkingWithItems.md).

### Solicitud de ejemplo
<a name="API_PutItem_Examples_Request"></a>

```
// This header is abbreviated. For a sample of a complete header, see API de bajo nivel 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"
}
```

### Respuesta de ejemplo
<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
}
```

## Acciones relacionadas
<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)