Amazon DynamoDB
开发人员指南 (API 版本 2012-08-10)
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

处理项目:.NET

您可以使用适用于 .NET 的 AWS 开发工具包低级 API,对表中的项目执行典型的创建、读取、更新和删除 (CRUD) 操作。以下是您使用 .NET 低级 API 执行数据 CRUD 操作时需要遵循的常见步骤:

  1. 创建 AmazonDynamoDBClient 类(客户端)的实例。

  2. 在相应的请求对象中,提供特定于操作的必需参数。

    例如,在上传项目时使用 PutItemRequest 请求数据元,在检索现有项目时使用 GetItemRequest 请求数据元。

    您可以使用请求数据元提供必需参数和可选参数。

  3. 通过传入您在之前步骤中创建的请求数据元,执行由客户端提供的相应方法。

    AmazonDynamoDBClient 客户端提供针对 CRUD 操作的 PutItemGetItemUpdateItemDeleteItem 方法。

放置项目

PutItem 方法能将项目上传至表。如果项目已存在,则会替换整个项目。

注意

如果您不想替换整个项目,而只希望更新特定属性,那么您可以使用 UpdateItem 方法。有关更多信息,请参阅更新项目

以下是使用低级 .NET 开发工具包 API 上传项目的步骤:

  1. 创建 AmazonDynamoDBClient 类的实例。

  2. 通过创建 PutItemRequest 类的实例,提供必需的参数。

    要放置项目,您必须提供表名称和项目。

  3. 通过提供您在之前步骤中创建的 PutItem 对象,执行 PutItemRequest 方法。

以下 C# 示例演示了上述步骤。该示例将一个项目上传到 ProductCatalog 表。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new PutItemRequest { TableName = tableName, Item = new Dictionary<string, AttributeValue>() { { "Id", new AttributeValue { N = "201" }}, { "Title", new AttributeValue { S = "Book 201 Title" }}, { "ISBN", new AttributeValue { S = "11-11-11-11" }}, { "Price", new AttributeValue { S = "20.00" }}, { "Authors", new AttributeValue { SS = new List<string>{"Author1", "Author2"} } } } }; client.PutItem(request);

在之前的示例中,您上传了一个包含 IdTitleISBNAuthors 属性的书本项目。请注意,Id 是一个数字类型属性,所有其他属性均为字符串类型。Authors 是 String 集。

指定可选参数

