Utilizzo di elementi in DynamoDB con il modello di documento AWS SDK for .NET

I seguenti esempi di codice illustrano come eseguire una serie di operazioni con il modello di documento  AWS SDK for .NET . È possibile utilizzare questi esempi per eseguire operazioni CRUD, batch e transazioni.

Per eseguire operazioni sui dati usando il modello di documento, è necessario anzitutto chiamare il metodo Table.LoadTable, che crea un'istanza della classe Table la quale rappresenta una tabella specifica. Nel seguente esempio C# viene creato un oggetto Table che rappresenta la tabella ProductCatalog in Amazon DynamoDB.

Esempio

Table table = Table.LoadTable(client, "ProductCatalog");

Nota

Generalmente, si usa il metodo LoadTable una volta all'inizio dell'applicazione poiché effettua una chiamata DescribeTable che aggiunge il percorso di andata e ritorno a DynamoDB.

Successivamente, puoi utilizzare l'oggetto Table per eseguire diverse operazioni sui dati. Ogni operazione sui dati dispone di due tipi di overload: uno accetta i minimi parametri imprescindibili e l'altro accetta informazioni di configurazione opzionali specifica dell'operazione. Per esempio, per recuperare un item, è necessario fornire il valore della chiave primaria della tabella nel caso in cui tu possa usare il seguente overload GetItem:

Esempio

// Get the item from a table that has a primary key that is composed of only a partition key.
Table.GetItem(Primitive partitionKey);
// Get the item from a table whose primary key is composed of both a partition key and sort key.
Table.GetItem(Primitive partitionKey, Primitive sortKey);

Puoi anche passare parametri facoltativi a questi metodi. Per esempio, la precedente operazione GetItem restituisce l'item completo includendo tutti i suoi attributi. Puoi specificare, a tua discrezione, un elenco di attributi da recuperare. In questo caso, usa il seguente overload GetItem che accetta il parametro dell'oggetto di configurazione specifico dell'operazione.

Esempio

// Configuration object that specifies optional parameters.
GetItemOperationConfig config = new GetItemOperationConfig()
{
  AttributesToGet = new List<string>() { "Id", "Title" },
};
// Pass in the configuration to the GetItem method.
// 1. Table that has only a partition key as primary key.
Table.GetItem(Primitive partitionKey, GetItemOperationConfig config);
// 2. Table that has both a partition key and a sort key.
Table.GetItem(Primitive partitionKey, Primitive sortKey, GetItemOperationConfig config);

Puoi utilizzare l'oggetto di configurazione per specificare diversi parametri facoltativi, come richiedere un elenco specifico di attributi o specificare la dimensione della pagina (numero di item per pagina). Ogni metodo di operazione sui dati ha una propria classe di configurazione. Ad esempio, puoi utilizzare la classe GetItemOperationConfig per fornire opzioni per l'operazione GetItem. Puoi utilizzare la classe PutItemOperationConfig per fornire parametri opzionali per l'operazione PutItem.

Nelle sezioni seguenti, viene spiegata ogni operazione sui dati supportata dalla classe Table.

Inserimento di un oggetto - Tabella. PutItem metodo

Il metodo PutItem carica l'istanza di input Document nella tabella. Se un item che ha una chiave primaria specificata nel Document di input esiste nella tabella, l'operazione PutItem sostituisce l'item esistente per intero. Il nuovo item è identico all'oggetto Document che hai fornito al metodo PutItem. Se il tuo item originale aveva attributi extra di qualsiasi genere, questi non sono più presenti nel nuovo item.

Di seguito sono riportate le fasi per collocare un item in una tabella usando il modello di documento AWS SDK for .NET .

1. Esegui il metodo Table.LoadTable che fornisce il nome della tabella nella quale desideri inserire un elemento.

2. crea un oggetto Document che ha un elenco dei nomi degli attributi e dei loro valori;

3. Eseguire Table.PutItem fornendo l'istanza Document come parametro.

Il seguente esempio di codice C# mostra le attività precedenti. L'esempio carica un item nella tabella ProductCatalog.

Esempio

Table table = Table.LoadTable(client, "ProductCatalog");

