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

# DeleteItem
<a name="API_DeleteItem_v20111205"></a>

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

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

依主索引鍵，刪除資料表中的單一項目。您可以執行條件式刪除操作，在項目存在或者項目具有預期的屬性值時予以刪除。

**注意**  
如果指定 `DeleteItem` 而沒有屬性或值，則會刪除項目的所有屬性。  
在未指定條件的情況下，`DeleteItem` 一律為等冪操作，在同一個項目或屬性上多次執行*不會*導致錯誤回應。  
條件式刪除僅能用於在符合特定條件時刪除項目和屬性。如果符合條件，DynamoDB 會執行刪除。反之則不會刪除項目。  
您可以在每次操作對一個屬性執行預期的條件式檢查。

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

### 語法
<a name="API_DeleteItem_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.DeleteItem 
content-type: application/x-amz-json-1.0 

{"TableName":"Table1",
    "Key":
        {"HashKeyElement":{"S":"AttributeValue1"},"RangeKeyElement":{"N":"AttributeValue2"}},
    "Expected":{"AttributeName3":{"Value":{"S":"AttributeValue3"}}},
    "ReturnValues":"ALL_OLD"}
}
```


****  

|  名稱  |  描述  |  必要 | 
| --- | --- | --- | 
|  TableName  |  包含要刪除項目的資料表名稱。 類型：字串  |  是  | 
|  Key  | 定義項目的主索引鍵。如需主索引鍵的詳細資訊，請參閱 [主索引鍵](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey)。類型：`HashKeyElement` 對其值的映射和 `RangeKeyElement` 對其值的映射。 | 是 | 
| 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  | 如果要在刪除前取得屬性名稱值組，請使用此參數。可能的參數值為 `NONE` (預設) 或 `ALL_OLD`。如果指定 `ALL_OLD`，則會傳回舊項目的內容。如果未提供此參數，或者參數為 `NONE`，則不會傳回任何內容。類型：字串 | 否 | 

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

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

```
HTTP/1.1 200 OK
x-amzn-RequestId: CSOC7TJPLR0OOKIRLGOHVAICUFVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 353
Date: Tue, 12 Jul 2011 21:31:03 GMT

{"Attributes":
    {"AttributeName3":{"SS":["AttributeValue3","AttributeValue4","AttributeValue5"]},
    "AttributeName2":{"S":"AttributeValue2"},
    "AttributeName1":{"N":"AttributeValue1"}
    },
"ConsumedCapacityUnits":1
}
```


****  

|  名稱  |  描述  | 
| --- | --- | 
|  Attributes  | 如果 `ReturnValues` 參數在請求中提供為 `ALL_OLD`，則 DynamoDB 會傳回屬性名稱值組陣列 (本質上為已刪除項目)。反之則會在回應包含空集合。類型：屬性名稱值組陣列。 | 
| ConsumedCapacityUnits | 操作所使用的寫入容量單位數目。此值顯示套用至佈建輸送量的數字。刪除不存在項目上的請求會使用 1 個寫入容量單位。如需更多資訊，請參閱[DynamoDB 佈建容量模式](provisioned-capacity-mode.md)。 類型：數字 | 

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


****  

|  錯誤  |  描述  | 
| --- | --- | 
|  ConditionalCheckFailedException  | 條件式檢查失敗。找不到預期的屬性值。 | 

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

### 請求範例
<a name="API_DeleteItem_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.DeleteItem 
content-type: application/x-amz-json-1.0

{"TableName":"comp-table",
    "Key":
        {"HashKeyElement":{"S":"Mingus"},"RangeKeyElement":{"N":"200"}},
    "Expected":
        {"status":{"Value":{"S":"shopping"}}},
    "ReturnValues":"ALL_OLD"
}
```

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

```
HTTP/1.1 200 OK
x-amzn-RequestId: U9809LI6BBFJA5N2R0TB0P017JVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 353
Date: Tue, 12 Jul 2011 22:31:23 GMT

{"Attributes":
    {"friends":{"SS":["Dooley","Ben","Daisy"]},
    "status":{"S":"shopping"},
    "time":{"N":"200"},
    "user":{"S":"Mingus"}
    },
"ConsumedCapacityUnits":1
}
```

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