# UpdateItem **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 Edita los atributos de un elemento existente. Puede realizar una actualización condicional, es decir, insertar un nuevo par nombre-valor de atributo si no existe, o bien sustituir un par de nombre-valor si tiene determinados valores de atributo esperados. **nota** Los atributos de clave principal no se pueden actualizar mediante UpdateItem. En lugar de ello, debe eliminar el elemento y utilizar PutItem para crear otro con los nuevos atributos. La operación UpdateItem incluye un parámetro `Action`, que define cómo realizar la actualización. Puede poner, eliminar o agregar valores de atributos. 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`. Si un elemento tiene la clave principal especificada: + **PUT:** agrega el atributo especificado. Si el atributo existe, se sustituye por el nuevo valor. + **DELETE:** si no se especifica ningún valor, esta acción elimina el atributo y su valor. Si se especifica un conjunto de valores, entonces los valores del conjunto especificado se eliminan del conjunto anterior. Por lo tanto, si el valor del atributo contiene [a,b,c] y la acción de eliminación contiene [a,c], el valor del atributo final es [b]. El tipo del valor especificado debe coincidir con el tipo de valor existente. No es válido especificar un conjunto vacío. + **ADD:** la acción de añadir se utiliza sólo para números o si el atributo de destino es un conjunto (incluidos los conjuntos de cadena). ADD no funciona si el atributo de destino es un valor de cadena única o un valor escalar de tipo Binary (binario). El valor especificado se suma a un valor numérico (se suma o se resta al valor numérico existente) o se agrega como valor adicional a un conjunto de cadenas. Si se especifica un conjunto de valores, los valores se agregan al conjunto existente. Por ejemplo, si el conjunto original es [1,2] y el valor suministrado es [3], después de la operación de añadir el conjunto será [1,2,3] y no [4,5]. Se produce un error si se especifica una acción Add para un atributo de tipo Set y el tipo de atributo especificado no coincide con el tipo de conjunto existente. Si utiliza ADD para un atributo que no existe, el atributo y sus valores se agregan al elemento. Si no hay ningún elemento que coincida con la clave principal especificada: + **PUT:** crea un elemento nuevo con la clave principal especificada. A continuación, agrega el atributo especificado. + **DELETE**: no sucede nada. + **ADD:** crea un elemento con la clave principal y el número (o el conjunto de números) suministrados para el valor del atributo. No es válido para los tipos de cadena o binario. **nota** Si utiliza `ADD` para sumar o restar de un valor numérico de un elemento que no existía antes de la actualización, DynamoDB utilizará `0` como valor inicial. Además, si actualiza un elemento mediante `ADD` para sumar o restar de un valor numérico de un atributo que no existía antes de la actualización (pero el elemento sí existía), DynamoDB utilizará `0` como valor inicial. Por ejemplo, si utiliza `ADD` para sumar `+3` a un atributo que no existía antes de la actualización. DynamoDB utilizará `0` para el valor inicial y el valor posterior a la actualización será `3`. Para obtener más información sobre cómo usar esta operación, consulte [Uso de elementos y atributos en DynamoDB](WorkingWithItems.md). ## Solicitudes ### Sintaxis ``` // 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.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" } ``` **** | Nombre | Descripción | Obligatorio | | --- | --- | --- | | TableName | Nombre de la tabla que contiene el elemento que se va a actualizar. Tipo: cadena | Sí | | Key | Clave principal que define el elemento. Para obtener más información sobre claves principales, consulte [Clave principal](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey).Tipo: Map, mapa de `HashKeyElement` a su valor y `RangeKeyElement` a su valor. | Sí | | AttributeUpdates | Mapa del nombre de atributo al nuevo valor y acción de la actualización. Los nombres de los atributos especifican los atributos que hay que modificar y no pueden contener atributos de clave principal.Tipo: Map, mapa de nombre de atributo, valor y acción de la actualización del atributo. | | | AttributeUpdates:Action | Especifica cómo realizar la actualización. Valores posibles: `PUT` (predeterminado), `ADD` o `DELETE`. La semántica se explica en la descripción de UpdateItem.Tipo: cadenaValor predeterminado: `PUT` | No | | Expected | Designa un atributo para una actualizació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 atributos. | 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 actualiza el elemento si todavía no existe el atributo "Color" para ese elemento:
"Expected" :
	{"Color":{"Exists":false}}
En la siguiente notación JSON se comprueba si el atributo denominado "Color" tiene el valor "Yellow" antes de actualizar el elemento: 
"Expected" : 
	{"Color":{"Exists":true},{"Value":{"S":"Yellow"}}}
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:
"Expected" : 
	{"Color":{"Value":{"S":"Yellow"}}}
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 `UpdateItem`. Los valores posibles de los parámetros son `NONE` (predeterminado) o `ALL_OLD`, `UPDATED_OLD`, `ALL_NEW` o `UPDATED_NEW`. Si se especifica `ALL_OLD` y `UpdateItem` 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. Si se especifica `ALL_NEW`, entonces se devuelven todos los atributos de la nueva versión del elemento. Si se especifica `UPDATED_NEW`, entonces se devuelven solamente las nuevas versiones de los atributos actualizados.Tipo: cadena | No | ## Respuestas ### Sintaxis 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: 140 {"Attributes":{ "AttributeName1":{"S":"AttributeValue1"}, "AttributeName2":{"S":"AttributeValue2"}, "AttributeName3":{"S":"AttributeValue3"}, "AttributeName5":{"B":"dmFsdWU="} }, "ConsumedCapacityUnits":1 } ``` **** | Nombre | Descripción | | --- | --- | | Attributes | Mapa de pares de nombre-valor del atributo, pero solo si el parámetro `ReturnValues` se ha especificado como algo distinto de `NONE` 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 **** | Error | Descripción | | --- | --- | | ConditionalCheckFailedException | Error en la verificación condicional. El valor del atributo ("\$1 name \$1") es ("\$1 value \$1") pero se esperaba ("\$1 expValue \$1"). | | ResourceNotFoundExceptions | No se encontró el elemento o atributo especificado. | ## Ejemplos Para obtener ejemplos sobre cómo usar el SDK de AWS, consulte [Uso de elementos y atributos en DynamoDB](WorkingWithItems.md). ### Solicitud de ejemplo ``` // 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.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" } ``` ### Respuesta de ejemplo ``` 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 } ``` ## Acciones relacionadas + [PutItem](API_PutItem_v20111205.md) + [DeleteItem](API_DeleteItem_v20111205.md)