Arbeiten mit Elementen in DynamoDB mithilfe des AWS SDK for .NET-Dokumentmodells

Die folgenden Codebeispiele zeigen, wie Sie eine Vielzahl von Operationen mit dem AWS SDK for .NET-Dokumentmodell durchführen können. Sie können diese Beispiele verwenden, um CRUD-, Batch- und Transaktionsoperationen durchzuführen.

Um Datenoperationen mit dem Dokumentmodell durchzuführen, müssen Sie zunächst die Table.LoadTable-Methode aufrufen, die eine Instance der Table-Klasse erstellt, diese wiederum stellt eine bestimmte Tabelle dar. Das folgende C#-Beispiel erstellt ein Table-Objekt, das die Tabelle ProductCatalog in Amazon DynamoDB darstellt.

Beispiel

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

Anmerkung

Im Allgemeinen nutzen Sie die LoadTable-Methode einmal zu Beginn der Anwendung, da sie einen DescribeTable-Aufruf durchführt, welcher der Umlaufzeit auf DynamoDB hinzugefügt wird.

Sie können dann das Table-Objekt nutzen, um verschiedene Datenoperationen durchzuführen. Jeder dieser Datenvorgänge hat zwei Überlastungsarten. Eine, die die minimal erforderlichen Parameter verwendet, und eine andere, die auch vorgangsspezifische optionale Konfigurationsinformationen verwendet. Wenn Sie beispielsweise ein Element abrufen, müssen Sie den Primärschlüsselwert der Tabelle angeben. In solchen Fällen können Sie die folgende GetItem-Überlastung verwenden:

Beispiel

// 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);

Sie können auch optionale Parameter an diese Methoden weiterleiten. Das vorangehende GetItem gibt zum Beispiel das gesamte Element einschließlich aller Attribute zurück. Sie können optional eine Liste der abzurufenden Attribute angeben. In diesem Fall nutzen Sie die folgende GetItem-Überlastung, die den vorgangsspezifischen Konfigurationsobjektparameter aufnimmt:

Beispiel

// 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);

Sie können das Konfigurationsobjekt verwenden, um mehrere optionale Parameter, wie etwa das Anfordern einer bestimmten Attributliste oder das Angeben der Seitengröße (Anzahl der Elemente pro Seite), anzugeben. Jede Datenoperationsmethode verfügt über eigene Konfigurationsklassen. Beispielsweise können Sie die GetItemOperationConfig-Klasse verwenden, um Optionen für die GetItem-Operation bereitzustellen. Sie können die PutItemOperationConfig-Klasse verwenden, um Optionen für die PutItem-Operation bereitzustellen.

In den folgenden Abschnitten werden alle Datenoperationen beschrieben, die von der Table-Klasse unterstützt werden.

Einfügen eines Elements – Table.PutItem method

Die PutItem-Methode lädt die Eingabe-Document-Instance in die Tabelle hoch. Wenn ein Element, das über einen Primärschlüssel verfügt, der in der Eingabe Document angegeben wird, un der Tabelle existiert, dann ersetzt die PutItem-Operation das gesamte vorhandene Element. Das neue Element ist identisch mit dem Document-Objekt, das Sie der PutItem-Methode zur Verfügung gestellt haben. Wenn das ursprüngliche Element zusätzliche Attribute hatte, sind diese im neuen Element nicht mehr vorhanden.

Es folgen die Schritte zum Setzen eines neuen Elements in die Tabelle mithilfe des AWS SDK for .NET-Dokumentmodells.

1. Führen Sie die Table.LoadTable-Methode aus, die den Tabellennamen bereitstellt, in den Sie ein Element ablegen möchten.

2. Erstellen Sie ein Document-Objekt, das über eine Liste von Attributen und deren Werte verfügt.

3. Führen Sie Table.PutItem aus, indem Sie die Document-Instance als Parameter bereitstellen.

Im folgenden C#-Codebeispiel werden die vorherigen Aufgaben veranschaulicht. Das Beispiel lädt ein Element in die ProductCatalog-Tabelle hoch.

Beispiel

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);

Im vorherigen Beispiel erstellt die Document Instance ein Element mit den Null Attributen Number, String, Boolean, und String Set. (Null wird verwendet, um anzugeben, dass der QuantityOnHand für dieses Produkt unbekannt ist.) Verwenden Sie für Boolean und Null die Konstruktormethoden DynamoDBBool und DynamoDBNull.

