Utilisation des éléments dans DynamoDB à l'aide du modèle de document AWS SDK for .NET

Les exemples de code suivants montrent comment effectuer différentes opérations avec le modèle de document AWS SDK for .NET . Vous pouvez utiliser ces exemples pour effectuer des opérations CRUD, par lot et de transaction.

Pour effectuer les opérations de données à l'aide du modèle de document, vous devez d'abord appeler la méthode Table.LoadTable, qui crée une instance de la classe Table qui représente une table spécifique. L'extrait de code C# suivant crée un objet Table qui représente la table ProductCatalog dans Amazon DynamoDB.

Exemple

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

Note

En général, vous utilisez la méthode LoadTable une fois au début de votre application, car elle effectue un appel DescribeTable qui s'ajoute à l'aller-retour vers DynamoDB.

Vous pouvez ensuite utiliser l'objet Table pour exécuter différentes opérations de données. Chaque opération de données possède deux types de surcharge : un qui prend les paramètres requis minimum et un autre qui prend les informations facultatives de configuration propres à l'opération. Par exemple, pour récupérer un élément, vous devez fournir la valeur de clé primaire de la table, auquel cas, vous pouvez utiliser la surcharge GetItem suivante :

Exemple

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

Vous pouvez aussi passer des paramètres facultatifs à ces méthodes. Par exemple, le GetItem précédent retourne l'élément entier, y compris tous ses attributs. Vous pouvez spécifier le cas échéant une liste d'attributs à extraire. Dans ce cas, vous utilisez la surcharge GetItem suivante qui accepte le paramètre d'objet de configuration spécifique à l'opération :

Exemple

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

Vous pouvez utiliser l'objet de configuration pour spécifier plusieurs paramètres facultatifs, tels que la demande d'une liste spécifique d'attributs ou la spécification de la taille de la page (nombre d'éléments par page). Chaque méthode d'opération de données a sa propre classe de configuration. Par exemple, vous pouvez utiliser la classe GetItemOperationConfig afin de fournir des options pour l’opération GetItem. Vous pouvez utiliser la classe PutItemOperationConfig afin de fournir des paramètres facultatifs pour l’opération PutItem.

Les sections suivantes décrivent chacune des opérations de données qui sont prises en charge par la classe Table.

Mettre un objet - Table. PutItem méthode

La méthode PutItem charge l'instance Document en entrée sur la table. Si un élément ayant une clé primaire spécifiée dans l'instance Document en entrée existe dans la table, l'opération PutItem remplace la totalité de l'élément existant. Le nouvel élément est identique à l'objet Document que vous fournissez à la méthode PutItem. Si votre élément d'origine a des attributs supplémentaires, ceux-ci ne sont plus présents dans le nouvel élément.

Voici les étapes à suivre pour insérer un nouvel élément dans une table à l'aide du modèle de document  AWS SDK for .NET .

1. Exécutez la méthode Table.LoadTable qui fournit le nom de la table dans laquelle vous voulez insérer un élément.

2. Créez un objet Document qui a une liste de noms d'attribut et de leurs valeurs.

3. Exécutez Table.PutItem en fournissant l'instance Document comme paramètre.

L'exemple de code C# suivant présente les tâches précédentes. L'exemple charge un élément dans la table ProductCatalog.

Exemple

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

Dans l'exemple précédent, l'Documentinstance crée un élément qui possède des Null attributs Number StringString Set,Boolean,, et. (Nullest utilisé pour indiquer que la QuantityOnmain de ce produit est inconnue.) Pour Boolean et Null, utilisez les méthodes constructeur DynamoDBBool et DynamoDBNull.

Dans DynamoDB, les types de données List et Map peuvent contenir des éléments composés d'autres types de données. Voici comment mapper ces types de données à l'API du modèle de document :

• List (liste) – Utilisez le constructeur DynamoDBList.

• Map (mappage) – Utilisez le constructeur Document.

Vous pouvez modifier l'exemple précédent pour ajouter un attribut List à l'élément. Pour ce faire, utilisez un constructeur DynamoDBList, comme illustré dans l'exemple de code suivant :

Exemple

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

Pour ajouter un attribut Map à l'élément « book », vous définissez un autre Document. L'exemple de code suivant montre comment procéder.

Exemple

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

Ces exemples sont basés sur l'élément affiché dans Spécification d'attributs d'élément lors de l'utilisation d'expressions. Le modèle de document vous permet de créer des attributs imbriqués, tels que l'attribut ProductReviews illustré dans l'étude de cas.

Spécification de paramètres facultatifs

Vous pouvez configurer des paramètres facultatifs pour l'opération PutItem en ajoutant le paramètre PutItemOperationConfig. Pour obtenir la liste complète des paramètres facultatifs, voir PutItem. L'exemple de code C# suivant insère un élément dans la table ProductCatalog. Il spécifie le paramètre facultatif suivant :

