UpdateItem

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

Modifica gli attributi di un elemento esistente. È possibile eseguire un aggiornamento condizionale (inserire una nuova coppia nome-valore attributo se non esiste o sostituire una coppia nome-valore esistente se ha determinati valori di attributo previsti).

Nota

Non è possibile aggiornare gli attributi della chiave primaria utilizzando UpdateItem. Eliminate invece l'elemento e PutItem utilizzatelo per creare un nuovo elemento con nuovi attributi.

L' UpdateItem operazione include un Action parametro che definisce come eseguire l'aggiornamento. È possibile inserire, eliminare o aggiungere 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.

Se un elemento esistente ha una chiave primaria specificata:

• PUT: aggiunge l'attributo specificato. Se l'attributo esiste, viene sostituito dal nuovo valore.

• DELETE: se non viene specificato alcun valore, rimuove l'attributo e il relativo valore. Se viene specificato un set di valori, i valori nel set specificato vengono rimossi dal set precedente. Quindi, se il valore dell'attributo contiene [a, b, c] e l'azione di eliminazione contiene [a, c], il valore dell'attributo finale sarà [b]. Il tipo di valore specificato deve corrispondere al tipo di valore esistente. La specifica di un set vuoto non è consentita.

• ADD: utilizzare l'azione di aggiunta solo per i numeri o se l'attributo di destinazione è un set (inclusi i set di stringhe). ADD non funziona se l'attributo di destinazione è un singolo valore stringa o un valore binario scalare. Il valore specificato viene aggiunto a un valore numerico (incrementando o diminuendo il valore numerico esistente) o aggiunto come valore aggiuntivo in un set di stringhe. Se viene specificato un set di valori, i valori vengono aggiunti al set esistente. Ad esempio, se il set originale è [1,2] e il valore fornito è [3], dopo l'operazione di aggiunta l'insieme sarà [1,2,3] e non [4,5]. Se viene specificata un'operazione ADD per un attributo set e il tipo di attributo specificato non corrisponde al tipo di set esistente, si verifica un errore.

  Se si utilizza ADD per un attributo che non esiste, l'attributo e i relativi valori verranno aggiunti all'elemento.

Se nessun elemento corrisponde alla chiave primaria specificata:

• PUT: crea un nuovo elemento con la chiave primaria specificata. Quindi aggiunge l'attributo specificato.

• DELETE: non succede nulla.

• ADD: viene creato un elemento con la chiave primaria e il numero (o insieme di numeri) forniti per il valore dell'attributo. Non valido per un tipo stringa o binario.

Nota

Se si utilizza ADD per aumentare o diminuire un valore numerico per un elemento che non esiste prima dell'aggiornamento, DynamoDB utilizzerà 0 come valore iniziale. Inoltre, se si aggiorna un elemento tramite ADD per aumentare o diminuire un valore numerico per un attributo che non esiste prima dell'aggiornamento, DynamoDB utilizzerà 0 come valore iniziale. Ad esempio, si supponga di utilizzare ADD per aggiungere +3 a un attributo che non esisteva prima dell'aggiornamento. DynamoDB utilizzerà 0 come valore iniziale e il valore dopo l'aggiornamento sarà 3.

Per ulteriori informazioni sull'utilizzo di questa operazione, consulta Utilizzo di elementi e attributi in DynamoDB.

Richieste

Sintassi

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

Nome	Descrizione	Richiesto
TableName	Il nome della tabella che contiene l'elemento da aggiornare. ▬Tipo: stringa	Sì
Key	La chiave primaria che definisce l'elemento. Per ulteriori informazioni sulle chiavi primarie, vedere Chiave primaria. Tipo: mappa di HashKeyElement sul suo valore e RangeKeyElement sul suo valore.	Sì
AttributeUpdates	Mappa del nome dell'attributo al nuovo valore e operazione per l'aggiornamento. I nomi degli attributi specificano gli attributi da modificare e non possono contenere attributi di chiave primaria. Tipo: mappa del nome dell'attributo, del valore e dell'operazione per l'aggiornamento dell'attributo.
AttributeUpdates:Action	Specifica come eseguire l'aggiornamento. Valori possibili PUT (predefinito), ADD o DELETE. La semantica è spiegata nella UpdateItem descrizione. ▬Tipo: stringa Impostazione predefinita: PUT	No
Expected	Designa un attributo per un aggiornamento 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 degli attributi.	No
Expected:AttributeName	Il nome dell'attributo per il put condizionale. ▬Tipo: stringa	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 aggiorna 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 aggiornare 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 UpdateItem. I valori dei parametri possibili sono NONE (predefinito) oALL_OLD, UPDATED_OLD, ALL_NEW o UPDATED_NEW. Se è stato specificato ALL_OLD e UpdateItem 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. Se viene specificato ALL_NEW, vengono restituiti tutti gli attributi della nuova versione dell'elemento. Se viene specificato UPDATED_NEW, vengono restituite tutte le versioni dei soli attributi aggiornati. ▬Tipo: stringa	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: 140

{"Attributes":{
	"AttributeName1":{"S":"AttributeValue1"},
	"AttributeName2":{"S":"AttributeValue2"},
	"AttributeName3":{"S":"AttributeValue3"},
	"AttributeName5":{"B":"dmFsdWU="}
	},
"ConsumedCapacityUnits":1
}

Nome	Descrizione
Attributes	Una mappa di coppie nome-valore attributo, ma solo se il parametro ReturnValues viene specificato come qualcosa di diverso da NONE 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 Modalità di capacità fornita da DynamoDB. Tipo: numero

Errori speciali

Errore	Descrizione
ConditionalCheckFailedException	Controllo condizionale non riuscito. Il valore dell'attributo ("+ name +") è ("+ value +") ma era previsto ("+ expValue +")
ResourceNotFoundExceptions	L'elemento o l'attributo specificati non sono stati trovati.

Esempi

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

Richiesta di esempio

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

Risposta di esempio

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
}

Operazioni correlate

• PutItem

• DeleteItem