In DynamoDB können die Datentypen List und Map aus anderen Datentypen bestehende Elemente enthalten. Hier sehen Sie, wie Sie diese Datentypen der Dokumentmodell-API zuordnen:.

• List – nutzen Sie den DynamoDBList-Konstruktor.

• Map – nutzen Sie den Document-Konstruktor.

Sie können das vorherige Beispiel ändern, um dem Element ein List-Attribut hinzuzufügen. Um dies zu tun, verwenden Sie einen DynamoDBList-Konstruktor, wie im folgenden Codebeispiel gezeigt:

Beispiel

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);

Um dem Buch ein Map-Attribut hinzuzufügen, definieren Sie einen anderen Document. Der folgende Beispielcode veranschaulicht diese Vorgehensweise.

Beispiel

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);

Diese Beispiele basieren auf dem Element, das in Angeben von Elementattributen bei der Verwendung von Ausdrücken dargestellt wird. Das Dokumentmodell ermöglicht Ihnen das Erstellen von komplexen verschachtelten Attributen, wie das in dieser Fallstudie dargestellte ProductReviews-Attribut.

Angeben eines optionalen Parameters

Sie können optionale Parameter für die PutItem-Operation konfigurieren, indem Sie den Parameter PutItemOperationConfig hinzufügen. Eine vollständige Liste der optionalen Parameter finden Sie unter PutItem. Das folgende C#-Codebeispiel setzt ein Element in die Tabelle ProductCatalog. Folgende optionale Parameter werden angegeben:

• Der Parameter ConditionalExpression, um dies zu einer bedingten Ablegeanforderung zu machen. Das Beispiel erstellt einen Ausdruck, der festlegt, dass das ISBN-Attribut über einen bestimmten Wert verfügen muss, der in dem zu ersetzenden Element vorhanden ist.

Beispiel

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);

Abrufen eines Elements – Tabelle.GetItem

Die GetItem-Operation ruft ein Element als Document-Instance ab. Sie müssen, wie im folgenden C#-Codebeispiel, den Primärschlüssel des wiederherzustellenden Elements angeben:

Beispiel

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

Die GetItem-Operation gibt alle Attribute des Elements zurück und führt standardmäßig einen Eventually Consistent-Lesevorgang durch (siehe Lesekonsistenz).

Angeben eines optionalen Parameters

Sie können zusätzliche Optionen für die GetItem-Operation konfigurieren, indem Sie den Parameter GetItemOperationConfig hinzufügen. Eine vollständige Liste der optionalen Parameter finden Sie unter GetItem. Das folgende C#-Codebeispiel ruft ein Objekt aus der ProductCatalog-Tabelle ab. Die GetItemOperationConfig wird angegeben, um die folgenden optionalen Parameter bereitzustellen:

• Der Parameter AttributesToGet, um nur die angegebenen Attribute abzurufen.

• Der Parameter ConsistentRead, um die neuesten Werte für alle angegebenen Attribute anzufordern. Weitere Informationen zur Datenkonsistenz finden Sie unter Lesekonsistenz.

Beispiel

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);

Wenn Sie ein Element mithilfe der Dokumentmodell-API abrufen, haben Sie Zugriff auf individuelle Elemente im Document-Objekt, wie im folgenden Beispiel gezeigt.

Beispiel

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();

Für Attribute des Typs List oder Map ordnen Sie diese Attribute so der Dokumentmodell-API zu:

• List – AsDynamoDBList-Methode verwenden.

• Map – AsDocument-Methode verwenden.

Das folgende Codebeispiel zeigt, wie ein List (RelatedItems) und ein Map (Bilder) aus dem Document Objekt abgerufen werden:

Beispiel

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

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

Löschen eines Elements – Tabelle.DeleteItem

Die DeleteItem-Operation löscht ein Element aus einer Tabelle. Sie können den Primärschlüssel des Elements als Parameter übergeben. Oder wenn Sie bereits ein Element gelesen haben und über das entsprechende Document-Objekt verfügeb, können Sie dieses als Parameter an die DeleteItem-Methode übergeben, wie im folgenden C#-Beispiel gezeigt.

Beispiel

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)

Angeben eines optionalen Parameters

