本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # .NET 物件持久性模型的 DynamoDBContext 類別 `DynamoDBContext` 類別是 Amazon DynamoDB 資料庫的進入點。它可讓您連線至 DynamoDB，繼而存取各種資料表中的資料、執行各種 CRUD 操作以及執行查詢。此 `DynamoDBContext` 類別提供下列方法。 **Topics** + [Create​MultiTable​BatchGet](#w2aac17b9c21c23c39b7) + [Create​MultiTable​BatchWrite](#w2aac17b9c21c23c39b9) + [CreateBatchGet](#w2aac17b9c21c23c39c11) + [CreateBatchWrite](#w2aac17b9c21c23c39c13) + [刪除](#w2aac17b9c21c23c39c15) + [Dispose](#w2aac17b9c21c23c39c17) + [Execute​Batch​Get](#w2aac17b9c21c23c39c19) + [Execute​Batch​Write](#w2aac17b9c21c23c39c21) + [FromDocument](#w2aac17b9c21c23c39c23) + [FromQuery](#w2aac17b9c21c23c39c25) + [FromScan](#w2aac17b9c21c23c39c27) + [Get​Target​Table](#w2aac17b9c21c23c39c29) + [Load](#w2aac17b9c21c23c39c31) + [Query](#w2aac17b9c21c23c39c33) + [Save](#w2aac17b9c21c23c39c35) + [Scan](#w2aac17b9c21c23c39c37) + [ToDocument](#w2aac17b9c21c23c39c39) + [指定 DynamoDBContext 的選用參數](#OptionalConfigParams) ## Create​MultiTable​BatchGet 建立由多個個別 `BatchGet` 物件組成的 `MultiTableBatchGet` 物件。其中的每個 `BatchGet` 物件都可用來從單一 DynamoDB 資料表中擷取項目。 若要從資料表擷取項目，請使用 `ExecuteBatchGet` 方法，將 `MultiTableBatchGet` 物件作為參數傳遞。 ## Create​MultiTable​BatchWrite 建立由多個個別 `BatchWrite` 物件組成的 `MultiTableBatchWrite` 物件。其中的每個 `BatchWrite` 物件可用來寫入或刪除單一 DynamoDB 資料表中的項目。 若要寫入資料表，請使用 `ExecuteBatchWrite` 方法，將 `MultiTableBatchWrite` 物件作為參數傳遞。 ## CreateBatchGet 建立 `BatchGet` 物件，您可以使用該物件從資料表中擷取多個項目。 ## CreateBatchWrite 建立 `BatchWrite` 物件，您可以使用該物件將多個項目放入資料表中，或從資料表中刪除多個項目。 ## 刪除 刪除資料表中的項目。這個方法需要您希望刪除之項目的主索引鍵。您可以提供主索引鍵值或包含主索引鍵值的用戶端物件，作為此方法的參數。 + 如果指定用戶端物件作為參數，且已啟用樂觀鎖定，則只有在物件的用戶端和伺服器端版本相符時，才能成功刪除項目。 + 如果只指定主索引鍵值作為參數，無論您是否已啟用樂觀鎖定，刪除都會成功。 **注意** 若要在背景執行此操作，請改用 `DeleteAsync` 方法。 ## Dispose 處置所有受管和非受管的資源。 ## Execute​Batch​Get 從一或多個資料表讀取資料，處理 `MultiTableBatchGet` 中的所有 `BatchGet` 物件。 **注意** 若要在背景執行此操作，請改用 `ExecuteBatchGetAsync` 方法。 ## Execute​Batch​Write 在一或多個資料表中寫入或刪除資料，處理 `MultiTableBatchWrite` 中的所有 `BatchWrite` 物件。 **注意** 若要在背景執行此操作，請改用 `ExecuteBatchWriteAsync` 方法。 ## FromDocument 若為 `Document` 執行個體，`FromDocument` 方法會傳回用戶端類別的執行個體。 如果您想使用文件模型類別以及物件持久性模型來執行任何資料操作，這會很有幫助。如需 提供之文件模型類別的詳細資訊 適用於 .NET 的 AWS SDK，請參閱 [在 DynamoDB 中使用 .NET 文件模型](DotNetSDKMidLevel.md)。 假設您有名為 `doc` 的 `Document` 物件，且其中包含 `Forum` 項目的表示法。(若要查看如何建構此物件，請參閱本主題後續內容中的 `ToDocument` 方法說明。) 您可以使用 `FromDocument` 從 `Document` 擷取 `Forum` 項目，如下列 C\$1 程式碼範例所示。 **Example** ``` forum101 = context.FromDocument(101); ``` **注意** 如果您的 `Document` 物件會實作 `IEnumerable` 介面，您可以使用 `FromDocuments` 方法。這允許您逐一查看 `Document` 中的所有類別執行個體。 ## FromQuery 以 `QueryOperationConfig` 物件中定義的查詢參數執行 `Query` 操作。 **注意** 若要在背景執行此操作，請改用 `FromQueryAsync` 方法。 ## FromScan 以 `ScanOperationConfig` 物件中定義的掃描參數執行 `Scan` 操作。 **注意** 若要在背景執行此操作，請改用 `FromScanAsync` 方法。 ## Get​Target​Table 擷取指定類型的目標資料表。如果您正在撰寫自訂轉換器，將任意資料映射至 DynamoDB 資料表，而且需要判斷哪個資料表與自訂資料類型相關聯，則此功能非常有用。 ## Load 從資料表擷取項目。這個方法只需要您希望擷取之項目的主索引鍵。 DynamoDB 預設會傳回數值最終一致的項目。如需最終一致性模式的資訊，請參閱 [DynamoDB 讀取一致性](HowItWorks.ReadConsistency.md)。 `Load` 或 `LoadAsync` 方法會呼叫 [GetItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html) 操作，這需要您指定資料表的主索引鍵。由於 `GetItem` 會忽略 `IndexName` 參數，您無法使用索引分割區或排序索引鍵載入項目。因此您必須使用資料表主索引鍵來載入項目。 **注意** 若要在背景執行此操作，請改用 `LoadAsync` 方法。若要檢視使用 `LoadAsync` 方法在 DynamoDB 資料表執行高階 CRUD 操作的範例，請參閱下列範例。 ``` /// /// Shows how to perform high-level CRUD operations on an Amazon DynamoDB /// table. /// public class HighLevelItemCrud { public static async Task Main() { var client = new AmazonDynamoDBClient(); DynamoDBContext context = new DynamoDBContext(client); await PerformCRUDOperations(context); } public static async Task PerformCRUDOperations(IDynamoDBContext context) { int bookId = 1001; // Some unique value. Book myBook = new Book { Id = bookId, Title = "object persistence-AWS SDK for.NET SDK-Book 1001", Isbn = "111-1111111001", BookAuthors = new List { "Author 1", "Author 2" }, }; // Save the book to the ProductCatalog table. await context.SaveAsync(myBook); // Retrieve the book from the ProductCatalog table. Book bookRetrieved = await context.LoadAsync(bookId); // Update some properties. bookRetrieved.Isbn = "222-2222221001"; // Update existing authors list with the following values. bookRetrieved.BookAuthors = new List { " Author 1", "Author x" }; await context.SaveAsync(bookRetrieved); // Retrieve the updated book. This time, add the optional // ConsistentRead parameter using DynamoDBContextConfig object. await context.LoadAsync(bookId, new DynamoDBContextConfig { ConsistentRead = true, }); // Delete the book. await context.DeleteAsync(bookId); // Try to retrieve deleted book. It should return null. Book deletedBook = await context.LoadAsync(bookId, new DynamoDBContextConfig { ConsistentRead = true, }); if (deletedBook == null) { Console.WriteLine("Book is deleted"); } } } ``` ## Query 根據您提供的查詢參數查詢資料表。 您只能查詢具有複合主鍵 (分割區索引鍵和排序索引鍵) 的資料表。查詢時，必須指定分割區索引鍵和套用至排序索引鍵的條件。 假設您有用戶端 `Reply` 類別映射至 DynamoDB 中的 `Reply` 資料表。下列 C\$1 程式碼範例會查詢 `Reply` 資料表，找出過去 15 天所張貼的論壇主題回覆。`Reply` 資料表的主索引鍵具有 `Id` 分割區索引鍵和 `ReplyDateTime` 排序索引鍵。 **Example** ``` 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 latestReplies = context.Query(replyId, QueryOperator.GreaterThan, twoWeeksAgoDate); ``` 這會傳回 `Reply` 物件的集合。 `Query` 方法會傳回「延遲載入」`IEnumerable` 集合。它一開始只會傳回一頁的結果，然後視需要進行服務呼叫來取得下一頁。若要取得所有相符的項目，您只需要逐一查看 `IEnumerable`。 如果資料表具有簡易主索引鍵 (分割區索引鍵)，您便不能使用 `Query` 方法。不過，您可以使用 `Load` 方法並提供分割區索引鍵來擷取項目。 **注意** 若要在背景執行此操作，請改用 `QueryAsync` 方法。 ## Save 將指定的物件儲存至資料表。如果輸入物件中指定的主索引鍵不存在於資料表中，該方法會將新項目新增至資料表中。如果主索引鍵存在，該方法會更新現有項目。 如果您已設定樂觀鎖定，則只有在用戶端和項目的伺服器端版本相符時才能成功更新項目。如需詳細資訊，請參閱[使用 DynamoDB 和 適用於 .NET 的 AWS SDK 物件持久性模型的樂觀鎖定](DynamoDBContext.VersionSupport.md)。 **注意** 若要在背景執行此操作，請改用 `SaveAsync` 方法。 ## Scan 執行整個資料表掃描。 您可以指定掃描條件來篩選掃描結果。您可以根據資料表中的任何屬性來評估條件。假設您有用戶端 `Book` 類別映射至 DynamoDB 中的 `ProductCatalog` 資料表。下列 C\$1 範例會掃描資料表，並且只會傳回價格低於 0 的所有書籍項目。 **Example** ``` IEnumerable itemsWithWrongPrice = context.Scan( new ScanCondition("Price", ScanOperator.LessThan, price), new ScanCondition("ProductCategory", ScanOperator.Equal, "Book") ); ``` `Scan` 方法會傳回「延遲載入」`IEnumerable` 集合。它一開始只會傳回一頁的結果，然後視需要進行服務呼叫來取得下一頁。若要取得所有相符的項目，您只需要逐一查看 `IEnumerable`。 出於效能考量，您應查詢資料表並避免執行資料表掃描。 **注意** 若要在背景執行此操作，請改用 `ScanAsync` 方法。 ## ToDocument 從類別執行個體傳回 `Document` 文件模型類別的執行個體。 如果您想使用文件模型類別以及物件持久性模型來執行任何資料操作，這會很有幫助。如需 提供之文件模型類別的詳細資訊 適用於 .NET 的 AWS SDK，請參閱 [在 DynamoDB 中使用 .NET 文件模型](DotNetSDKMidLevel.md)。 假設您有用戶端類別映射至範例 `Forum` 資料表。然後，您可以使用 `DynamoDBContext` 從 `Forum` 資料表中獲取項目作為 `Document` 物件，如下列 C\$1 程式碼範例所示。 **Example** ``` DynamoDBContext context = new DynamoDBContext(client); Forum forum101 = context.Load(101); // Retrieve a forum by primary key. Document doc = context.ToDocument(forum101); ``` ## 指定 DynamoDBContext 的選用參數 使用物件持久性模型時，您可以指定 `DynamoDBContext` 的下列選用參數。 + **`ConsistentRead`：**當使用 `Load`、`Query` 或 `Scan` 操作來擷取資料時，您可以新增此選用參數來請求資料的最新數值。 + **`IgnoreNullValues`：**此參數會通知 `DynamoDBContext` 在 `Save` 操作期間忽略屬性上的 Null 數值。如果此參數為 false (或未設定)，則會將 Null 數值轉譯為刪除特定屬性的指令。 + **`SkipVersionCheck`：**此參數會通知 `DynamoDBContext` 不要在儲存或刪除項目時比較版本。如需版本控制的詳細資訊，請參閱「[使用 DynamoDB 和 適用於 .NET 的 AWS SDK 物件持久性模型的樂觀鎖定](DynamoDBContext.VersionSupport.md)」。 + **`TableNamePrefix`：**使用特定字串作為所有資料表名稱的字首。如果此參數為 null (或未設定)，則不會使用字首。 + `DynamoDBEntryConversion` – 指定用戶端使用的轉換結構描述。您可以將此參數設定為版本 V1 或 V2。V1 是預設版本。 根據您設定的版本，此參數的行為會變更。例如： + 在 V1 中，`bool` 資料類型會轉換為 `N` 數字類型，其中 0 代表 false，1 代表 true。在 V2 中，`bool` 會轉換為 `BOOL`。 + 在 V2 中，清單和陣列不會與 HashSet 一起分組。數值、字串類型和二進位類型的清單和陣列會轉換為 `L` (清單) 類型，可以傳送空白清單來更新清單。這與 V1 不同，其中空白清單不會透過線路傳送。 在 V1 中，清單、HashSet 和陣列等集合類型都視為相同。清單、HashSet 和數值陣列會轉換為 `NS` (數字集) 類型。 下列範例會將轉換結構描述版本設定為 V2，變更 .NET 類型和 DynamoDB 資料類型之間的轉換行為。 ``` var config = new DynamoDBContextConfig { Conversion = DynamoDBEntryConversion.V2 }; var contextV2 = new DynamoDBContext(client, config); ``` 下列 C\$1 範例會指定 `ConsistentRead` 和 `SkipVersionCheck` 這兩個上述選用參數來建立新的 `DynamoDBContext`。 **Example** ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); ... DynamoDBContext context = new DynamoDBContext(client, new DynamoDBContextConfig { ConsistentRead = true, SkipVersionCheck = true}); ``` `DynamoDBContext` 包含這些選用參數，以及您使用此內容傳送的每個請求。 您可以使用 `DynamoDBContext` 為個別操作指定參數，而不是在 `DynamoDBContext` 層級設定這些參數，如下列 C\$1 程式碼範例所示。此範例會載入特定的書籍項目。`DynamoDBContext` 的 `Load` 方法會指定 `ConsistentRead` 和 `SkipVersionCheck` 等選用參數。 **Example** ``` AmazonDynamoDBClient client = new AmazonDynamoDBClient(); ... DynamoDBContext context = new DynamoDBContext(client); Book bookItem = context.Load(productId,new DynamoDBContextConfig{ ConsistentRead = true, SkipVersionCheck = true }); ``` 在此例中，`DynamoDBContext` 只有在傳送 `Get` 請求時才會包含這些參數。