var book = new Document();
book["Id"] = 101;
book["Title"] = "Book 101 Title";
book["ISBN"] = "11-11-11-11";
book["Authors"] = new List<string> { "Author 1", "Author 2" };
book["InStock"] = new DynamoDBBool(true);
book["QuantityOnHand"] = new DynamoDBNull();

table.PutItem(book);

Nell'esempio precedente, l'Documentistanza crea un elemento conNumber, String String SetBoolean, e Null attributi. (Nullviene utilizzato per indicare che la QuantityOnmano di questo prodotto è sconosciuta.) Per Boolean e Null, utilizza i metodi del costruttore DynamoDBBool e DynamoDBNull.

In DynamoDB i tipi di dati List e Map possono contenere elementi composti da altri tipi di dati. Di seguito viene mostrato come mappare questi tipi di dati nell'API del modello di documento:

• List: utilizzare il costruttore DynamoDBList.

• Map: utilizzare il costruttore Document.

Puoi modificare l'esempio precedente per aggiungere un attributo List all'item. Per far ciò, usa un costruttore DynamoDBList come mostrato nel seguente esempio di codice:

Esempio

Table table = Table.LoadTable(client, "ProductCatalog");

var book = new Document();
book["Id"] = 101;

/*other attributes omitted for brevity...*/

var relatedItems = new DynamoDBList();
relatedItems.Add(341);
relatedItems.Add(472);
relatedItems.Add(649);
book.Add("RelatedItems", relatedItems);

table.PutItem(book);

Per aggiungere un attributo Map al libro, definisci un altro oggetto Document. Il seguente esempio di codice dimostra come eseguire questa operazione.

Esempio

Table table = Table.LoadTable(client, "ProductCatalog");

var book = new Document();
book["Id"] = 101;

/*other attributes omitted for brevity...*/

var pictures = new Document();
pictures.Add("FrontView", "http://example.com/products/101_front.jpg" );
pictures.Add("RearView", "http://example.com/products/101_rear.jpg" );

book.Add("Pictures", pictures);

table.PutItem(book);

Questi esempi si basano sull'item mostrato in Riferimento agli attributi degli elementi quando si utilizzano espressioni in DynamoDB. Il modello di documento ti permette di creare attributi nidificati complessi, come l'attributo ProductReviews mostrato in questo caso di studio.

Specifica dei parametri facoltativi

Puoi configurare parametri facoltativi per l'operazione PutItem aggiungendo il parametro PutItemOperationConfig. Per un elenco completo dei parametri opzionali, vedere PutItem. L'esempio di codice C# seguente inserisce un item nella tabella ProductCatalog. Esso specifica il seguente parametro opzionale:

• Il parametro ConditionalExpression per renderla una richiesta di collocazione facoltativa. L'esempio crea un'espressione che specifica che l'attributo ISBN deve avere un valore specifico, che deve essere presente nell'item che stai sostituendo.

Esempio

Table table = Table.LoadTable(client, "ProductCatalog");

var book = new Document();
book["Id"] = 555;
book["Title"] = "Book 555 Title";
book["Price"] = "25.00";
book["ISBN"] = "55-55-55-55";
book["Name"] = "Item 1 updated";
book["Authors"] = new List<string> { "Author x", "Author y" };
book["InStock"] = new DynamoDBBool(true);
book["QuantityOnHand"] = new DynamoDBNull();

// Create a condition expression for the optional conditional put operation.
Expression expr = new Expression();
expr.ExpressionStatement = "ISBN = :val";
expr.ExpressionAttributeValues[":val"] = "55-55-55-55";

PutItemOperationConfig config = new PutItemOperationConfig()
{
  // Optional parameter.
     ConditionalExpression = expr
};

table.PutItem(book, config);

Ottenere un articolo - Tabella. GetItem

L'operazione GetItem recupera un item come un'istanza Document. È necessario fornire la chiave primaria dell'item che vuoi recuperare, come mostrato nel seguente esempio di codice C#:

Esempio

Table table = Table.LoadTable(client, "ProductCatalog");
Document document = table.GetItem(101); // Primary key 101.

L'operazione GetItem restituisce tutti gli attributi di un item ed esegue, per impostazione predefinita, una lettura consistente finale (consulta Consistenza di lettura).

Specifica dei parametri facoltativi