Sie können zusätzliche Optionen für die Delete-Operation konfigurieren, indem Sie den Parameter DeleteItemOperationConfig hinzufügen. Eine vollständige Liste der optionalen Parameter finden Sie unter DeleteTable. Das folgende C#-Codebeispiel gibt die beiden folgenden optionalen Parameter an:

• Den Parameter ConditionalExpression, um sicherzustellen, dass der Buchartikel, der gerade gelöscht wird, einen bestimmten Wert für das ISBN-Attribut hat.

• Den Parameter ReturnValues, um anzufordern, dass die Delete-Methode das Element zurückgibt, das sie gelöscht hat.

Beispiel

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);

Aktualisieren eines Elements – Tabelle.UpdateItem

Die Operation UpdateItem aktualisiert ein bestehendes Element, wenn es vorhanden ist. Wenn das Element, das den bestimmten Primärschlüssel besitzt, nicht gefunden wird, fügt die UpdateItem-Operation ein neues Element hinzu.

Sie können die UpdateItem-Operation verwenden, um vorhandene Attributwerte zu aktualisieren, neue Attribute der vorhandenen Sammlung hinzuzufügen oder Attribute aus der vorhandenen Sammlung zu löschen. Sie stellen diese Aktualisierungen bereit, indem Sie eine Document-Instance erstellen, die die Aktualisierungen beschreibt, die Sie ausführen möchten.

Die UpdateItem-Aktion verwendet die folgenden Leitlinien:

• Wenn das Element nicht vorhanden ist, fügt UpdateItem ein neues Element hinzu, indem der in der Eingabe angegebene Primärschlüssel genutzt wird.

• Wenn das Element vorhanden ist, wendet UpdateItem die Aktualisierung wie folgt an:

  • Ersetzt die vorhandenen Attributwerte mit den Werten in der Aktualisierung.

  • Wenn ein Attribut, das Sie in der Eingabe angegeben haben, nicht vorhanden ist, fügt es dem Element ein neues Attribut hinzu.

  • Wenn der Attributwert Null ist, löscht es die Attribute, sofern es vorhanden ist.

Anmerkung

Diese UpdateItem Operation der mittleren Ebene unterstützt nicht die Add Aktion (siehe UpdateItem), die von der zugrunde liegenden DynamoDB-Operation unterstützt wird.

Anmerkung

Die PutItem-Operation (Einfügen eines Elements – Table.PutItem method) kann auch eine Aktualisierung durchführen. Wenn Sie PutItem aufrufen, um ein Element hochzuladen, und der Primärschlüssel vorhanden ist, ersetzt die PutItem-Operation das gesamte Element. Wenn Attribute in dem vorhandenen Element zur Verfügung stehen und diese nicht im Document angegeben werden, das gerade abgelegt wird, löscht die PutItem-Operation diese Attribute. Jedoch aktualisiert UpdateItem lediglich die angegebenen Eingabeattribute. Alle anderen vorhandenen Attribute dieses Elements bleiben unverändert.

Im Folgenden werden die Schritte zum Aktualisieren eines Elements mithilfe des AWS SDK for .NET-Dokumentmodells erörtert.

1. Führen Sie die Table.LoadTable-Methode durch das Bereitstellen des Namens der Tabelle aus, in der Sie eine Aktualisierungsoperation durchführen möchten.

2. Erstellen Sie eine Document-Instance, indem Sie alle Aktualisierungen bereitstellen, die Sie durchführen möchten.

   Um ein vorhandenes Attribut zu löschen, geben Sie den Attributwert als Null an.

3. Rufen Sie die Table.UpdateItem-Methode auf und geben die Document-Instance als Eingabeparameter an.

   Sie müssen den Primärschlüssel entweder in der Document-Instance oder ausdrücklich als Parameter angeben.

Im folgenden C#-Codebeispiel werden die vorherigen Aufgaben veranschaulicht. Das Codebeispiel aktualisiert ein Element in der Book-Tabelle. Die UpdateItem-Operation aktualisiert das vorhandene Authors-Attribut, löscht das PageCount-Attribut und fügt ein neues XYZ-Attribut hinzu. Die Document-Instance beinhaltet den Primärschlüssel des zu aktualisierenden Buchs.

Beispiel

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);

Angeben eines optionalen Parameters

Sie können zusätzliche Optionen für die UpdateItem-Operation konfigurieren, indem Sie den Parameter UpdateItemOperationConfig hinzufügen. Eine vollständige Liste der optionalen Parameter finden Sie unter UpdateItem.