• Le paramètre ConditionalExpression pour en faire une demande d'insertion conditionnelle. L'exemple crée une expression spécifiant que l'attribut ISBN doit avoir une valeur spécifique, présente dans l'élément que vous remplacez.

Exemple

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

Obtenir un objet - Tableau. GetItem

L'opération GetItem récupère un élément comme instance Document. Vous devez fournir la clé primaire de l'élément que vous souhaitez récupérer, comme illustré dans l'extrait de code C# suivant :

Exemple

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

L'opération GetItem retourne tous les attributs de l'élément et effectue une lecture cohérente à terme (eventually consistent) (voir Cohérence en lecture) par défaut.

Spécification de paramètres facultatifs

Vous pouvez configurer des options supplémentaires pour l'opération GetItem en ajoutant le paramètre GetItemOperationConfig. Pour obtenir la liste complète des paramètres facultatifs, voir GetItem. L'exemple de code C# suivant extrait trois éléments de la table ProductCatalog. Il spécifie le paramètre GetItemOperationConfig pour fournir les paramètres facultatifs suivants :

• Le paramètre AttributesToGet pour récupérer uniquement les attributs spécifiés.

• Le paramètre ConsistentRead pour demander les dernières valeurs de tous les attributs spécifiés. Pour en savoir plus sur la cohérence des données, consultez Cohérence en lecture.

Exemple

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

Lorsque vous récupérez un élément à l'aide de l'API de modèle de document, vous pouvez accéder aux éléments individuels de l'objet Document retourné, comme illustré dans l'exemple suivant.

Exemple

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

Pour les attributs qui sont de type List ou Map, voici comment mapper ces attributs à l'API de modèle de document :

• List – Utilisez la méthode AsDynamoDBList.

• Map – Utilisez la méthode AsDocument.

L'exemple de code suivant montre comment récupérer a List (RelatedItems) et a Map (Pictures) de l'Documentobjet :

Exemple

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

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

Supprimer un élément - Tableau. DeleteItem

L'opération DeleteItem supprime un élément d'une table. Vous pouvez passer la clé primaire de l'élément comme paramètre. Sinon, si vous avez déjà lu un élément et que vous avez l'objet Document correspondant, vous pouvez le passer comme paramètre pour la méthode DeleteItem, comme illustré dans l'exemple de code C# suivant.

Exemple

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)

Spécification de paramètres facultatifs

Vous pouvez configurer des options supplémentaires pour l'opération Delete en ajoutant le paramètre DeleteItemOperationConfig. Pour obtenir la liste complète des paramètres facultatifs, voir DeleteTable. L'exemple de code C# suivant spécifie les deux paramètres facultatifs suivants :

• Le paramètre ConditionalExpression pour s'assurer que l'élément « book » en cours de suppression possède une valeur spécifique pour l'attribut ISBN.

• Le paramètre ReturnValuespour demander que la méthode Delete retourne l'élément qu'elle a supprimé.

Exemple

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

Mettre à jour un élément - Tableau. UpdateItem

L'opération UpdateItem met à jour un élément existant s'il est présent. Si l'élément qui possède la clé primaire spécifiée est introuvable, l'opération UpdateItem ajoute un nouvel élément.

Vous pouvez utiliser l'opération UpdateItem pour mettre à jour les valeurs d'attribut existantes, ajouter de nouveaux attributs à la collection existante ou supprimer des attributs de la collection existante. Vous fournissez ces mises à jour en créant une instance Document qui décrit les mises à jour que vous souhaitez effectuer.

L'action UpdateItem utilise les directives suivantes :

• Si l'élément n'existe pas, UpdateItem ajoute un nouvel élément à l'aide de la clé primaire spécifiée dans l'entrée.

• Si l'élément existe, UpdateItem applique les mises à jour comme suit :

  • Remplace les valeurs d'attribut existantes par les valeurs de la mise à jour.

  • Si un attribut que vous fournissez en entrée n'existe pas, un nouvel attribut est ajouté à l'élément.

  • Si l'attribut en entrée a la valeur null, il est supprimé s'il est présent.

Note

Cette UpdateItem opération de niveau intermédiaire ne prend pas en charge l'Addaction (voir UpdateItem) prise en charge par l'opération DynamoDB sous-jacente.

Note

L'opération PutItem (Mettre un objet - Table. PutItem méthode) peut également exécuter une mise à jour. Si vous appelez PutItem pour charger un élément et que la clé primaire existe, l'opération PutItem remplace la totalité de l'élément. S'il existe des attributs dans l'élément existant et qu'ils ne sont pas spécifiés dans l'élément Document en cours d'insertion, l'opération PutItem supprime ces attributs. Toutefois, UpdateItem ne met à jour que les attributs spécifiés en entrée. Tous les autres attributs de cet élément demeurent inchangés.

