Amazon DynamoDB
开发人员指南 (API Version 2012-08-10)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。点 击 Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

DynamoDBContext 类

DynamoDBContext 类是 DynamoDB 数据库的入口点。它提供到 DynamoDB 的连接、让您能够访问各种表中的数据、执行各种 CRUD 操作,以及执行查询。DynamoDBContext 类提供以下方法:

Create​MultiTable​BatchGet

创建由多个 BatchGet 对象组成的 MultiTableBatchGet 对象。其中每个 BatchGet 对象都可用于检索单个 DynamoDB 表的项目。

要检索表中的项目,请使用 ExecuteBatchGet 方法,将 MultiTableBatchGet 对象作为参数传递。

Create​MultiTable​BatchWrite

创建由多个 BatchWrite 对象组成的 MultiTableBatchWrite 对象。其中每个 BatchWrite 对象都可用于写入或删除单个 DynamoDB 表中的项目。

要向表中写入,请使用 ExecuteBatchWrite 方法,将 MultiTableBatchWrite 对象作为参数传递。

Create​Batch​Get

创建可用于检索表中的多个项目的 BatchGet 对象。有关更多信息,请参阅 批量获取:获取多个项目

Create​Batch​Write

创建用于将多个项目放入表中或删除表中多个项目的 BatchWrite 对象。有关更多信息,请参阅 批量写入:放置和删除多个项目

Delete

删除表中的项目。此方法需要您提供要删除的项目的主键。您可以提供主键值,也可以提供包含主键值的客户端数据元作为此方法的参数。

  • 如果您指定一个客户端数据元作为参数,并且启用了乐观锁,那么只有当数据元的客户端版本和服务器端版本相匹配时才能成功执行删除操作。

  • 如果您只将主键值指定为参数,那么不管您是否启用乐观锁,都可以成功执行删除操作。

注意

要在后台执行此操作,请使用 DeleteAsync 方法。

Dispose

处理所有托管及非托管资源。

Execute​Batch​Get

读取一个或多个表中的数据,在 MultiTableBatchGet 中处理所有 BatchGet 对象。

注意

要在后台执行此操作,请使用 ExecuteBatchGetAsync 方法。

Execute​Batch​Write

在一个或多个表中写入或删除数据,在 MultiTableBatchWrite 中处理所有 BatchWrite 对象。

注意

要在后台执行此操作,请使用 ExecuteBatchWriteAsync 方法。

FromDocument

对于 Document 的实例,FromDocument 方法会返回客户端类的实例。

如果您要将文档模型类与对象持久化模型结合使用来执行任意数据操作,此方法会非常有用。有关适用于 .NET 的 AWS 开发工具包提供的文档模型类的更多信息,请参阅.NET:文档模型

假设您有名为 docDocument 对象,其中包含 Forum 项目的表示。 (要了解如何构造该对象,请参阅下文对 ToDocument 方法的描述。)您可以使用 FromDocument 检索 Document 的 Forum 项目,如下面的 C# 代码段所示。

Copy
forum101 = context.FromDocument<Forum>(101);

注意

如果您的 Document 对象实现 IEnumerable 接口,则您可以使用 FromDocuments 方法。这样,您就可以遍历 Document 中的所有类实例。

FromQuery

使用在 QueryOperationConfig 对象中定义的查询参数执行 Query 操作。

注意

要在后台执行此操作,请使用 FromQueryAsync 方法。

FromScan

使用在 ScanOperationConfig 对象中定义的扫描参数执行 Scan 操作。

注意

要在后台执行此操作,请使用 FromScanAsync 方法。

Get​Target​Table

检索指定类型的目标表。如果您要编写用于将任意数据映射到 DynamoDB 表的自定义转换器,并需要确定与某个自定义数据类型关联的表,则该操作十分有用。

Load

检索表中的项目。此方法只需要您提供要检索的项目的主键。

默认情况下,DynamoDB 所返回的项目的值采用最终一致性。有关最终一致性模型的信息,请参阅读取一致性

注意

要在后台执行此操作,请使用 LoadAsync 方法。

Query

根据您提供的查询参数查询表。

只有当表拥有复合主键 (分区键和排序键) 时,您才可以查询表。查询时,您必须指定一个分区键和一个适用于排序键的条件。

假设您有一个客户端 Reply 类映射到 DynamoDB 中的 Reply 表,以下 C# 代码段可以查询 Reply 表,以查找过去 15 天内发布的论坛话题回复。Reply 表的主键具有 Id 分区键和 ReplyDateTime 排序键。有关 Reply 表的更多信息,请参阅创建表并加载示例数据

Copy
DynamoDBContext context = new DynamoDBContext(client); string replyId = "DynamoDB#DynamoDB Thread 1"; //Partition key DateTime twoWeeksAgoDate = DateTime.UtcNow.Subtract(new TimeSpan(14, 0, 0, 0)); // Date to compare. IEnumerable<Reply> latestReplies = context.Query<Reply>(replyId, QueryOperator.GreaterThan, twoWeeksAgoDate);

