DynamoDBContext 类 - Amazon DynamoDB
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

DynamoDBContext 类

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

Create​MultiTable​BatchGet

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

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

Create​MultiTable​BatchWrite

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

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

Create​batch​get

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

Create​batch​write

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

删除

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

  • 如果将客户端对象指定为参数,并且启用了乐观锁定,则只有在对象的客户端版本和服务器端版本匹配时,删除才会成功。

  • 如果仅将主键值指定为参数,则无论您是否启用了乐观锁定,删除都会成功。

注意

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

Dispose

处置所有托管和非托管资源。

Execute​batch​get

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

注意

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

Execute​batch​write

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

注意

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

FromDocument

给定一个 Document 实例,FromDocument 方法返回客户端类的实例。

如果要将文档模型类与对象持久化模型一起使用来执行任何数据操作,这将非常有用。有关 Amazon SDK for .NET 提供的文档模型类的更多信息,请参阅.NET:文档模型

假设您有一个名为 docDocument 对象,其中包含 Forum 项目。(要了解如何构造此对象,请参阅本主题稍后的 ToDocument 方法说明。) 您可以使用 FromDocumentDocument 检索 Forum 项目,如以下 C# 代码示例所示。

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

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

FromQuery

运行Query操作,查询参数定义在QueryOperationConfig对象。

注意

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

FromScan

运行Scan操作,扫描参数定义在ScanOperationConfig对象。

注意

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

Get​target​table

检索指定类型的目标表。如果您正在编写用于将任意数据映射到 DynamoDB 表的自定义转换器,并且需要确定哪个表与自定义数据类型相关联,则此选项非常有用。

Load

检索表中的项目。方法只需要要检索的项目的主键。

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

注意

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

查询

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

只有当表或索引具有复合主键(分区键和排序键)时,您才能对其执行查询。在查询时,您必须指定分区键以及适用于排序键的条件。

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

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(保存)

将指定对象保存到表中。如果表中不存在输入对象中指定的主键,则方法会将新项目添加到表中。如果存在主键,此方法就会更新现有项目。

如果您配置了乐观锁定,则仅当客户端和项目的服务器端版本匹配时,更新才会成功。有关更多信息,请参阅将使用版本号的乐观锁与使用 Amazon SDK for .NET 对象持久化模型的 DynamoDB 结合使用

注意

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

Scan

执行整个表扫描。

您可以通过指定扫描条件来筛选扫描结果。可以根据表中的任何属性对条件进行评估。假设您有一个客户端类 Book 映射到 DynamoDB 的 ProductCatalog 表。以下 C# 示例扫描表并仅返回价格小于 0 的书籍项目。

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

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

出于性能考虑,您应查询表并避免表扫描。

注意

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

ToDocument

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

如果要将文档模型类与对象持久化模型一起使用来执行任何数据操作,这将非常有用。有关 Amazon SDK for .NET 提供的文档模型类的更多信息,请参阅.NET:文档模型

假设您有一个映射到示例 Forum 表的客户端类。然后,您可以使用 DynamoDBContextForum 表获取一个项目作为 Document 对象,如以下 C# 代码示例所示。

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保存或删除项目时不比较版本。有关版本控制的更多信息,请参阅 将使用版本号的乐观锁与使用 Amazon SDK for .NET 对象持久化模型的 DynamoDB 结合使用

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

下面的 C# 示例指定前面的两个可选参数,创建一个新的 DynamoDBContext

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

DynamoDBContext包含这些可选参数以及您使用此上下文发送的每个请求。

不在 DynamoDBContext 级别设置这些参数,可以为使用 DynamoDBContext 运行的各个操作指定,如以下 C# 代码示例所示。此示例加载特定的图书项目。DynamoDBContextLoad 方法指定前面的可选参数。

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

在这种情况下,DynamoDBContext 仅在发送 Get 请求时包含这些参数。