Puoi configurare opzioni aggiuntive per l'operazione GetItem aggiungendo il parametro GetItemOperationConfig. Per un elenco completo dei parametri opzionali, vedere GetItem. L'esempio di codice C# seguente recupera un item dalla tabella ProductCatalog. L'esempio specifica la GetItemOperationConfig per fornire i seguenti parametri facoltativi:

• il parametro AttributesToGet per recuperare solo gli attributi specificati;

• il parametro ConsistentRead per richiedere i valori più recenti per tutti gli attributi specificati. Per ulteriori informazioni sulla consistenza dei dati, consulta Consistenza di lettura.

Esempio

Table table = Table.LoadTable(client, "ProductCatalog");

GetItemOperationConfig config = new GetItemOperationConfig()
{
  AttributesToGet = new List<string>() { "Id", "Title", "Authors", "InStock", "QuantityOnHand" },
  ConsistentRead = true
};
Document doc = table.GetItem(101, config);

Quando recuperi un item usando l'API del modello di documento, puoi ottenere l'accesso ai singoli elementi nell'oggetto Document restituito, come mostrato nell'esempio seguente:

Esempio

int id = doc["Id"].AsInt();
string title = doc["Title"].AsString();
List<string> authors = doc["Authors"].AsListOfString();
bool inStock = doc["InStock"].AsBoolean();
DynamoDBNull quantityOnHand = doc["QuantityOnHand"].AsDynamoDBNull();

Per gli attributi di tipo List o Map, viene mostrato di seguito come mapparli nell'API del modello di documento:

• List: utilizzare il metodo AsDynamoDBList.

• Map: utilizzare il metodo AsDocument.

Il seguente esempio di codice mostra come recuperare un List (RelatedItems) e un Map (Pictures) dall'Documentoggetto:

Esempio

DynamoDBList relatedItems = doc["RelatedItems"].AsDynamoDBList();

Document pictures = doc["Pictures"].AsDocument();

Eliminazione di un elemento - Tabella. DeleteItem

L'operazione DeleteItem elimina un item da un tabella. Puoi passare la chiave primaria dell'item con un parametro. Oppure, se hai già letto un item e hai l'oggetto Document corrispondente, puoi passarlo come un parametro al metodo DeleteItem come mostrato nel seguente esempio di codice C#.

Esempio

Table table = Table.LoadTable(client, "ProductCatalog");

// Retrieve a book (a Document instance)
Document document = table.GetItem(111);

// 1) Delete using the Document instance.
 table.DeleteItem(document);

// 2) Delete using the primary key.
int partitionKey = 222;
table.DeleteItem(partitionKey)

Specifica dei parametri facoltativi

Puoi configurare opzioni aggiuntive per l'operazione Delete aggiungendo il parametro DeleteItemOperationConfig. Per un elenco completo dei parametri opzionali, vedere DeleteTable. Il seguente esempio di codice C# specifica i due seguenti parametri facoltativi:

• il parametro ConditionalExpression per garantire che l'item libro che si eliminerà abbia un valore specifico per l'attributo ISBN;

• il parametro ReturnValues per richiedere che il metodo Delete restituisca l'item che ha eliminato.

Esempio

Table table = Table.LoadTable(client, "ProductCatalog");
int partitionKey = 111;

Expression expr = new Expression();
expr.ExpressionStatement = "ISBN = :val";
expr.ExpressionAttributeValues[":val"] = "11-11-11-11";

// Specify optional parameters for Delete operation.
DeleteItemOperationConfig config = new DeleteItemOperationConfig
{
     ConditionalExpression = expr,
     ReturnValues = ReturnValues.AllOldAttributes // This is the only supported value when using the document model.
};

// Delete the book.
Document d = table.DeleteItem(partitionKey, config);

Aggiornamento di un elemento - Tabella. UpdateItem

L'operazione UpdateItem aggiorna un item esistente se presente. Se non viene trovato l'item che dispone della chiave primaria specificata, l'operazione UpdateItem aggiunge un nuovo item.

Puoi usare l'operazione UpdateItem per aggiornare i valori degli attributi esistenti, aggiungere nuovi attributi alla raccolta esistente o eliminare attributi dalla raccolta esistente. Fornisci questi aggiornamenti creando un'istanza Document che descrive gli aggiornamenti che desideri eseguire.

L'operazione UpdateItem usa le seguenti linee guida:

