放入項目取得項目更新項目原子計數器刪除項目批次寫入：放入和刪除多個項目批次取得：取得多個項目

使用項目：。NET

您可以使用 AWS SDK for .NET 低階 API 對資料表中的項目執行典型的建立、讀取、更新和刪除（CRUD）操作。以下是使用執行資料CRUD操作時，您遵循的常見步驟。NET低階 API：

建立 AmazonDynamoDBClient 類別的執行個體 (用戶端)。
在對應的請求物件中，提供操作專屬的必要參數。

例如，上傳項目時使用 PutItemRequest 請求物件，擷取現有的項目時使用 GetItemRequest 請求物件。

您可以使用請求物件來提供必要和選用的參數。
透過傳遞您在前一步驟中所建立的請求物件，執行用戶端提供的適當方法。

AmazonDynamoDBClient 用戶端為 CRUD操作提供 UpdateItem、、 PutItem GetItem和 DeleteItem方法。

主題

放入項目

PutItem 方法會將項目上傳至資料表。若已有該項目，其會取代整個項目。

注意

若不希望取代整個項目，而是只想要更新特定的屬性，可以使用 UpdateItem 方法。如需詳細資訊，請參閱更新項目。

以下是使用低階 NET上傳項目的步驟SDKAPI：

建立 AmazonDynamoDBClient 類別的執行個體。
您可以透過建立 PutItemRequest 類別的執行個體來提供必要的參數。

若要放入項目，您必須提供資料表名稱及項目。
提供您在前一個步驟中建立的 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);

在上述範例中，您要上傳具有 Id、Title、ISBN 和 Authors 屬性的書籍項目。請注意，Id 是數值類型的屬性，而所有其他屬性則是字串類型。作者是 String 集合。

指定選用參數

您也可以使用 PutItemRequest 物件提供選用參數，如以下 C# 範例所示。此範例會指定下列選用參數：

ExpressionAttributeNames、 ExpressionAttributeValues和 ConditionExpression指定只有在現有項目具有具有特定值的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 方法。如需詳細資訊，請參閱批次取得：取得多個項目。

以下是使用低階 AWS SDK for .NET 擷取現有項目的步驟API。

建立 AmazonDynamoDBClient 類別的執行個體。
您可以透過建立 GetItemRequest 類別的執行個體來提供必要的參數。

若要取得項目，您必須提供資料表名稱及項目的主索引鍵。
提供您在前一個步驟中建立的 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 參數，用來執行強烈一致讀取。若要進一步了解讀取一致性，請參閱 DynamoDB 讀取一致性。

範例


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 會套用更新，如下所示：
- 使用更新中的值取代現有的屬性值。
- 若您在輸入中提供的屬性不存在，則其會為項目新增新的屬性。
- 若輸入屬性為 Null，則其會刪除該屬性 (若有的話)。
- 如果您針對 Action 使用 ADD，就可以將值新增至現有的集合 (字串集或數字集)，或以數學方法加 (使用正數) 減 (使用負數) 現有的數值屬性值。

注意

PutItem 操作也可以執行更新。如需詳細資訊，請參閱放入項目。例如，如果您呼叫 PutItem 上傳項目，且主索引鍵已存在，則 PutItem 操作會取代整個項目。如果現有的項目中有屬性，但輸入中並未指定這些屬性，則 PutItem 操作會刪除這些屬性。但是，UpdateItem 只會更新指定的輸入屬性。任何其他該項目現有的屬性都不會變更。

以下是使用低階更新現有項目的步驟。NETSDKAPI：

建立 AmazonDynamoDBClient 類別的執行個體。
您可以透過建立 UpdateItemRequest 類別的執行個體來提供必要的參數。

這是您說明所有更新的請求物件，例如新增屬性、更新現有的屬性或刪除屬性。若要刪除現有的屬性，請以 Null 值指定屬性名稱。
提供您在前一個步驟中建立的 UpdateItem 物件來執行 UpdateItemRequest 方法。

下列 C# 程式碼範例示範前述步驟。範例會更新 ProductCatalog 表中的項目。它會將新的作者新增到 Authors 集合，並刪除現有的 ISBN 屬性。它也會將價格減一。


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# 範例所示。它會指定以下選用參數：

ExpressionAttributeValues 和 ConditionExpression 指定只有當現有價格為 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 來實作原子計數器以增加或減少現有屬性的值，卻不干擾其他寫入請求。若要更新原子計數器，UpdateExpression 參數請使用屬性類型為 Number 的 updateItem，Action 使用 ADD。

下列範例示範這項作業，將 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 SDK API

建立 AmazonDynamoDBClient 類別的執行個體。
您可以透過建立 DeleteItemRequest 類別的執行個體來提供必要的參數。

若要刪除項目，需要有資料表名稱及項目的主索引鍵。
提供您在前一個步驟中建立的 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# 程式碼範例所示。它會指定以下選用參數：

ExpressionAttributeValues 並ConditionExpression指定只有在書籍項目不再位於發佈中時，才能將其刪除（ 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 SDK API

建立 AmazonDynamoDBClient 類別的執行個體。
透過建立 BatchWriteItemRequest 類別的執行個體來說明所有的放入與刪除操作。
提供您在前一個步驟中建立的 BatchWriteItem 物件來執行 BatchWriteItemRequest 方法。
處理回應。您應該檢查回應中是否傳回任何未經處理的請求項目。如果您達到佈建輸送量配額或遇到一些其他暫時性錯誤，就可能發生這個狀況。此外，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);

如需運作範例，請參閱範例：使用 AWS SDK for .NET 低階的批次操作 API。

批次取得：取得多個項目

您可利用 BatchGetItem 方法，從一或多個資料表擷取多個項目。

注意

若要擷取單一項目，可以使用 GetItem 方法。

以下是使用低階 AWS SDK for .NET 擷取多個項目的步驟API。

建立 AmazonDynamoDBClient 類別的執行個體。
您可以透過建立 BatchGetItemRequest 類別的執行個體來提供必要的參數。

若要擷取多個項目，需要有資料表名稱及主索引鍵值的清單。
提供您在前一個步驟中建立的 BatchGetItem 物件來執行 BatchGetItemRequest 方法。
處理回應。您應該檢查是否有任何未經處理的索引鍵，如果您達到佈建輸送量配額或遇到一些其他暫時性錯誤，就可能發生這個狀況。

下列 C# 程式碼範例示範前述步驟。範例會從 Forum 和 Thread 這兩份資料表擷取項目。請求會指定兩個 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。

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

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

文件慣用形式

範例：處理二進位類型屬性 - Java 文件 API

範例：CRUD操作 - .NET 低階 API