Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Utilizzo di elementi e attributi in DynamoDB In Amazon DynamoDB, un *elemento* è una raccolta di attributi. Ogni attributo ha un nome e un valore. Il valore di un attributo può essere un tipo scalare, un set o un tipo di documento. Per ulteriori informazioni, consulta [Amazon DynamoDB: come funziona](HowItWorks.md). DynamoDB fornisce quattro operazioni per le funzionalità di creazione, lettura, aggiornamento ed eliminazione CRUD (create/read/update/delete) di base. Tutte queste operazioni sono atomiche. + `PutItem`: crea un elemento. + `GetItem`: legge un elemento. + `UpdateItem`: aggiorna un elemento. + `DeleteItem`: elimina un elemento. Ognuna di queste operazioni richiede di specificare la chiave primaria dell'elemento da usare. Per leggere, ad esempio, un elemento con `GetItem`, devi specificare la chiave di partizione e la chiave di ordinamento (se applicabile) per l'elemento. Oltre alle quattro operazioni CRUD di base, DynamoDB fornisce anche le seguenti funzionalità: + `BatchGetItem`: legge fino a 100 elementi da una o più tabelle. + `BatchWriteItem`: crea o elimina fino a 25 elementi in una o più tabelle. Queste operazioni batch combinano diverse operazioni CRUD in una singola richiesta. Le operazioni batch, inoltre, leggono e scrivono gli elementi in parallelo, per ridurre al minimo la latenza delle risposte. In questa sezione viene descritto come usare queste operazioni e sono inclusi argomenti correlati, come gli aggiornamenti condizionali e i contatori atomici. Questa sezione include anche un codice di esempio che utilizza il AWS SDKs. **Topics** + [Dimensioni e formati degli elementi di DynamoDB](CapacityUnitCalculations.md) + [Lettura di un elemento](#WorkingWithItems.ReadingData) + [Scrittura di un elemento](#WorkingWithItems.WritingData) + [Valori restituiti](#WorkingWithItems.ReturnValues) + [Operazioni batch](#WorkingWithItems.BatchOperations) + [Contatori atomici](#WorkingWithItems.AtomicCounters) + [Scritture condizionali](#WorkingWithItems.ConditionalUpdate) + [Utilizzo di espressioni in DynamoDB](Expressions.md) + [Utilizzo del Time to Live in DynamoDB](TTL.md) + [Esecuzione di query in DynamoDB](Query.md) + [Scansione di tabelle in DynamoDB](Scan.md) + [PartiQL: un linguaggio di query compatibile con SQL per Amazon DynamoDB](ql-reference.md) + [Utilizzo degli elementi: Java](JavaDocumentAPIItemCRUD.md) + [Uso di elementi: .NET](LowLevelDotNetItemCRUD.md) ## Lettura di un elemento Per leggere un elemento da una tabella DynamoDB, utilizza l'operazione `GetItem`. Devi fornire il nome della tabella e la chiave primaria dell'elemento desiderato. **Example** L' AWS CLI esempio seguente mostra come leggere un elemento dalla `ProductCatalog` tabella. ``` aws dynamodb get-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' ``` **Nota** Con `GetItem`, devi specificare l'*intera* chiave primaria, non una parte di essa. Se, ad esempio, una tabella ha una chiave primaria composita (chiave di partizione e chiave di ordinamento), devi fornire un valore per la chiave di partizione e uno per la chiave di ordinamento. Una richiesta `GetItem` esegue una lettura consistente finale per impostazione predefinita. Puoi usare il parametro `ConsistentRead` per richiedere invece una lettura consistente assoluta. (Ciò consuma unità di capacità di lettura aggiuntive, ma restituisce la maggior parte delle up-to-date versioni dell'articolo.) `GetItem` restituisce tutti gli attributi dell'elemento. Puoi usare un'*espressione di proiezione* per restituire solo alcuni degli attributi. Per ulteriori informazioni, consulta [Utilizzo di espressioni di proiezione in DynamoDB](Expressions.ProjectionExpressions.md). Per restituire il numero di unità di capacità di lettura utilizzate da `GetItem`, imposta il parametro `ReturnConsumedCapacity` su `TOTAL`. **Example** L'esempio seguente AWS Command Line Interface (AWS CLI) mostra alcuni `GetItem` parametri opzionali. ``` aws dynamodb get-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --consistent-read \ --projection-expression "Description, Price, RelatedItems" \ --return-consumed-capacity TOTAL ``` ## Scrittura di un elemento Per creare, aggiornare o eliminare un elemento in una tabella DynamoDB, utilizza una delle operazioni seguenti: + `PutItem` + `UpdateItem` + `DeleteItem` Per ognuna di queste operazioni, devi specificare l'intera chiave primaria e non solo una parte di essa. Se, ad esempio, una tabella ha una chiave primaria composita (chiave di partizione e chiave di ordinamento), devi fornire un valore per la chiave di partizione e uno per la chiave di ordinamento. Per restituire il numero di unità di capacità di scrittura utilizzate da queste operazioni, imposta il parametro `ReturnConsumedCapacity` su uno dei valori seguenti: + `TOTAL`: restituisce il numero totale di unità di capacità di scrittura totali consumate. + `INDEXES`: restituisce il numero totale di unità di capacità di scrittura consumate, con i subtotali per la tabella e gli eventuali indici secondari interessati dall'operazione. + `NONE`: non vengono restituiti dettagli sulla capacità di scrittura. Questa è l'impostazione predefinita. ### PutItem `PutItem` crea un nuovo elemento. Se nella tabella esiste già un elemento con la stessa chiave, il nuovo elemento sostituisce quello esistente. **Example** Scrivi un nuovo elemento nella tabella `Thread`. La chiave primaria per `Thread` è costituita da `ForumName` (chiave di partizione) e `Subject` (chiave di ordinamento). ``` aws dynamodb put-item \ --table-name Thread \ --item file://item.json ``` Gli argomenti per `--item` sono memorizzati nel file `item.json`: ``` { "ForumName": {"S": "Amazon DynamoDB"}, "Subject": {"S": "New discussion thread"}, "Message": {"S": "First post in this thread"}, "LastPostedBy": {"S": "fred@example.com"}, "LastPostDateTime": {"S": "201603190422"} } ``` ### UpdateItem Se non esiste un elemento con la chiave specificata, `UpdateItem` crea un nuovo elemento. In caso contrario, modifica gli attributi di un elemento esistente. Puoi usare un'*espressione di aggiornamento* per specificare gli attributi che desideri modificare e i loro nuovi valori. Per ulteriori informazioni, consulta [Utilizzo di espressioni di aggiornamento in DynamoDB](Expressions.UpdateExpressions.md). Nell'espressione di aggiornamento usi i valori degli attributi di espressione come segnaposto per i valori effettivi. Per ulteriori informazioni, consulta [Utilizzo dei valori degli attributi di espressione in DynamoDB](Expressions.ExpressionAttributeValues.md). **Example** Modifica i diversi attributi nell'elemento `Thread`. Il parametro `ReturnValues` facoltativo mostra l'elemento dopo l'aggiornamento. Per ulteriori informazioni, consulta [Valori restituiti](#WorkingWithItems.ReturnValues). ``` aws dynamodb update-item \ --table-name Thread \ --key file://key.json \ --update-expression "SET Answered = :zero, Replies = :zero, LastPostedBy = :lastpostedby" \ --expression-attribute-values file://expression-attribute-values.json \ --return-values ALL_NEW ``` Gli argomenti per `--key` sono memorizzati nel file `key.json`: ``` { "ForumName": {"S": "Amazon DynamoDB"}, "Subject": {"S": "New discussion thread"} } ``` Gli argomenti per `--expression-attribute-values` sono memorizzati nel file `expression-attribute-values.json`: ``` { ":zero": {"N":"0"}, ":lastpostedby": {"S":"barney@example.com"} } ``` ### DeleteItem `DeleteItem` elimina l'elemento con la chiave specificata. **Example** L' AWS CLI esempio seguente mostra come eliminare l'`Thread`elemento. ``` aws dynamodb delete-item \ --table-name Thread \ --key file://key.json ``` ## Valori restituiti In alcuni casi potrebbe essere necessario che DynamoDB restituisca determinati valori degli attributi nello stato in cui si trovano prima o dopo la modifica. Le operazioni `PutItem`, `UpdateItem` e `DeleteItem` hanno un parametro `ReturnValues` che è possibile usare per restituire i valori degli attributi prima o dopo la modifica. Il valore predefinito per `ReturnValues` è `NONE`, il che significa che DynamoDB non restituisce informazioni sugli attributi che sono stati modificati. Di seguito sono illustrate le altre impostazioni valide per `ReturnValues`, organizzate in base all'operazione API di DynamoDB. ### PutItem + `ReturnValues`: `ALL_OLD` + Se sovrascrivi un elemento esistente, `ALL_OLD` restituisce l'intero elemento precedente alla sovrascrittura. + Se scrivi un elemento che non esiste, `ALL_OLD` non ha alcun effetto. ### UpdateItem L'uso più comune di `UpdateItem` è quello di aggiornare un elemento esistente. `UpdateItem` esegue tuttavia un'operazione *upsert*, ovvero crea automaticamente l'elemento, se non esiste già. + `ReturnValues`: `ALL_OLD` + Se aggiorni un elemento esistente, `ALL_OLD` restituisce l'intero elemento precedente all'aggiornamento. + Se aggiorni un item che non esiste (upsert), `ALL_OLD` non ha alcun effetto. + `ReturnValues`: `ALL_NEW` + Se aggiorni un elemento esistente, `ALL_NEW` restituisce l'intero elemento successivo all'aggiornamento. + Se aggiorni un elemento che non esiste (upsert), `ALL_NEW` restituisce l'intero elemento. + `ReturnValues`: `UPDATED_OLD` + Se aggiorni un elemento esistente, `UPDATED_OLD` restituisce solo gli attributi aggiornati, nello stato precedente all'aggiornamento. + Se aggiorni un item che non esiste (upsert), `UPDATED_OLD` non ha alcun effetto. + `ReturnValues`: `UPDATED_NEW` + Se aggiorni un elemento esistente, `UPDATED_NEW` restituisce solo gli attributi interessati, nello stato successivo all'aggiornamento. + Se aggiorni un elemento che non esiste (upsert), `UPDATED_NEW` restituisce solo gli attributi aggiornati, nello stato successivo all'aggiornamento. ### DeleteItem + `ReturnValues`: `ALL_OLD` + Se elimini un elemento esistente, `ALL_OLD` restituisce l'intero elemento precedente all'eliminazione. + Se elimini un elemento che non esiste, `ALL_OLD` non restituisce alcun dato. ## Operazioni batch Per le applicazioni che devono leggere o scrivere più elementi, DynamoDB fornisce le operazioni `BatchGetItem` e `BatchWriteItem`. L'uso di queste operazioni permette di ridurre il numero di viaggi di andata e ritorno di rete dall'applicazione a DynamoDB. Inoltre, DynamoDB esegue le singole operazioni di lettura o scrittura in parallelo. Le applicazioni possono ottenere un vantaggio da questo parallelismo, senza dover gestire la concorrenza o il threading. Le operazioni batch sono essenzialmente una combinazione di più richieste di lettura o di scrittura. Se, ad esempio, una richiesta `BatchGetItem` contiene cinque elementi, DynamoDB esegue cinque operazioni `GetItem` per conto tuo. Analogamente, se una richiesta `BatchWriteItem` contiene due richieste put e quattro richieste delete, DynamoDB esegue due richieste `PutItem` e quattro richieste `DeleteItem`. In generale, un'operazione batch non ha esito negativo a meno che *tutte* le richieste nel batch non abbiano esito negativo. Supponi, ad esempio, di eseguire un'operazione `BatchGetItem`, ma una delle singole richieste `GetItem` nel batch ha esito negativo. In questo caso, `BatchGetItem` restituisce le chiavi e i dati della richiesta `GetItem` che ha avuto esito negativo. Le altre richieste `GetItem` nel batch non sono interessate. ### BatchGetItem Una singola operazione `BatchGetItem` può contenere fino a 100 singole richieste `GetItem` e può recuperare fino a 16 MB di dati. Un'operazione `BatchGetItem` può inoltre recuperare elementi da più tabelle. **Example** Recupera due elementi dalla tabella `Thread` usando un'espressione di proiezione per restituire solo alcuni degli attributi. ``` aws dynamodb batch-get-item \ --request-items file://request-items.json ``` Gli argomenti per `--request-items` sono memorizzati nel file `request-items.json`: ``` { "Thread": { "Keys": [ { "ForumName":{"S": "Amazon DynamoDB"}, "Subject":{"S": "DynamoDB Thread 1"} }, { "ForumName":{"S": "Amazon S3"}, "Subject":{"S": "S3 Thread 1"} } ], "ProjectionExpression":"ForumName, Subject, LastPostedDateTime, Replies" } } ``` ### BatchWriteItem L'operazione `BatchWriteItem` può contenere fino a 25 singole richieste `PutItem` e `DeleteItem` e può scrivere fino a 16 MB di dati. La dimensione massima di un singolo elemento è 400 KB. Un'operazione `BatchWriteItem` può inoltre inserire o eliminare elementi in più tabelle. **Nota** `BatchWriteItem` non supporta le richieste `UpdateItem`. **Example** Scrivi due elementi nella tabella `ProductCatalog`. ``` aws dynamodb batch-write-item \ --request-items file://request-items.json ``` Gli argomenti per `--request-items` sono memorizzati nel file `request-items.json`: ``` { "ProductCatalog": [ { "PutRequest": { "Item": { "Id": { "N": "601" }, "Description": { "S": "Snowboard" }, "QuantityOnHand": { "N": "5" }, "Price": { "N": "100" } } } }, { "PutRequest": { "Item": { "Id": { "N": "602" }, "Description": { "S": "Snow shovel" } } } } ] } ``` ## Contatori atomici È possibile utilizzare l'operazione `UpdateItem` per implementare un *contatore atomico*: un attributo numerico che viene incrementato, incondizionatamente, senza interferire con altre richieste di scrittura. Tutte le richieste di scrittura vengono applicate in base all'ordine di ricezione. Con un contatore atomico, gli aggiornamenti non sono idempotenti. In altre parole, il valore numerico aumenta o diminuisce a ogni chiamata di `UpdateItem`. Se il valore di incremento utilizzato per aggiornare il contatore atomico è positivo, può causare un conteggio in eccesso. Se il valore dell'incremento è negativo, può causare un conteggio in difetto. Puoi usare un contatore atomico per tenere traccia del numero di visitatori di un sito Web. In questo caso, l'applicazione incrementa un valore numerico, indipendentemente dal valore corrente. Se un'operazione `UpdateItem` non va a buon fine, l'applicazione può semplicemente provare a ripetere l'operazione. Ciò rischierebbe di aggiornare il contatore due volte, anche se probabilmente un lieve discostamento in eccesso o in difetto nel numero di visitatori del sito Web può essere tollerato. Un contatore atomico non è appropriato quando un conteggio maggiore o minore di quello effettivo non può essere tollerato (ad esempio, in un'applicazione bancaria). In questo caso, è preferibile usare un aggiornamento condizionale al posto di un contatore atomico. Per ulteriori informazioni, consulta [Incremento e decremento di attributi numerici](Expressions.UpdateExpressions.md#Expressions.UpdateExpressions.SET.IncrementAndDecrement). **Example** L' AWS CLI esempio seguente incrementa il valore `Price` di un prodotto di 5. In questo esempio, l’elemento esisteva già prima dell’aggiornamento del contatore. Poiché `UpdateItem` non è idempotente, il valore di `Price` aumenta ogni volta che si esegue il codice. ``` aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id": { "N": "601" }}' \ --update-expression "SET Price = Price + :incr" \ --expression-attribute-values '{":incr":{"N":"5"}}' \ --return-values UPDATED_NEW ``` ## Scritture condizionali Per impostazione predefinita, le operazioni di scrittura di DynamoDB `PutItem` (`DeleteItem`,) *sono* incondizionate: ogni operazione sovrascrive un elemento esistente con la chiave primaria specificata. Facoltativamente, per queste operazioni DynamoDB supporta le scritture condizionali. Una scrittura condizionale ha esito positivo solo se gli attributi dell'elemento soddisfano una o più condizioni. In caso contrario, restituisce un errore. Le scritture condizionali controllano le condizioni rispetto alla versione aggiornata più recente dell’elemento. Se l’elemento non esisteva in precedenza o se l’ultima operazione completata su quell’elemento è stata un’eliminazione, la scrittura condizionale non troverà alcun elemento precedente. Le operazioni di scrittura condizionali sono utili in molte situazioni. Potrebbe ad esempio essere necessario fare in modo che un'operazione `PutItem` abbia esito positivo solo se non è già presente un elemento con la stessa chiave primaria. In alternativa, si potrebbe impedire a un'operazione `UpdateItem` di modificare un elemento se uno o più dei relativi attributi ha un determinato valore. Le scritture condizionali sono utili nei casi in cui più utenti tentano di modificare lo stesso elemento. Si consideri il diagramma seguente, in cui due utenti (Alice e Bob) stanno lavorando con lo stesso elemento in una tabella DynamoDB. ![Gli utenti Alice e Bob tentano di modificare un elemento con Id 1, dimostrando la necessità di scritture condizionali.](http://docs.aws.amazon.com/it_it/amazondynamodb/latest/developerguide/images/update-no-condition.png) Supponiamo che Alice utilizzi l'attributo to per aggiornare l' AWS CLI attributo a 8. `Price` ``` aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --update-expression "SET Price = :newval" \ --expression-attribute-values file://expression-attribute-values.json ``` Gli argomenti per `--expression-attribute-values` sono memorizzati nel file `expression-attribute-values.json`: ``` { ":newval":{"N":"8"} } ``` Supponi ora che Bob esegua una richiesta `UpdateItem` simile in un secondo momento, modificando però il valore di `Price` in 12. Per Bob, l'aspetto del parametro `--expression-attribute-values` è simile al seguente. ``` { ":newval":{"N":"12"} } ``` La richiesta di Bob ha esito positivo, ma l'aggiornamento precedente di Alice viene perso. Per richiedere un'operazione `PutItem`, `DeleteItem` o `UpdateItem` condizionale, specifichi un'espressione di condizione. Un'*espressione condizionale* è una stringa contenente nomi di attributi, operatori condizionali e funzioni predefinite. L'intera espressione deve essere vera. In caso contrario, l'operazione non va a buon fine. Considera ora il diagramma seguente, che mostra in che modo le scritture condizionali impedirebbero la sovrascrittura dell'aggiornamento di Alice. ![Scrittura condizionale che impedisce all’aggiornamento dell’utente Bob di sovrascrivere le modifiche dell’utente Alice allo stesso elemento.](http://docs.aws.amazon.com/it_it/amazondynamodb/latest/developerguide/images/update-yes-condition.png) Alice prova innanzitutto ad aggiornare il valore di `Price` a 8, ma solo se il valore di `Price` corrente è 10. ``` aws dynamodb update-item \ --table-name ProductCatalog \ --key '{"Id":{"N":"1"}}' \ --update-expression "SET Price = :newval" \ --condition-expression "Price = :currval" \ --expression-attribute-values file://expression-attribute-values.json ``` Gli argomenti per `--expression-attribute-values` sono memorizzati nel file `expression-attribute-values.json`: ``` { ":newval":{"N":"8"}, ":currval":{"N":"10"} } ``` L'aggiornamento di Alice riesce perché la condizione è vera. Bob cerca quindi di aggiornare il valore di `Price` a 12, ma solo se il valore di `Price` corrente è 10. Per Bob, l'aspetto del parametro `--expression-attribute-values` è simile al seguente. ``` { ":newval":{"N":"12"}, ":currval":{"N":"10"} } ``` Poiché in precedenza Alice ha modificato il valore di `Price` in 8, l'espressione condizionale è falsa e l'aggiornamento di Bob non riesce. Per ulteriori informazioni, consulta [Esempio di CLI di espressione condizionale in DynamoDB](Expressions.ConditionExpressions.md). ### Idempotenza delle scritture condizionali Le scritture condizionali possono essere *idempotenti* se la verifica condizionale è sullo stesso attributo in fase di aggiornamento. Ciò significa che DynamoDB esegue una certa richiesta di scrittura solo se determinati valori degli attributi nell'elemento corrispondono a quanto previsto al momento della richiesta. Supponi, ad esempio, di eseguire una richiesta `UpdateItem` per aumentare il valore di `Price` per un elemento di 3, ma solo se il valore di `Price` corrente è 20. Dopo che hai inviato la richiesta, ma prima di ricevere i risultati, si verifica un errore di rete e non sai se la richiesta ha avuto esito positivo. Poiché la scrittura condizionale è idempotente, è possibile eseguire di nuovo la stessa richiesta `UpdateItem` e DynamoDB aggiornerà l'elemento solo se il valore di `Price` corrente è 20. ### Unità di capacità utilizzate dalle scritture condizionali Se `ConditionExpression` restituisce false durante una scrittura condizionale, DynamoDB utilizza comunque la capacità di scrittura della tabella. La quantità consumata dipende dalla dimensione dell'elemento esistente (o almeno 1). Ad esempio, se un elemento esistente è di 300 KB e il nuovo elemento che si sta cercando di creare o aggiornare è 310 KB, le unità di capacità di scrittura consumate saranno 300 se la condizione restituisce un errore o 310 se la condizione riesce. Se si tratta di un elemento nuovo (non un elemento esistente), le unità di capacità di scrittura consumate saranno 1 se la condizione restituisce un errore e 310 se la condizione riesce. **Nota** Le operazioni di scrittura utilizzano solo unità di capacità in *scrittura*. Non utilizzano mai unità di capacità in *lettura*. Una scrittura condizionale non riuscita restituisce `ConditionalCheckFailedException`. In questo caso, non vengono inviate informazioni nella risposta sulla capacità di scrittura utilizzata. Per restituire il numero di unità di capacità di scrittura utilizzate durante una scrittura condizionale, usa il parametro `ReturnConsumedCapacity`: + `TOTAL`: restituisce il numero totale di unità di capacità di scrittura totali consumate. + `INDEXES`: restituisce il numero totale di unità di capacità di scrittura consumate, con i subtotali per la tabella e gli eventuali indici secondari interessati dall'operazione. + `NONE`: non vengono restituiti dettagli sulla capacità di scrittura. Questa è l'impostazione predefinita. **Nota** A differenza di un indice secondario globale, un indice secondario locale condivide la capacità di throughput assegnata con la relativa tabella. L'attività di lettura e scrittura su un indice secondario locale utilizza la capacità di throughput assegnata della tabella.