本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 處理項目：.NET
<a name="LowLevelDotNetItemCRUD"></a>

您可以使用 適用於 .NET 的 AWS SDK 低階 API，對資料表中的項目執行典型的建立、讀取、更新和刪除 (CRUD) 操作。以下是使用 .NET 低階 API 執行資料 CRUD 操作所遵循的一般步驟：

1. 建立 `AmazonDynamoDBClient` 類別的執行個體 (用戶端)。

1. 在對應的請求物件中，提供操作專屬的必要參數。

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

   您可以使用請求物件來提供必要和選用的參數。

1. 透過傳遞您在前一步驟中所建立的請求物件，執行用戶端提供的適當方法。

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

**Topics**
+ [放入項目](#PutItemLowLevelAPIDotNet)
+ [取得項目](#GetItemLowLevelDotNET)
+ [更新項目](#UpdateItemLowLevelDotNet)
+ [原子計數器](#AtomicCounterLowLevelDotNet)
+ [刪除項目](#DeleteMidLevelDotNet)
+ [批次寫入：放入和刪除多個項目](#BatchWriteLowLevelDotNet)
+ [批次取得：取得多個項目](#BatchGetLowLevelDotNet)
+ [範例：使用 適用於 .NET 的 AWS SDK 低階 API 的 CRUD 操作](LowLevelDotNetItemsExample.md)
+ [範例：使用 適用於 .NET 的 AWS SDK 低階 API 的批次操作](batch-operation-lowlevel-dotnet.md)
+ [範例：使用 適用於 .NET 的 AWS SDK 低階 API 處理二進位類型屬性](LowLevelDotNetBinaryTypeExample.md)

## 放入項目
<a name="PutItemLowLevelAPIDotNet"></a>

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

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

以下是使用低階 .NET 軟體開發套件 API 上傳項目的步驟：

1. 建立 `AmazonDynamoDBClient` 類別的執行個體。

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

   若要放入項目，您必須提供資料表名稱及項目。

1. 提供您在前一個步驟中建立的 `PutItem` 物件來執行 `PutItemRequest` 方法。

下列 C\$1 範例示範前述步驟。範例會將項目上傳至 `ProductCatalog` 資料表。

**Example**  

```
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` 集合。

### 指定選用參數
<a name="PutItemLowLevelAPIDotNetOptions"></a>

您也可以使用 `PutItemRequest` 物件提供選用參數，如以下 C\$1 範例所示。此範例會指定下列選用參數：
+ `ExpressionAttributeNames`、`ExpressionAttributeValues` 和 `ConditionExpression` 指定，只有當現有項目的 ISBN 屬性為特定值時，才能取代該項目。
+ `ReturnValues` 參數請求回應中為舊項目。

**Example**  

```
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](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html)。

## 取得項目
<a name="GetItemLowLevelDotNET"></a>

`GetItem` 方法會擷取項目。

**注意**  
若要擷取多個項目，您可以使用 `BatchGetItem` 方法。如需詳細資訊，請參閱 [批次取得：取得多個項目](#BatchGetLowLevelDotNet)。

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

1. 建立 `AmazonDynamoDBClient` 類別的執行個體。

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

   若要取得項目，您必須提供資料表名稱及項目的主索引鍵。

1. 提供您在前一個步驟中建立的 `GetItem` 物件來執行 `GetItemRequest` 方法。

下列 C\$1 範例示範前述步驟。下列範例會從 `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.
```

### 指定選用參數
<a name="GetItemLowLevelDotNETOptions"></a>

您也可以使用 `GetItemRequest` 物件提供選用參數，如以下 C\$1 範例所示。範例會指定下列選用參數：
+ `ProjectionExpression` 參數會指定要擷取的屬性。
+ `ConsistentRead` 參數，用來執行高度一致性讀取。若要進一步了解讀取一致性，請參閱 [DynamoDB 讀取一致性](HowItWorks.ReadConsistency.md)。

**Example**  

```
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](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html)。

## 更新項目
<a name="UpdateItemLowLevelDotNet"></a>

`UpdateItem` 方法會更新現有的項目 (若存在的話)。您可以使用 `UpdateItem` 操作來更新現有的屬性值、新增新的屬性，或從現有的集合刪除屬性。若找不到具有指定主索引鍵的項目，則其會新增新的項目。

`UpdateItem` 操作使用以下準則：
+ 若還沒有該項目，`UpdateItem` 會使用輸入中指定的主索引鍵新增項目。
+ 若已有該項目，`UpdateItem` 會套用更新，如下所示：
  + 使用更新中的值取代現有的屬性值。
  + 若您在輸入中提供的屬性不存在，則其會為項目新增新的屬性。
  + 若輸入屬性為 Null，則其會刪除該屬性 (若有的話)。
  + 如果您針對 `Action` 使用 `ADD`，就可以將值新增至現有的集合 (字串集或數字集)，或以數學方法加 (使用正數) 減 (使用負數) 現有的數值屬性值。

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

以下是使用低階 .NET 軟體開發套件 API 來更新現有項目的步驟。

1. 建立 `AmazonDynamoDBClient` 類別的執行個體。

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

   這是您說明所有更新的請求物件，例如新增屬性、更新現有的屬性或刪除屬性。若要刪除現有的屬性，請以 Null 值指定屬性名稱。

1. 提供您在前一個步驟中建立的 `UpdateItem` 物件來執行 `UpdateItemRequest` 方法。

下列 C\$1 程式碼範例示範前述步驟。範例會更新 `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);
```

### 指定選用參數
<a name="UpdateItemLowLevelDotNETOptions"></a>

您也可以使用 `UpdateItemRequest` 物件提供選用參數，如以下 C\$1 範例所示。它會指定以下選用參數：
+ `ExpressionAttributeValues` 和 `ConditionExpression` 指定只有當現有價格為 20.00 時才更新價格。
+ `ReturnValues` 參數，其會請求回應中的更新項目。

**Example**  

```
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](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html)。

## 原子計數器
<a name="AtomicCounterLowLevelDotNet"></a>

您可以使用 `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);
```

## 刪除項目
<a name="DeleteMidLevelDotNet"></a>

`DeleteItem` 方法會從資料表刪除項目。

以下是使用低階 .NET 軟體開發套件 API 來刪除項目的步驟。

1. 建立 `AmazonDynamoDBClient` 類別的執行個體。

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

    若要刪除項目，需要有資料表名稱及項目的主索引鍵。

1. 提供您在前一個步驟中建立的 `DeleteItem` 物件來執行 `DeleteItemRequest` 方法。

**Example**  

```
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);
```

### 指定選用參數
<a name="DeleteItemLowLevelDotNETOptions"></a>

您也可以使用 `DeleteItemRequest` 物件提供選用參數，如以下 C\$1 程式碼範例所示。它會指定以下選用參數：
+ `ExpressionAttributeValues` 和 `ConditionExpression` 指定只有不再發行的書籍項目才可刪除 (InPublication 屬性值為 false)。
+ `ReturnValues` 參數，其會請求回應中的刪除項目。

**Example**  

```
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](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteItem.html)。

## 批次寫入：放入和刪除多個項目
<a name="BatchWriteLowLevelDotNet"></a>

*批次寫入*表示在一個批次中放入和刪除多個項目。您可利用 `BatchWriteItem` 方法，在單一呼叫中對來自一或多個資料表的多個項目執行放入與刪除操作。以下是使用低階 .NET 開發套件 API 來擷取多個項目的步驟。

1. 建立 `AmazonDynamoDBClient` 類別的執行個體。

1. 透過建立 `BatchWriteItemRequest` 類別的執行個體來說明所有的放入與刪除操作。

1. 提供您在前一個步驟中建立的 `BatchWriteItem` 物件來執行 `BatchWriteItemRequest` 方法。

1. 處理回應。您應該檢查回應中是否傳回任何未經處理的請求項目。如果您達到佈建輸送量配額或遇到一些其他暫時性錯誤，就可能發生這個狀況。此外，DynamoDB 會限制您在請求中指定的請求大小及操作次數。如果您超出這些限制，DynamoDB 會拒絕此請求。如需詳細資訊，請參閱 [BatchWriteItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html)。

下列 C\$1 程式碼範例示範前述步驟。範例會建立 `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);
```

如需運作範例，請參閱 [範例：使用 適用於 .NET 的 AWS SDK 低階 API 的批次操作](batch-operation-lowlevel-dotnet.md)。

## 批次取得：取得多個項目
<a name="BatchGetLowLevelDotNet"></a>

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

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

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

1. 建立 `AmazonDynamoDBClient` 類別的執行個體。

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

   若要擷取多個項目，需要有資料表名稱及主索引鍵值的清單。

1. 提供您在前一個步驟中建立的 `BatchGetItem` 物件來執行 `BatchGetItemRequest` 方法。

1. 處理回應。您應該檢查是否有任何未經處理的索引鍵，如果您達到佈建輸送量配額或遇到一些其他暫時性錯誤，就可能發生這個狀況。

下列 C\$1 程式碼範例示範前述步驟。範例會從 `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);
}
```



### 指定選用參數
<a name="BatchGetItemLowLevelDotNETOptions"></a>

您也可以使用 `BatchGetItemRequest` 物件提供選用參數，如以下 C\$1 程式碼範例所示。範例會從 `Forum` 表擷取兩個項目。它指定以下選用參數：
+  `ProjectionExpression` 參數會指定要擷取的屬性。

**Example**  

```
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](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchGetItem.html)。