使用 Amazon SDK for .NET 文档模型处理 DynamoDB 中的项目 - Amazon DynamoDB
放置项目 – Table.PutItem 方法指定可选参数
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

使用 Amazon SDK for .NET 文档模型处理 DynamoDB 中的项目

要使用文档模型执行数据操作，您必须首先调用 Table.LoadTable 方法，它会创建 Table 类的实例来代表特定的表。以下 C# 示例创建的 Table 对象表示 Amazon DynamoDB 中的 ProductCatalog 表。

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

一般情况下，您只需在应用程序开头使用一次 LoadTable 方法，因为它会发出 DescribeTable 调用，从而建立起与 DynamoDB 之间的往返行程。

然后，您可以使用 Table 对象执行各种数据操作。每个数据操作都有两类重载，一类接收最少数量的必需参数，另一类接收操作特有的可选配置信息。例如，要检索项目，您必须提供表的主键值，这个时候，您可以使用以下 GetItem 重载。

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

您还可以向这些方法传递可选参数。例如，前面所述的 GetItem 会返回整个项目并包括其所有属性。您可以选择指定要检索的一系列属性。在这一情况下，您可以使用以下 GetItem 重载，它会接收操作特有的配置对象参数。

例 

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

您可以使用配置数据元指定多个可选参数，例如请求特定属性列表或指定页面大小（每页的项目数）。每个数据操作方法都有自己的配置类。例如，您可以使用 GetItemOperationConfig 类为 GetItem 操作提供选项。您可以使用 PutItemOperationConfig 类为 PutItem 操作提供可选参数。

以下部分讨论 Table 类支持的每个数据操作。

放置项目 – Table.PutItem 方法

PutItem 方法将输入 Document 实例上传到表中。如果输入 Document 中指定的项目主键在表中已存在，PutItem 操作会替换整个现有项目。新项目与您向 PutItem 方法提供的 Document 对象相同。如果您的原始项目有额外属性，新项目中将不再有这些属性。

下面是使用Amazon SDK for .NET文档模型将新项目放置到表中的步骤。

  1. 执行 Table.LoadTable 方法，提供作为项目放置对象的表的名称。

  2. 创建包含一系列属性名称和值的 Document 数据元。

  3. 以参数形式提供 Document 实例，执行 Table.PutItem。

以下 C# 代码示例演示了上述任务。该示例将一个项目上传到 ProductCatalog 表。

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

在前面的示例中，Document 实例创建的项目具有 Number、String、String Set、Boolean 和 Null 属性。（Null 用于表示该产品的 QuantityOnHand 未知。） 对于 Boolean 和 Null，使用构造函数方法 DynamoDBBool 和 DynamoDBNull。

在 DynamoDB 中，List 和 Map 数据类型可以包含由其他数据类型构成的元素。下面介绍这些数据类型如何映射到文档模型 API：

  • List — 使用 DynamoDBList 构造函数。

  • Map — 使用 Document 构造函数。

您可以修改上述示例以便将 List 属性添加到项目。为此，请按照以下代码示例所示使用 DynamoDBList 构造函数。

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

要将 Map 属性添加到图书，可以定义另一个 Document。以下代码示例说明了如何执行该操作。

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

这些示例基于使用表达式时指定项目属性中显示的项目。使用文档模型可以创建复杂的嵌套属性，例如案例研究中显示的 ProductReviews 属性。

指定可选参数

您可以通过添加 PutItem 参数来配置 PutItemOperationConfig 操作的可选参数。要获得可选参数的完整列表，请参阅 PutItem。以下 C# 代码示例在 ProductCatalog 表中放置一个项目。其中指定了以下可选参数：

  • ConditionalExpression 参数，让此请求成为有条件放置请求。本示例创建一个表达式，该表达式指定 ISBN 属性必须具有特定的值，该值需在要替换的项目中存在。

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