PutItem

Importante

In questa sezione si fa riferimento alla versione API 2011-12-05, che è obsoleta e non deve essere utilizzata per le nuove applicazioni.

Per informazioni sull'API di basso livello corrente, consulta la Amazon DynamoDB API Reference.

Descrizione

Crea un nuovo elemento o sostituisce un vecchio elemento con un nuovo elemento (includendo tutti gli attributi). Se nella tabella specificata esiste già un elemento con la stessa chiave primaria, il nuovo elemento sostituisce completamente l'elemento esistente. È possibile eseguire un put condizionale (inserire un nuovo elemento se non ne esiste uno con la chiave primaria specificata) o sostituire un elemento esistente se dispone di determinati valori di attributo.

I valori degli attributi non possono essere nulli; gli attributi stringa e di tipo binario devono avere lunghezze maggiori di zero e gli attributi di tipo impostato non devono essere vuoti. Le richieste con valori vuoti verranno rifiutate con una eccezione ValidationException.

Nota

Per essere certi che un nuovo elemento non sostituisca un elemento esistente, utilizza un'operazione put condizionale con Exists impostato su falseper l'attributo o gli attributi della chiave primaria.

Per ulteriori informazioni sull'utilizzo di PutItem, consultare Utilizzo di elementi e attributi.

Richieste

Sintassi

// This header is abbreviated.
// For a sample of a complete header, see API DynamoDB di basso livello.
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"}

Nome	Descrizione	Obbligatorio
TableName	Il nome della tabella che deve contenere l'elemento da eliminare. Tipo: string	Sì
Item	Una mappa degli attributi per l'elemento e deve includere i valori della chiave primaria che definiscono l'elemento. È possibile fornire altre coppie nome-valore dell'attributo per l'elemento. Per ulteriori informazioni sulle chiavi primarie, vedere Chiave primaria. Tipo: mappa dei nomi degli attributi ai valori degli attributi.	Sì
Expected	Designa un attributo per un put condizionale. Il parametro Expected consente di fornire un nome di attributo e se DynamoDB deve controllare o meno se il valore dell'attributo esiste già o se esiste e ha un valore particolare prima di modificarlo. Tipo: mappa dei nomi di un attributo a un valore di attributo e se esiste.	No
Expected:AttributeName	Il nome dell'attributo per il put condizionale. Tipo: string	No
Expected:AttributeName: ExpectedAttributeValue	Utilizza questo parametro per specificare se esiste già un valore per la coppia nome-valore dell'attributo. La seguente notazione JSON sostituisce l'elemento se l'attributo "Colore" non esiste già per quell'elemento: "Expected" : {"Color":{"Exists":false}} La seguente notazione JSON controlla se l'attributo con nome "Colore" ha un valore esistente pari a "Giallo" prima di sostituire l'elemento: "Expected" : {"Color":{"Exists":true,{"Value":{"S":"Yellow"}}} Per impostazione predefinita, se si utilizza il parametro Expected e si fornisce un Value, DynamoDB presuppone che l'attributo esista e abbia un valore corrente da sostituire. Quindi non è necessario specificare{"Exists":true} perché è implicito. È possibile abbreviare la richiesta in: "Expected" : {"Color":{"Value":{"S":"Yellow"}}} Nota Se si specifica {"Exists":true} senza un valore di attributo da controllare, DynamoDB restituisce un errore.	No
ReturnValues	Utilizza questo parametro se desideri ottenere le coppie nome-valore dell'attributo prima che vengano aggiornate con la richiesta PutItem. I valori possibili dei parametri sono NONE (predefinito) o ALL_OLD. Se è stato specificato ALL_OLD e PutItem ha sovrascritto una coppia nome-valore dell'attributo, viene restituito il contenuto del vecchio elemento. Se questo parametro non viene fornito o è NONE, non viene restituito nulla. Tipo: string	No

Risposte

Sintassi

Nella sintassi di esempio seguente si presuppone che la richiesta abbia specificato un parametro ReturnValues di ALL_OLD; in caso contrario, la risposta ha solo l'elemento 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
}

Nome	Descrizione
Attributes	I valori degli attributi prima dell'operazione put, ma solo se la proprietà ReturnValues viene specificata come ALL_OLD nella richiesta. Tipo: mappa di coppie nome-valore dell'attributo.
ConsumedCapacityUnits	Il numero di unità di capacità di scrittura utilizzate dall'operazione. Questo valore mostra il numero applicato alla velocità effettiva assegnata. Per ulteriori informazioni, consulta Gestione delle impostazioni sulle tabelle di capacità assegnata di DynamoDB. Tipo: numero

Errori speciali

Errore	Descrizione
ConditionalCheckFailedException	Controllo condizionale non riuscito. Il valore di attributo previsto non è stato trovato.
ResourceNotFoundException	L'elemento o l'attributo specificati non sono stati trovati.

Esempi

Per gli esempi di utilizzo dell'SDK AWS, consulta Utilizzo di elementi e attributi.

Richiesta di esempio

// This header is abbreviated. For a sample of a complete header, see API DynamoDB di basso livello.
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"
}

Risposta di esempio

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
}

Operazioni correlate

• UpdateItem

• DeleteItem

• GetItem

• BatchGetItem