# 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이 될 수 없습니다. 문자열과 이진 형식 속성 길이는 0보다 커야 합니다. 설정 유형 속성은 비어 있으면 안 됩니다. 값이 비어 있는 요청은 `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 | 이 파라미터를 사용하여 속성 이름-값 페어의 값이 존재할지 여부를 지정합니다.다음 JSON 표기법은 항목의 "Color" 속성이 없을 경우 해당 항목을 바꿉니다.<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>


****  

|  Error  |  설명  | 
| --- | --- | 
|  ConditionalCheckFailedException  | 조건부 확인이 실패했습니다. 예상 속성 값이 검색되지 않았습니다. | 
| ResourceNotFoundException  | 지정된 항목 또는 속성을 찾을 수 없습니다. | 

## 예시
<a name="API_PutItem_Examples"></a>

AWS SDK를 사용하는 예는 [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)