CreateMultiTableBatchGet CreateMultiTableBatchWrite CreateBatchGet CreateBatchWrite Delete Dispose ExecuteBatchGet ExecuteBatchWrite FromDocument FromQuery FromScan GetTargetTable Load Query Save Scan ToDocument 指定 DynamoDBContext 的選用參數

.NET 物件持久性模型的 DynamoDBContext 類別

DynamoDBContext 類別是 Amazon DynamoDB 資料庫的進入點。它可讓您連線至 DynamoDB，繼而存取各種資料表中的資料、執行各種 CRUD 操作以及執行查詢。此 DynamoDBContext 類別提供下列方法。

主題

CreateMultiTableBatchGet
CreateMultiTableBatchWrite
CreateBatchGet
CreateBatchWrite
Delete
Dispose
ExecuteBatchGet
ExecuteBatchWrite
FromDocument
FromQuery
FromScan
GetTargetTable
Load
Query
Save
Scan
ToDocument
指定 DynamoDBContext 的選用參數

CreateMultiTableBatchGet

建立由多個個別 BatchGet 物件組成的 MultiTableBatchGet 物件。其中的每個 BatchGet 物件都可用來從單一 DynamoDB 資料表中擷取項目。

若要從資料表擷取項目，請使用 ExecuteBatchGet 方法，將 MultiTableBatchGet 物件作為參數傳遞。

CreateMultiTableBatchWrite

建立由多個個別 BatchWrite 物件組成的 MultiTableBatchWrite 物件。其中的每個 BatchWrite 物件可用來寫入或刪除單一 DynamoDB 資料表中的項目。

若要寫入資料表，請使用 ExecuteBatchWrite 方法，將 MultiTableBatchWrite 物件作為參數傳遞。

CreateBatchGet

建立 BatchGet 物件，您可以使用該物件從資料表中擷取多個項目。

CreateBatchWrite

建立 BatchWrite 物件，您可以使用該物件將多個項目放入資料表中，或從資料表中刪除多個項目。

Delete

刪除資料表中的項目。這個方法需要您希望刪除之項目的主索引鍵。您可以提供主索引鍵值或包含主索引鍵值的用戶端物件，作為此方法的參數。

如果指定用戶端物件作為參數，且已啟用樂觀鎖定，則只有在物件的用戶端和伺服器端版本相符時，才能成功刪除項目。
如果只指定主索引鍵值作為參數，無論您是否已啟用樂觀鎖定，刪除都會成功。

注意

若要在背景執行此操作，請改用 DeleteAsync 方法。

Dispose

處置所有受管和非受管的資源。

ExecuteBatchGet

從一或多個資料表讀取資料，處理 MultiTableBatchGet 中的所有 BatchGet 物件。

注意

若要在背景執行此操作，請改用 ExecuteBatchGetAsync 方法。

ExecuteBatchWrite

在一或多個資料表中寫入或刪除資料，處理 MultiTableBatchWrite 中的所有 BatchWrite 物件。

注意

若要在背景執行此操作，請改用 ExecuteBatchWriteAsync 方法。

FromDocument

若為 Document 執行個體，FromDocument 方法會傳回用戶端類別的執行個體。

如果您想使用文件模型類別以及物件持久性模型來執行任何資料操作，這會很有幫助。如需適用於 .NET 的 AWS SDK 所提供文件模型類別的詳細資訊，請參閱在 DynamoDB 中使用 .NET 文件模型。

假設您有名為 doc 的 Document 物件，且其中包含 Forum 項目的表示法。(若要查看如何建構此物件，請參閱本主題後續內容中的 ToDocument 方法說明。) 您可以使用 FromDocument 從 Document 擷取 Forum 項目，如下列 C# 程式碼範例所示。

範例


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

注意

如果您的 Document 物件會實作 IEnumerable 介面，您可以使用 FromDocuments 方法。這允許您逐一查看 Document 中的所有類別執行個體。

FromQuery

以 QueryOperationConfig 物件中定義的查詢參數執行 Query 操作。

注意

若要在背景執行此操作，請改用 FromQueryAsync 方法。

FromScan

以 ScanOperationConfig 物件中定義的掃描參數執行 Scan 操作。

