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

# UpdateItem
<a name="API_UpdateItem_v20111205"></a>

**重要**  
***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。***  
 **如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**

## 描述
<a name="API_UpdateItem_Description"></a>

編輯現有項目的屬性。您可以執行條件式更新 (在新的屬性名稱值組不存在時插入新的，或者在現有名稱值組具有某些預期的屬性值時將其取代)。

**注意**  
您無法使用 UpdateItem 更新主索引鍵屬性。但您可以刪除項目並使用 PutItem 建立具有新屬性的新項目。

UpdateItem 操作包含 `Action` 參數，該參數定義如何執行更新。您可以放入、刪除或新增屬性值。

屬性值不得為 Null；字串和二進位類型屬性的長度必須大於零；集合類型屬性不可為空白。具有空值的請求會遭到拒絕，並出現 `ValidationException`。

如果現有項目具有指定的主索引鍵：
+ **PUT：**新增指定的屬性。如果屬性存在，則會以新值取代。
+ **DELETE：**如果未指定任何值，則會移除屬性及其值。如果有指定一組值，則所指定集合中的值將從舊集合中移除。因此，如果屬性值包含 [a、b、c]，而刪除動作包含 [a、c]，則最後屬性值為 [b]。指定值類型必須符合現有值類型。指定空集合無效。
+ **ADD：**僅對數字使用新增動作，或者在目標屬性為集合 (包括字串集合) 時使用。如果目標屬性為單一字串值或純量二進位值，則 ADD 無法運作。指定的值會新增至數值 (現有的數值進行遞增或遞減)，或者新增為字串集合中的額外值。如果有指定一組值，則會將這些值新增至現有的集合中。例如，如果原始集合為 [1、2]，而提供的值為 [3]，則在新增操作之後，集合為 [1、2、3]，而非 [4、5]。如果已為集合屬性指定 Add 動作，且指定的屬性類型與現有集合類型不符，則會發生錯誤。

  如果對不存在的屬性使用 ADD，則會將屬性及其值新增至項目。

如果沒有項目符合所指定的主索引鍵：
+ **PUT：**建立具有指定主索引鍵的新項目。然後新增指定屬性。
+ **DELETE：**不進行任何動作。
+ **ADD：**建立具有提供的主索引鍵和屬性值數字 (或一組數字) 的項目。不適用於字串或二進位類型。

**注意**  
如果對更新前不存在的項目使用 `ADD` 增減數值，則 DynamoDB 會以 `0` 為初始值。此外，如果對更新前不存在的屬性 (但項目存在) 使用 `ADD` 增減數值來更新項目，則 DynamoDB 會以 `0` 為初始值。例如，您使用 `ADD` 將 `+3` 新增至更新前不存在的屬性。DynamoDB 使用 `0` 為初始值，而且更新後的值為 `3`。

如需使用此操作的詳細資訊，請參閱 [在 DynamoDB 使用項目和屬性](WorkingWithItems.md)。

## 請求
<a name="API_UpdateItem_RequestParameters"></a>

### 語法
<a name="API_UpdateItem_RequestParameters.syntax"></a>

```
// This header is abbreviated.
// For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.UpdateItem
content-type: application/x-amz-json-1.0

{"TableName":"Table1",
    "Key":
        {"HashKeyElement":{"S":"AttributeValue1"},
        "RangeKeyElement":{"N":"AttributeValue2"}},
    "AttributeUpdates":{"AttributeName3":{"Value":{"S":"AttributeValue3_New"},"Action":"PUT"}},
    "Expected":{"AttributeName3":{"Value":{"S":"AttributeValue3_Current"}}},
    "ReturnValues":"ReturnValuesConstant"
}
```


****  

