UpdateItem - Amazon DynamoDB
DescripciónSolicitudesRespuestasErrores especialesEjemplosAcciones relacionadas

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.

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.

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.

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: cadena

Valor 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"}}}
nota

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.

Tipo: Number

Errores especiales

Error Descripción
ConditionalCheckFailedException Error en la verificación condicional. El valor del atributo ("+ name +") es ("+ value +") pero se esperaba ("+ expValue +").
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.

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
}