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

# PutItem
<a name="API_PutItem_v20111205"></a>

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

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

建立新項目，或以新項目取代舊項目 (包括全部屬性)。如果具有相同主索引鍵的指定資料表中已存在某項目，則新項目會完全取代現有項目。您可以執行條件式放置 (如果具有所指定主索引鍵的項目不存在，則插入新項目)，或者在現有項目具有某些屬性值時取代項目。

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

**注意**  
若要確保新項目不會取代現有項目，請使用條件式放置操作，針對主索引鍵屬性或屬性將 `Exists` 設定為 `false`。

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

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

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

{"TableName":"Table1",
    "Item":{
        "AttributeName1":{"S":"AttributeValue1"},
        "AttributeName2":{"N":"AttributeValue2"},
        "AttributeName5":{"B":"dmFsdWU="}
    },
    "Expected":{"AttributeName3":{"Value": {"S":"AttributeValue"}, "Exists":Boolean}},
    "ReturnValues":"ReturnValuesConstant"}
```


****  

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

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

### 語法
<a name="API_PutItem_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: 85

{"Attributes":
	{"AttributeName3":{"S":"AttributeValue3"},
	"AttributeName2":{"SS":"AttributeValue2"},
	"AttributeName1":{"SS":"AttributeValue1"},
	},
"ConsumedCapacityUnits":1
}
```


****  

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

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


****  

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

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

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

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

{"TableName":"comp5",
	"Item":
		{"time":{"N":"300"},
		"feeling":{"S":"not surprised"},
		"user":{"S":"Riley"}
		},
	"Expected":
		{"feeling":{"Value":{"S":"surprised"},"Exists":true}}
	"ReturnValues":"ALL_OLD"
}
```

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

```
HTTP/1.1 200 
x-amzn-RequestId: 8952fa74-71e9-11e0-a498-71d736f27375 
content-type: application/x-amz-json-1.0
content-length: 84

{"Attributes":
	{"feeling":{"S":"surprised"},
	"time":{"N":"300"},
	"user":{"S":"Riley"}},
"ConsumedCapacityUnits":1
}
```

## 相關動作
<a name="API_PutItem_Related_Actions"></a>
+  [UpdateItem](API_UpdateItem_v20111205.md) 
+  [DeleteItem](API_DeleteItem_v20111205.md) 
+  [GetItem](API_GetItem_v20111205.md) 
+  [BatchGetItem](API_BatchGetItem_v20111205.md)