|  名稱  |  描述  |  必要 | 
| --- | --- | --- | 
|  TableName  |  包含要更新項目的資料表的名稱。 類型：字串  |  是  | 
|  Key  | 定義項目的主索引鍵。如需主索引鍵的詳細資訊，請參閱 [主索引鍵](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey)。類型：`HashKeyElement` 對其值的映射和 `RangeKeyElement` 對其值的映射。 | 是 | 
| AttributeUpdates | 新值的屬性名稱映射以及更新動作。屬性名稱指定要修改的屬性，且不能包含任何主索引鍵屬性。類型：屬性名稱映射、值，以及屬性更新動作。 |  | 
| AttributeUpdates:Action | 指定如何執行更新。可能值：`PUT` (預設)、`ADD` 或 `DELETE`。語義會在 UpdateItem 描述中說明。類型：字串預設：`PUT` | 否 | 
| Expected  | 指定條件式更新的屬性。`Expected` 參數可讓您提供屬性名稱，以及 DynamoDB 是否應該檢查屬性值是否已存在；或者屬性值是否存在且在變更之前有特定值。類型：屬性名稱映射。 | 否 | 
| Expected:AttributeName  | 條件式放置的屬性的名稱。類型：字串 | 否 | 
| Expected:AttributeName: ExpectedAttributeValue | 使用此參數來指定屬性名稱值組的值是否已經存在。如果該項目的 Color (顏色) 屬性尚未存在，則下列 JSON 符號會更新項目：<pre>"Expected" :<br />	{"Color":{"Exists":false}}</pre>下列 JSON 符號會在更新項目之前檢查名為 Color (顏色) 的屬性是否具有現有值 Yellow (黃色)：<pre>"Expected" : <br />	{"Color":{"Exists":true},{"Value":{"S":"Yellow"}}}</pre>根據預設，如果使用 `Expected` 參數並提供 `Value`，DynamoDB 會假設屬性存在，且有要取代的目前值。所以您不必指定 `{"Exists":true}`，因為這是暗含的。您可以將請求縮短為：<pre>"Expected" : <br />	{"Color":{"Value":{"S":"Yellow"}}}</pre> 如果指定 `{"Exists":true}` 而無要檢查的屬性值，則 DynamoDB 會傳回錯誤。  | 否 | 
| ReturnValues  | 如果想在以 `UpdateItem` 請求更新屬性名稱值組之前取得屬性名稱值組，則請使用此參數。可能的參數值為 `NONE` (預設) 或者 `ALL_OLD`、`UPDATED_OLD`、`ALL_NEW` 或 `UPDATED_NEW`。如果已指定 `ALL_OLD`，且 `UpdateItem` 覆寫屬性名稱值組，則會傳回舊項目的內容。如果未提供此參數，或者參數為 `NONE`，則不會傳回任何內容。如果指定 `ALL_NEW`，則會傳回項目新版本的所有屬性。如果指定 `UPDATED_NEW`，則只會傳回已更新屬性的新版本。類型：字串 | 否 | 

## 回應
<a name="API_UpdateItem_CommonResponseElements"></a>

### 語法
<a name="API_UpdateItem_CommonResponseElements.syntax"></a>

下列語法範例假設請求指定 `ALL_OLD` 的 `ReturnValues` 參數，反之則回應只有 `ConsumedCapacityUnits` 元素。

```
HTTP/1.1 200 
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375 
content-type: application/x-amz-json-1.0
content-length: 140

{"Attributes":{
	"AttributeName1":{"S":"AttributeValue1"},
	"AttributeName2":{"S":"AttributeValue2"},
	"AttributeName3":{"S":"AttributeValue3"},
	"AttributeName5":{"B":"dmFsdWU="}
	},
"ConsumedCapacityUnits":1
}
```


****  

|  名稱  |  描述  | 
| --- | --- | 
|  Attributes  | 屬性名稱值組映射，但僅限於 `ReturnValues` 參數在請求中被指定為 `NONE` 以外選項的情況。類型：屬性名稱值組映射。 | 
| ConsumedCapacityUnits | 操作所使用的寫入容量單位數目。此值顯示套用至佈建輸送量的數字。如需更多資訊，請參閱[DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。 類型：數字 | 

## 特殊錯誤
<a name="API_UpdateItem_SpecialErrors"></a>


****  

|  錯誤  |  描述  | 
| --- | --- | 
|  ConditionalCheckFailedException  | 條件式檢查失敗。屬性 ("\$1 name \$1") 值為 ("\$1 value \$1")，但預期為 ("\$1 expValue \$1")  | 
| ResourceNotFoundExceptions  | 找不到指定的項目或屬性。 | 

## 範例
<a name="API_UpdateItem_Examples"></a>

如需使用 AWS 開發套件的範例，請參閱 [在 DynamoDB 使用項目和屬性](WorkingWithItems.md)。

### 請求範例
<a name="API_UpdateItem_Examples_Request"></a>

```
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.UpdateItem
content-type: application/x-amz-json-1.0 

{"TableName":"comp5",
    "Key":
        {"HashKeyElement":{"S":"Julie"},"RangeKeyElement":{"N":"1307654350"}},
    "AttributeUpdates":
        {"status":{"Value":{"S":"online"},
        "Action":"PUT"}},
    "Expected":{"status":{"Value":{"S":"offline"}}},
    "ReturnValues":"ALL_NEW"
}
```

### 回應範例
<a name="API_UpdateItem_Examples_Response"></a>

```
HTTP/1.1 200 OK
x-amzn-RequestId: 5IMHO7F01Q9P7Q6QMKMMI3R3QRVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 121
Date: Fri, 26 Aug 2011 21:05:00 GMT

{"Attributes":
    {"friends":{"SS":["Lynda, Aaron"]},
    "status":{"S":"online"},
    "time":{"N":"1307654350"},
    "user":{"S":"Julie"}},
"ConsumedCapacityUnits":1
}
```

## 相關動作
<a name="API_UpdateItem_Related_Actions"></a>
+  [PutItem](API_PutItem_v20111205.md) 
+  [DeleteItem](API_DeleteItem_v20111205.md)