您还可以使用 PutItemRequest 对象提供可选参数(如以下 C# 示例所示)。该示例指定了以下可选参数:

  • ExpressionAttributeNamesExpressionAttributeValuesConditionExpression 指定只有在现有项目的 ISBN 属性为特定值时才替换该项目。

  • ReturnValues 参数,请求响应中的旧项目。

var request = new PutItemRequest { TableName = tableName, Item = new Dictionary<string, AttributeValue>() { { "Id", new AttributeValue { N = "104" }}, { "Title", new AttributeValue { S = "Book 104 Title" }}, { "ISBN", new AttributeValue { S = "444-4444444444" }}, { "Authors", new AttributeValue { SS = new List<string>{"Author3"}}} }, // Optional parameters. ExpressionAttributeNames = new Dictionary<string,string>() { {"#I", "ISBN"} }, ExpressionAttributeValues = new Dictionary<string, AttributeValue>() { {":isbn",new AttributeValue {S = "444-4444444444"}} }, ConditionExpression = "#I = :isbn" }; var response = client.PutItem(request);

有关更多信息,请参阅 PutItem

获取项目

GetItem 方法能检索项目。

注意

要检索多个项目,您可以使用 BatchGetItem 方法。有关更多信息,请参阅批量获取:获取多个项目

以下是使用低级 适用于 .NET 的 AWS 开发工具包 开发工具包 API 检索现有项目的步骤。

  1. 创建 AmazonDynamoDBClient 类的实例。

  2. 通过创建 GetItemRequest 类的实例,提供必需的参数。

    要获取项目,您必须提供表名称和项目主键。

  3. 通过提供您在之前步骤中创建的 GetItem 对象,执行 GetItemRequest 方法。

以下 C# 示例演示了上述步骤。以下示例从 ProductCatalog 表检索项目。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new GetItemRequest { TableName = tableName, Key = new Dictionary<string,AttributeValue>() { { "Id", new AttributeValue { N = "202" } } }, }; var response = client.GetItem(request); // Check the response. var result = response.GetItemResult; var attributeMap = result.Item; // Attribute list in the response.

指定可选参数

您还可以使用 GetItemRequest 对象提供可选参数,如以下 C# 示例所示。该示例指定了以下可选参数:

  • ProjectionExpression 参数,指定要检索的属性。

  • ConsistentRead 参数,执行强一致性读取。要了解有关读取一致性的更多信息,请参阅读取一致性

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new GetItemRequest { TableName = tableName, Key = new Dictionary<string,AttributeValue>() { { "Id", new AttributeValue { N = "202" } } }, // Optional parameters. ProjectionExpression = "Id, ISBN, Title, Authors", ConsistentRead = true }; var response = client.GetItem(request); // Check the response. var result = response.GetItemResult; var attributeMap = result.Item;

有关更多信息,请参阅 GetItem

更新项目

UpdateItem 方法可以更新现有的项目 (如果存在)。您可以使用 UpdateItem 操作更新现有属性值、添加新属性或从现有集合中删除属性。如果未找到具有特定主键的项目,此操作会添加一个新项目。

UpdateItem 操作遵循以下指导原则:

  • 如果项目不存在,UpdateItem 会添加一个新项目 (使用输入中指定的主键)。

  • 如果项目存在,则 UpdateItem 按照以下方式应用更新:

    • 使用更新中的值替换现有属性值。

    • 如果您在输入中提供的属性不存在,系统就会为项目添加新属性。

    • 如果输入的属性为空,系统会删除该属性 (如果存在)。

    • 如您为 Action 操作使用 ADD,则可以将值添加到现有集合(字符串或数字集),以及使用数学方法向现有数字属性值添加(使用正数)或从中减去(使用负数)一定值。

注意

PutItem 操作还可以执行更新。有关更多信息,请参阅放置项目。例如,如果您调用 PutItem 上传项目,并且主键存在,则 PutItem 操作会替换整个项目。如果现有项目中有属性,并且这些属性未在所放置的内容中指定,那么 PutItem 操作就会删除这些属性。但是,UpdateItem 只会更新指定的输入属性。该项目的任何其他现有属性都不会更改。

以下是使用低级 .NET API 更新现有项目的步骤:

  1. 创建 AmazonDynamoDBClient 类的实例。

  2. 通过创建 UpdateItemRequest 类的实例,提供必需的参数。

    这就是请求数据元,您在其中介绍所有更新 (例如,添加属性、更新现有属性或删除属性)。要删除现有属性,请指定具有空值的属性名称。

  3. 通过提供您在之前步骤中创建的 UpdateItem 对象,执行 UpdateItemRequest 方法。

以下 C# 代码示例演示了上述步骤。该示例更新 ProductCatalog 表中的书本项目。将新作者添加到 Authors 集合中,并删除现有 ISBN 属性。另外还降低了价格 (-1)。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new UpdateItemRequest { TableName = tableName, Key = new Dictionary<string,AttributeValue>() { { "Id", new AttributeValue { N = "202" } } }, ExpressionAttributeNames = new Dictionary<string,string>() { {"#A", "Authors"}, {"#P", "Price"}, {"#NA", "NewAttribute"}, {"#I", "ISBN"} }, ExpressionAttributeValues = new Dictionary<string, AttributeValue>() { {":auth",new AttributeValue { SS = {"Author YY","Author ZZ"}}}, {":p",new AttributeValue {N = "1"}}, {":newattr",new AttributeValue {S = "someValue"}}, }, // This expression does the following: // 1) Adds two new authors to the list // 2) Reduces the price // 3) Adds a new attribute to the item // 4) Removes the ISBN attribute from the item UpdateExpression = "ADD #A :auth SET #P = #P - :p, #NA = :newattr REMOVE #I" }; var response = client.UpdateItem(request);

指定可选参数

您还可以使用 UpdateItemRequest 对象提供可选参数,如以下 C# 示例所示。它指定以下可选参数:

  • ExpressionAttributeValuesConditionExpression,指定仅当现有价格为 20.00 时才能更新价格。

  • ReturnValues 参数,请求响应中的已更新项目。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new UpdateItemRequest { Key = new Dictionary<string,AttributeValue>() { { "Id", new AttributeValue { N = "202" } } }, // Update price only if the current price is 20.00. ExpressionAttributeNames = new Dictionary<string,string>() { {"#P", "Price"} }, ExpressionAttributeValues = new Dictionary<string, AttributeValue>() { {":newprice",new AttributeValue {N = "22"}}, {":currprice",new AttributeValue {N = "20"}} }, UpdateExpression = "SET #P = :newprice", ConditionExpression = "#P = :currprice", TableName = tableName, ReturnValues = "ALL_NEW" // Return all the attributes of the updated item. }; var response = client.UpdateItem(request);

有关更多信息,请参阅 UpdateItem

原子计数器

您可以使用 updateItem 实现原子计数器,并使用该计数器来递增或递减现有属性的值而不会干扰其他写入请求。要更新原子计数器,请使用 updateItem 操作,在 UpdateExpression 参数中使用类型属性 Number,将 ADD 作为 Action

以下示例演示了这一用法,将 Quantity 属性递增 1。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new UpdateItemRequest { Key = new Dictionary<string, AttributeValue>() { { "Id", new AttributeValue { N = "121" } } }, ExpressionAttributeNames = new Dictionary<string, string>() { {"#Q", "Quantity"} }, ExpressionAttributeValues = new Dictionary<string, AttributeValue>() { {":incr",new AttributeValue {N = "1"}} }, UpdateExpression = "SET #Q = #Q + :incr", TableName = tableName }; var response = client.UpdateItem(request);

删除项目

DeleteItem 方法能删除表中的项目。

以下是使用低级 .NET 开发工具包 API 删除项目的步骤。

  1. 创建 AmazonDynamoDBClient 类的实例。

  2. 通过创建 DeleteItemRequest 类的实例,提供必需的参数。

    要删除某个项目,您必须提供表名称和项目主键。

  3. 通过提供您在之前步骤中创建的 DeleteItem 对象,执行 DeleteItemRequest 方法。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string tableName = "ProductCatalog"; var request = new DeleteItemRequest { TableName = tableName, Key = new Dictionary<string,AttributeValue>() { { "Id", new AttributeValue { N = "201" } } }, }; var response = client.DeleteItem(request);

指定可选参数

您还可以使用 DeleteItemRequest 对象提供可选参数,如以下 C# 代码示例所示。它指定以下可选参数:

  • ExpressionAttributeValuesConditionExpression,指定仅当书本项目不在出版物中 (InPublication 属性值为 false) 时才能删除该项目。

  • ReturnValues 参数,请求响应中的已删除项目。

var request = new DeleteItemRequest { TableName = tableName, Key = new Dictionary<string,AttributeValue>() { { "Id", new AttributeValue { N = "201" } } }, // Optional parameters. ReturnValues = "ALL_OLD", ExpressionAttributeNames = new Dictionary<string, string>() { {"#IP", "InPublication"} }, ExpressionAttributeValues = new Dictionary<string, AttributeValue>() { {":inpub",new AttributeValue {BOOL = false}} }, ConditionExpression = "#IP = :inpub" }; var response = client.DeleteItem(request);

有关更多信息,请参阅 DeleteItem

批量写入:放置和删除多个项目

批量写入 是指批量放置和删除多个项目。BatchWriteItem 方法可让您通过一次 调用即可向一个或多个表中放置或从中删除多个项目。以下是使用低级 .NET 开发工具包 API 检索多个项目的步骤。

  1. 创建 AmazonDynamoDBClient 类的实例。

  2. 通过创建 BatchWriteItemRequest 类的实例,介绍所有放置和删除操作。

  3. 通过提供您在之前步骤中创建的 BatchWriteItem 对象,执行 BatchWriteItemRequest 方法。

  4. 处理响应。您应该检查一下响应是否返回未处理的请求项目。如果您达到预配置的吞吐量上限或遇到其他临时错误,可能会出现这种情况。此外,DynamoDB 还对可在请求中指定的请求大小和操作数进行限制。如果超出这些限制,DynamoDB 会拒绝请求。有关更多信息,请参阅BatchWriteItem

以下 C# 代码示例演示了上述步骤。示例创建 BatchWriteItemRequest 以执行以下写入操作:

  • 将项目放置到 Forum

  • Thread 表放置和删除项目。

然后,代码执行 BatchWriteItem 以执行批量操作。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string table1Name = "Forum"; string table2Name = "Thread"; var request = new BatchWriteItemRequest { RequestItems = new Dictionary<string, List<WriteRequest>> { { table1Name, new List<WriteRequest> { new WriteRequest { PutRequest = new PutRequest { Item = new Dictionary<string,AttributeValue> { { "Name", new AttributeValue { S = "Amazon S3 forum" } }, { "Threads", new AttributeValue { N = "0" }} } } } } } , { table2Name, new List<WriteRequest> { new WriteRequest { PutRequest = new PutRequest { Item = new Dictionary<string,AttributeValue> { { "ForumName", new AttributeValue { S = "Amazon S3 forum" } }, { "Subject", new AttributeValue { S = "My sample question" } }, { "Message", new AttributeValue { S = "Message Text." } }, { "KeywordTags", new AttributeValue { SS = new List<string> { "Amazon S3", "Bucket" } } } } } }, new WriteRequest { DeleteRequest = new DeleteRequest { Key = new Dictionary<string,AttributeValue>() { { "ForumName", new AttributeValue { S = "Some forum name" } }, { "Subject", new AttributeValue { S = "Some subject" } } } } } } } } }; response = client.BatchWriteItem(request);

要了解可工作的示例,请参阅示例:使用适用于 .NET 的 AWS 开发工具包低级别 API 的批量操作

批量获取:获取多个项目

BatchGetItem 方法可让您检索一个或多个表中的多个项目。

注意

要检索单个项目,您可以使用 GetItem 方法。

以下是使用低级适用于 .NET 的 AWS 开发工具包 API 检索多个项目的步骤。

  1. 创建 AmazonDynamoDBClient 类的实例。

  2. 通过创建 BatchGetItemRequest 类的实例,提供必需的参数。

    要检索多个项目,您必须提供表名称和主键值列表。

  3. 通过提供您在之前步骤中创建的 BatchGetItem 对象,执行 BatchGetItemRequest 方法。

  4. 处理响应。您应检查一下是否存在任何未处理的键,如果您达到预置的吞吐量上限或遇到某些其他临时错误,可能会出现这种情况。

以下 C# 代码示例演示了上述步骤。示例检索两个表(ForumThread)中的项目。请求指定 Forum 中的两个项目,以及 Thread 表中的三个项目。响应包括两个表中的项目。代码显示您如何处理响应。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string table1Name = "Forum"; string table2Name = "Thread"; var request = new BatchGetItemRequest { RequestItems = new Dictionary<string, KeysAndAttributes>() { { table1Name, new KeysAndAttributes { Keys = new List<Dictionary<string, AttributeValue>>() { new Dictionary<string, AttributeValue>() { { "Name", new AttributeValue { S = "DynamoDB" } } }, new Dictionary<string, AttributeValue>() { { "Name", new AttributeValue { S = "Amazon S3" } } } } } }, { table2Name, new KeysAndAttributes { Keys = new List<Dictionary<string, AttributeValue>>() { new Dictionary<string, AttributeValue>() { { "ForumName", new AttributeValue { S = "DynamoDB" } }, { "Subject", new AttributeValue { S = "DynamoDB Thread 1" } } }, new Dictionary<string, AttributeValue>() { { "ForumName", new AttributeValue { S = "DynamoDB" } }, { "Subject", new AttributeValue { S = "DynamoDB Thread 2" } } }, new Dictionary<string, AttributeValue>() { { "ForumName", new AttributeValue { S = "Amazon S3" } }, { "Subject", new AttributeValue { S = "Amazon S3 Thread 1" } } } } } } } }; var response = client.BatchGetItem(request); // Check the response. var result = response.BatchGetItemResult; var responses = result.Responses; // The attribute list in the response. var table1Results = responses[table1Name]; Console.WriteLine("Items in table {0}" + table1Name); foreach (var item1 in table1Results.Items) { PrintItem(item1); } var table2Results = responses[table2Name]; Console.WriteLine("Items in table {1}" + table2Name); foreach (var item2 in table2Results.Items) { PrintItem(item2); } // Any unprocessed keys? could happen if you exceed ProvisionedThroughput or some other error. Dictionary<string, KeysAndAttributes> unprocessedKeys = result.UnprocessedKeys; foreach (KeyValuePair<string, KeysAndAttributes> pair in unprocessedKeys) { Console.WriteLine(pair.Key, pair.Value); }

指定可选参数

您还可以使用 BatchGetItemRequest 对象提供可选参数,如以下 C# 代码示例所示。以下示例从 Forum 表检索两个项目。其中指定了以下可选参数:

  • ProjectionExpression 参数,指定要检索的属性。

AmazonDynamoDBClient client = new AmazonDynamoDBClient(); string table1Name = "Forum"; var request = new BatchGetItemRequest { RequestItems = new Dictionary<string, KeysAndAttributes>() { { table1Name, new KeysAndAttributes { Keys = new List<Dictionary<string, AttributeValue>>() { new Dictionary<string, AttributeValue>() { { "Name", new AttributeValue { S = "DynamoDB" } } }, new Dictionary<string, AttributeValue>() { { "Name", new AttributeValue { S = "Amazon S3" } } } } }, // Optional - name of an attribute to retrieve. ProjectionExpression = "Title" } } }; var response = client.BatchGetItem(request);

有关更多信息,请参阅 BatchGetItem