此查询返回一系列 Reply 数据元。

Query 方法可以返回“延迟加载”IEnumerable 集合。它最初只返回一页结果,然后在需要时发出服务调用请求下一页结果。要获取匹配的所有项目,您只需对 IEnumerable 进行迭代。

如果您的表具有简单主键 (分区键),您就无法使用 Query 方法。您可以改而使用 Load 方法并提供分区键来检索相应的项目。

注意

要在后台执行此操作,请使用 QueryAsync 方法。

Save

将指定数据元保存到表中。如果表中没有在输入数据元中指定的主键,该方法就会向表中添加新项目。如果主键存在,该方法会更新现有项目。

如果您配置了乐观锁,那么只有在项目的客户端版本和服务器端版本匹配时才能成功执行更新操作。有关更多信息,请参阅 乐观锁 (使用版本号) 与 DynamoDB (使用适用于 .NET 的 AWS 开发工具包对象持久性模型) 配合使用

注意

要在后台执行此操作,请使用 SaveAsync 方法。

Scan

执行全表扫描。

您可以通过指定扫描条件来筛选扫描结果。您可以就表中的任意属性对条件进行评估。假设您有一个客户端类 Book 映射到 DynamoDB 中的 ProductCatalog 表,以下 C# 代码段可以扫描此表,并且只返回价格低于 0 的图书项目。

Copy
IEnumerable<Book> itemsWithWrongPrice = context.Scan<Book>( new ScanCondition("Price", ScanOperator.LessThan, price), new ScanCondition("ProductCategory", ScanOperator.Equal, "Book") );

Scan 方法可以返回“延迟加载”IEnumerable 集合。它最初只返回一页结果,然后在需要时发出服务调用请求下一页结果。要获取匹配的所有项目,您只需对 IEnumerable 进行迭代。

出于性能考虑,您应对表进行查询,而避免进行扫描。

注意

要在后台执行此操作,请使用 ScanAsync 方法。

ToDocument

从您的类实例返回 Document 文档模型类的实例。

如果您要将文档模型类与对象持久化模型结合使用来执行任意数据操作,此方法会非常有用。有关适用于 .NET 的 AWS 开发工具包提供的文档模型类的更多信息,请参阅.NET:文档模型

假设您有一个客户端类映射到示例 Forum 表,您就可以使用 DynamoDBContext 从 Forum 表中获取项目作为 Document 数据元,如以下 C# 代码段所示。

Copy
DynamoDBContext context = new DynamoDBContext(client); Forum forum101 = context.Load<Forum>(101); // Retrieve a forum by primary key. Document doc = context.ToDocument<Forum>(forum101);

指定适用于 DynamoDBContext 的可选参数

在使用对象持久化模型时,您可以为 DynamoDBContext 指定以下可选参数。

  • ConsistentRead – 当使用 LoadQueryScan 操作检索数据时,您可以选择添加此参数来请求相应数据的最新值。

  • IgnoreNullValues - 此参数通知 DynamoDBContextSave 操作期间忽略属性的所有空值。如果该参数为 False (或者未设置),则会将空值解释为用于删除特定属性的指令。

  • SkipVersionCheck – 此参数可以通知 DynamoDBContext 在保存或删除项目时不比较版本。有关版本控制的更多信息,请参阅乐观锁 (使用版本号) 与 DynamoDB (使用适用于 .NET 的 AWS 开发工具包对象持久性模型) 配合使用

  • TableNamePrefix - 为所有表名称加上特定字符串前缀。如果该参数为空 (或者未设置),则不使用前缀。

以下 C# 代码段通过指定上述两个可选参数来创建新的 DynamoDBContext。

Copy
AmazonDynamoDBClient client = new AmazonDynamoDBClient(); ... DynamoDBContext context = new DynamoDBContext(client, new DynamoDBContextConfig { ConsistentRead = true, SkipVersionCheck = true});

DynamoDBContext 在您使用此上下文发送的每个请求中都包含这两个可选参数。

您可以不在 DynamoDBContext 级设置这两个参数,而是使用 DynamoDBContext 为执行的各个操作指定这两个参数,如以下 C# 代码段所示。该示例加载一个特定图书项目。DynamoDBContextLoad 方法会指定上述可选参数。

Copy
AmazonDynamoDBClient client = new AmazonDynamoDBClient(); ... DynamoDBContext context = new DynamoDBContext(client); Book bookItem = context.Load<Book>(productId,new DynamoDBContextConfig{ ConsistentRead = true, SkipVersionCheck = true });

在本示例中,DynamoDBContext 只在发送 Get 请求时包含这两个参数。