• Se l'item non esiste, UpdateItem aggiunge un nuovo item usando la chiave primaria specificata nell'input.

• Se l'item esiste, UpdateItem applica gli aggiornamenti come segue:

  • sostituisce il valore dell'attributo esistente con i valori dell'aggiornamento;

  • se un attributo che fornisci nell'input non esiste, viene aggiunto un nuovo attributo all'item;

  • se il valore dell'attributo di input è nullo, viene eliminato l'attributo qualora presente.

Nota

Questa UpdateItem operazione di medio livello non supporta l'Addazione (vedi UpdateItem) supportata dall'operazione DynamoDB sottostante.

Nota

L'operazione PutItem (Inserimento di un oggetto - Tabella. PutItem metodo) può anche eseguire un aggiornamento. Se chiami PutItem per caricare un item e la chiave primaria esiste, l'operazione PutItem sostituisce l'intero item. Se vi sono attributi nell'item esistente e tali attributi non sono specificati nel Document che è stato inserito, l'operazione PutItem li eliminerà. Tuttavia, UpdateItem aggiorna solo gli attributi di input specificati. Qualsiasi altro attributo esistente di quell'item rimarrà invariato.

Di seguito sono riportati i passaggi per aggiornare un elemento utilizzando il AWS SDK for .NET modello di documento:

1. Eseguire il metodo Table.LoadTable fornendo il nome della tabella nella quale si desidera eseguire l'operazione di aggiornamento.

2. Crea un'istanza Document fornendo tutti gli aggiornamenti che desideri eseguire.

   Per rimuovere un attributo esistente, specifica che il valore dell'attributo sia nullo;

3. chiama il metodo Table.UpdateItem fornendo l'istanza di Document come parametro di input.

   È necessario fornire la chiave primaria o nell'istanza Document o in maniera esplicita come un parametro.

Il seguente esempio di codice C# mostra le attività precedenti. L'esempio di codice aggiorna un item nella tabella Book. L'operazione UpdateItem aggiorna l'attributo Authors esistente, elimina l'attributo PageCount e aggiunge un nuovo attributo XYZ. L'istanza Document include la chiave primaria del libro da aggiornare.

Esempio

Table table = Table.LoadTable(client, "ProductCatalog");

var book = new Document();

// Set the attributes that you wish to update.
book["Id"] = 111; // Primary key.
// Replace the authors attribute.
book["Authors"] = new List<string> { "Author x", "Author y" };
// Add a new attribute.
book["XYZ"] = 12345;
// Delete the existing PageCount attribute.
book["PageCount"] = null;

table.Update(book);

Specifica dei parametri facoltativi

Puoi configurare opzioni aggiuntive per l'operazione UpdateItem aggiungendo il parametro UpdateItemOperationConfig. Per un elenco completo dei parametri opzionali, vedere UpdateItem.

Il seguente esempio di codice C# aggiorna il prezzo di un item libro a 25. Esso specifica i due seguenti parametri facoltativi:

• il parametro ConditionalExpression che identifica l'attributo Price con valore pari a 20, che prevedi sarà presente;

• il parametro ReturnValues per richiedere che l'operazione UpdateItem restituisca l'item che è stato aggiornato.

Esempio

Table table = Table.LoadTable(client, "ProductCatalog");
string partitionKey = "111";

var book = new Document();
book["Id"] = partitionKey;
book["Price"] = 25;

Expression expr = new Expression();
expr.ExpressionStatement = "Price = :val";
expr.ExpressionAttributeValues[":val"] = "20";

UpdateItemOperationConfig config = new UpdateItemOperationConfig()
{
    ConditionalExpression = expr,
    ReturnValues = ReturnValues.AllOldAttributes
};

Document d1 = table.Update(book, config);

Scrittura in batch: collocazione ed eliminazione di più elementi

La scrittura in batch fa riferimento alla collocazione e all'eliminazione di più item in un batch. L'operazione ti consente di inserire ed eliminare più item da una o più tabelle con un'unica chiamata. Di seguito sono riportati i passaggi per inserire o eliminare più elementi da una tabella utilizzando l'API del modello di AWS SDK for .NET documento.

1. crea un oggetto Table eseguendo il metodo Table.LoadTable e fornendo il nome della tabella in cui desideri eseguire l'operazione batch;