注意

若要在背景執行此操作，請改用 FromScanAsync 方法。

GetTargetTable

擷取指定類型的目標資料表。如果您正在撰寫自訂轉換器，將任意資料映射至 DynamoDB 資料表，而且需要判斷哪個資料表與自訂資料類型相關聯，則此功能非常有用。

Load

從資料表擷取項目。這個方法只需要您希望擷取之項目的主索引鍵。

DynamoDB 預設會傳回數值最終一致的項目。如需最終一致性模式的資訊，請參閱 DynamoDB 讀取一致性。

Load 或 LoadAsync 方法會呼叫 GetItem 操作，這需要您指定資料表的主索引鍵。由於 GetItem 會忽略 IndexName 參數，您無法使用索引分割區或排序索引鍵載入項目。因此您必須使用資料表主索引鍵來載入項目。

注意

若要在背景執行此操作，請改用 LoadAsync 方法。若要檢視使用 LoadAsync 方法在 DynamoDB 資料表執行高階 CRUD 操作的範例，請參閱下列範例。



    /// <summary>
    /// Shows how to perform high-level CRUD operations on an Amazon DynamoDB
    /// table.
    /// </summary>
    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<string> { "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<Book>(bookId);

            // Update some properties.
            bookRetrieved.Isbn = "222-2222221001";

            // Update existing authors list with the following values.
            bookRetrieved.BookAuthors = new List<string> { " 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<Book>(bookId, new DynamoDBContextConfig
            {
                ConsistentRead = true,
            });

            // Delete the book.
            await context.DeleteAsync<Book>(bookId);

            // Try to retrieve deleted book. It should return null.
            Book deletedBook = await context.LoadAsync<Book>(bookId, new DynamoDBContextConfig
            {
                ConsistentRead = true,
            });

            if (deletedBook == null)
            {
                Console.WriteLine("Book is deleted");
            }
        }
    }

Query

根據您提供的查詢參數查詢資料表。

您只能查詢具有複合主鍵 (分割區索引鍵和排序索引鍵) 的資料表。查詢時，必須指定分割區索引鍵和套用至排序索引鍵的條件。

假設您有用戶端 Reply 類別映射至 DynamoDB 中的 Reply 資料表。下列 C# 程式碼範例會查詢 Reply 資料表，找出過去 15 天所張貼的論壇主題回覆。Reply 資料表的主索引鍵具有 Id 分割區索引鍵和 ReplyDateTime 排序索引鍵。

範例


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 SDK 物件持久性模型的樂觀鎖定。

注意

若要在背景執行此操作，請改用 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 文件模型類別的執行個體。

假設您有用戶端類別映射至範例 Forum 資料表。然後，您可以使用 DynamoDBContext 從 Forum 資料表中獲取項目作為 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：當使用 Load、Query 或 Scan 操作來擷取資料時，您可以新增此選用參數來請求資料的最新數值。
IgnoreNullValues：此參數會通知 DynamoDBContext 在 Save 操作期間忽略屬性上的 Null 數值。如果此參數為 false (或未設定)，則會將 Null 數值轉譯為刪除特定屬性的指令。
SkipVersionCheck：此參數會通知 DynamoDBContext 不要在儲存或刪除項目時比較版本。如需版本控制的詳細資訊，請參閱「使用 DynamoDB 和適用於 .NET 的 AWS SDK 物件持久性模型的樂觀鎖定」。
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# 範例會指定 ConsistentRead 和 SkipVersionCheck 這兩個上述選用參數來建立新的 DynamoDBContext。

範例


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

DynamoDBContext 包含這些選用參數，以及您使用此內容傳送的每個請求。

您可以使用 DynamoDBContext 為個別操作指定參數，而不是在 DynamoDBContext 層級設定這些參數，如下列 C# 程式碼範例所示。此範例會載入特定的書籍項目。DynamoDBContext 的 Load 方法會指定 ConsistentRead 和 SkipVersionCheck 等選用參數。

範例


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

在此例中，DynamoDBContext 只有在傳送 Get 請求時才會包含這些參數。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

DynamoDB 屬性

使用版本編號的樂觀鎖定