Les étapes à suivre pour mettre à jour un élément à l'aide du modèle de AWS SDK for .NET document sont les suivantes :

1. Exécutez la méthode Table.LoadTable en fournissant le nom de la table dans laquelle vous souhaitez effectuer l'opération de mise à jour.

2. Créez une instance Document en fournissant toutes les mises à jour que vous voulez effectuer.

   Pour supprimer un attribut existant, spécifiez la valeur d'attribut comme null.

3. Appelez la méthode Table.UpdateItem et fournissez l'instance Document comme paramètre d'entrée.

   Vous devez fournir la clé primaire dans l'instance Document ou explicitement comme paramètre.

L'exemple de code C# suivant présente les tâches précédentes. L'exemple de code met à jour un élément de la table Book. L'opération UpdateItem met à jour l'attribut Authors existant, supprime l'attribut PageCount et ajoute un nouvel attribut XYZ. L'instance Document inclut la clé primaire de l'élément « book » à mettre à jour.

Exemple

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

Spécification de paramètres facultatifs

Vous pouvez configurer des options supplémentaires pour l'opération UpdateItem en ajoutant le paramètre UpdateItemOperationConfig. Pour obtenir la liste complète des paramètres facultatifs, voir UpdateItem.

L'exemple de code C# suivant met à jour le prix d'un élément « book » avec la valeur 25. Il spécifie les deux paramètres facultatifs suivants :

• Le paramètre ConditionalExpression qui identifie l'attribut Price avec la valeur 20 à laquelle vous vous attendiez.

• Le paramètre ReturnValues pour demander que l'opération UpdateItem retourne l'élément qui est mis à jour.

Exemple

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

Écriture par lots – Insertion et suppression de plusieurs éléments

L'écriture par lots fait référence à l'insertion et la suppression de plusieurs éléments dans un lot. L'opération vous permet d'insérer et de supprimer plusieurs éléments d'une ou de plusieurs tables en un seul appel. Voici les étapes à suivre pour placer ou supprimer plusieurs éléments d'un tableau à l'aide de l'API du modèle de AWS SDK for .NET document.

1. Créez un objet Table en exécutant la méthode Table.LoadTable en fournissant le nom de la table dans laquelle vous souhaitez effectuer l'opération de traitement par lots.

2. Exécutez la méthode createBatchWrite sur l'instance de table que vous avez créée à l'étape précédente, puis créez un objet DocumentBatchWrite.

3. Utilisez les méthodes de l'objet DocumentBatchWrite pour spécifier les documents que vous souhaitez charger ou supprimer.

4. Appelez la méthode DocumentBatchWrite.Execute pour exécuter l'opération par lot.

   Lorsque vous utilisez l'API de modèle de document, vous pouvez spécifier un nombre quelconque d'opérations dans un lot. Cependant, DynamoDB limite le nombre d'opérations d'un lot et la taille totale du lot dans une opération par lot. Pour plus d'informations sur les limites spécifiques, consultez la section BatchWriteArticle. Si l'API de modèle de document détecte que votre demande d'écriture par lots a dépassé le nombre de requêtes d'écriture autorisé ou que la taille de charge utile HTTP d'un traitement par lots a dépassé la limite autorisée par BatchWriteItem, elle scinde le lot en plusieurs lots plus petits. En outre, si une réponse à une écriture par lot retourne des éléments non traités, l'API de modèle de document envoie automatiquement une autre requête de lots avec les éléments non traités.

L'exemple de code C# suivant présente les étapes précédentes. L'exemple utilise l'opération d'écriture par lots afin d'effectuer deux écritures ; charger un élément « book » et supprimer un autre élément « book ».

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

Pour obtenir un exemple pratique, consultez Exemple : opérations par lots à l'aide de l'API du modèle de AWS SDK for .NET document.

Vous pouvez utiliser l'opération batchWrite pour effectuer des opérations d'insertion et de suppression dans plusieurs tables. Voici les étapes à suivre pour placer ou supprimer plusieurs éléments de plusieurs tables à l'aide du modèle de AWS SDK for .NET document.

1. Vous créez une instance DocumentBatchWrite pour chaque table dans laquelle vous voulez insérer ou supprimer plusieurs éléments, comme décrit dans la procédure précédente.

2. Créez une instance de l'élément MultiTableDocumentBatchWrite et ajoutez-y les objets DocumentBatchWrite.

3. Exécutez la méthode MultiTableDocumentBatchWrite.Execute.

L'exemple de code C# suivant présente les étapes précédentes. L'exemple de code utilise l'opération d'écriture par lots pour effectuer les opérations d'écriture suivantes :

• Placer un nouvel élément dans l'élément de table Forum.

• Placer un élément dans la table Thread et supprimer un élément de la même table.

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