2. Eseguire il metodo createBatchWrite nell'istanza della tabella creata nella fase precedente e creare un oggetto DocumentBatchWrite.

3. utilizza i metodi dell'oggetto DocumentBatchWrite per specificare i documenti che desideri caricare o eliminare;

4. Richiamare il metodo DocumentBatchWrite.Execute per eseguire l'operazione in batch.

   Quando usi l'API del modello di documento, puoi specificare qualsiasi numero di operazioni in un batch. Tuttavia, DynamoDB limita il numero di operazioni in un batch e la dimensione totale del batch in un'operazione batch. Per ulteriori informazioni sui limiti specifici, consulta BatchWriteItem. Se l'API del modello di documento rileva una risposta di scrittura in batch che ha superato il numero delle richieste scritte consentito o una dimensione di un payload HTTP di un batch che è andata oltre il limite prestabilito da BatchWriteItem, essa divide il batch in più batch di dimensione inferiore. Inoltre, se una risposta a un'operazione di scrittura in batch restituisce item non elaborati, l'API del modello di documento invia automaticamente un'altra richiesta batch con gli elementi non elaborati.

Il seguente esempio di codice C# mostra le fasi precedenti. L'esempio usa l'operazione di scrittura in batch per eseguire due scritture: caricare un item libro ed eliminare un altro item libro.

Table productCatalog = Table.LoadTable(client, "ProductCatalog");
var batchWrite = productCatalog.CreateBatchWrite();

var book1 = new Document();
book1["Id"] = 902;
book1["Title"] = "My book1 in batch write using .NET document model";
book1["Price"] = 10;
book1["Authors"] = new List<string> { "Author 1", "Author 2", "Author 3" };
book1["InStock"] = new DynamoDBBool(true);
book1["QuantityOnHand"] = 5;

batchWrite.AddDocumentToPut(book1);
// specify delete item using overload that takes PK.
batchWrite.AddKeyToDelete(12345);

batchWrite.Execute();

Per un esempio di utilizzo, consulta Esempio: operazioni Batch utilizzando l'API del modello di AWS SDK for .NET documento.

Puoi utilizzare l'operazione batchWrite per eseguire operazioni di collocazione ed eliminazione su più tabelle. Di seguito sono riportati i passaggi per inserire o eliminare più elementi da più tabelle utilizzando il modello di AWS SDK for .NET documento.

1. Crea un'istanza DocumentBatchWrite per ogni tabella in cui desideri collocare o eliminare più item come descritto nella procedura precedente;

2. crea un'istanza MultiTableDocumentBatchWrite e aggiungi l'oggetto individuale DocumentBatchWrite nell'istanza;

3. Esegui il metodo MultiTableDocumentBatchWrite.Execute.

Il seguente esempio di codice C# mostra le fasi precedenti. L'esempio usa l'operazione di scrittura in batch per eseguire le seguenti operazioni di scrittura:

• inserisci un nuovo item nell'item della tabella Forum;

• inserisci un item nella tabella Thread ed elimina un item dalla stessa tabella.

// 1. Specify item to add in the Forum table.
Table forum = Table.LoadTable(client, "Forum");
var forumBatchWrite = forum.CreateBatchWrite();

var forum1 = new Document();
forum1["Name"] = "Test BatchWrite Forum";
forum1["Threads"] = 0;
forumBatchWrite.AddDocumentToPut(forum1);


// 2a. Specify item to add in the Thread table.
Table thread = Table.LoadTable(client, "Thread");
var threadBatchWrite = thread.CreateBatchWrite();

var thread1 = new Document();
thread1["ForumName"] = "Amazon S3 forum";
thread1["Subject"] = "My sample question";
thread1["Message"] = "Message text";
thread1["KeywordTags"] = new List<string>{ "Amazon S3", "Bucket" };
threadBatchWrite.AddDocumentToPut(thread1);

// 2b. Specify item to delete from the Thread table.
threadBatchWrite.AddKeyToDelete("someForumName", "someSubject");

// 3. Create multi-table batch.
var superBatch = new MultiTableDocumentBatchWrite();
superBatch.AddBatch(forumBatchWrite);
superBatch.AddBatch(threadBatchWrite);

superBatch.Execute();