Das folgende C#-Codebeispiel aktualisiert einen Buchartikelpreis auf 25. Es gibt die folgenden zwei optionalen Parameter an:

• Den Parameter ConditionalExpression, der das Price-Attribut mit dem Wert 20 angibt, von dem Sie erwarten, dass er vorhanden ist.

• Den Parameter ReturnValues für die Anforderung der UpdateItem-Methode, um das Element zurückzugeben, das aktualisiert wird.

Beispiel

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);

Batch Write – Einfügen und Löschen mehrerer Elemente

Batch Write bezieht sich auf das Einfügen und Löschen mehrerer Elemente in einem Batch. Die Operation ermöglicht Ihnen, anhand eine einzigen Aufrufs, das Ablegen und Löschen von mehreren Elementen einer oder mehrerer Tabellen. Führen Sie Folgendes aus, um mehrere Elemente einer Tabelle mithilfe der AWS SDK for .NET-Dokumentmodell-API abzulegen oder zu löschen.

1. Durch das Ausführen der Table-Methode, wird ein Table.LoadTable-Objekt erstellt, indem Sie den Namen der Tabelle, in der Sie die Batchoperation durchführen möchten, angeben.

2. Führen Sie die createBatchWrite-Methode auf der Tabellen-Instance, die Sie im vorangegangenen Schritt erstellt haben, aus und erstellen Sie das DocumentBatchWrite-Objekt.

3. Verwenden Sie DocumentBatchWrite-Objektmethoden für das Angeben von Dokumenten, die Sie hochladen oder löschen möchten.

4. Rufen Sie die DocumentBatchWrite.Execute-Methode auf, um die Batchoperation auszuführen.

   Wenn Sie die Dokumentmodell-API nutzen, können Sie eine beliebige Anzahl von Operationen in einem Batch angeben. Beachten Sie jedoch, dass DynamoDB die Anzahl der Operationen in einem Batch und die Gesamtgröße des Batches in einer Batchoperation begrenzt. Weitere Informationen zu den spezifischen Grenzwerten finden Sie unter BatchWriteItem. Wenn die Dokumentmodell-API erkennt, dass die Batchschreibanforderung die Menge der erlaubten Schreibanforderungen überschritten hat oder die HTTP-Nutzlastgröße eines Batches über dem Grenzwert von BatchWriteItem liegt, zerteilt sie den Batch in mehrere kleinere Batches. Wenn zudem eine Antwort auf einen BatchWrite-Vorgang unverarbeitete Elemente zurückgibt, sendet die Dokumentmodell-API automatisch eine andere Batchanforderung mit diesen unverarbeiteten Elementen.

Im folgenden C#-Codebeispiel werden die vorherigen Schritte veranschaulicht. Das Beispiel verwendet Batchschreiboperationen zum Durchführen von zwei Schreibvorgängen: Hochladen eines Buchartikels und Löschen eines anderen.

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();

Ein funktionierendes Beispiel finden Sie unter Beispiel: Batchoperationen mit der AWS SDK for .NET-Dokumentmodell-API.

Sie können die batchWrite-Operation zum Durchführen von Ablege- und Löschoperationen auf mehreren Tabellen durchführen. Führen Sie Folgendes aus, um mehrere Elemente aus mehreren Tabellen mithilfe des AWS SDK for .NET-Dokumentmodells abzulegen oder zu löschen.

1. Sie erstellen eine DocumentBatchWrite-Instance für jede Tabelle, in der Sie mehrere Elemente, wie im vorherigen Vorgang beschrieben, ablegen oder löschen möchten.

2. Erstellen Sie eine Instance des MultiTableDocumentBatchWrite und fügen dieser das individuelle DocumentBatchWrite-Objekt hinzu.

3. Führen Sie die MultiTableDocumentBatchWrite.Execute-Methode aus.

Im folgenden C#-Codebeispiel werden die vorherigen Schritte veranschaulicht. Das Beispiel verwendet Batchschreiboperationen für die Durchführung der folgenden Schreiboperationen:

• Legen Sie ein neues Element in das Forum-Tabellenelement ab

• Legen Sie ein Element in die Thread-Tabelle ab, und löschen Sie ein Element aus derselben Tabelle.

// 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();