PutItem - Amazon DynamoDB
DescripciónSolicitudesRespuestasErrores especialesEjemplosAcciones relacionadas

PutItem

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

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.

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

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:

"Expected" :
	{"Color":{"Exists":false}}

En la siguiente notación JSON se comprueba si el atributo denominado "Color" tiene el valor "Yellow" antes de sustituir 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 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

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

Tipo: Number

Errores especiales

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

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

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
}