View a markdown version of this page

PutItem - Amazon DynamoDB
설명요청응답특수 오류예시관련 작업

PutItem

중요

이 단원에서 언급되는 API 버전 2011-12-05는 사용 중단되었으며 새 애플리케이션에 사용해서는 안 됩니다.

현재 하위 수준 API에 대한 설명서는 Amazon DynamoDB API 참조 섹션을 참조하세요.

설명

새 항목을 만들거나 이전 항목을 새 항목으로 바꿉니다(모든 속성 포함). 지정된 테이블에 동일한 기본 키를 지닌 항목이 이미 존재하는 경우 기존 항목이 새 항목으로 완전히 바뀝니다. 조건부 입력을 수행하거나(기본 키가 지정된 항목이 없는 경우 새 항목을 삽입합니다) 기존 항목에 특정 속성 값이 있는 경우 해당 항목을 교체할 수 있습니다.

속성 값은 null이 될 수 없습니다. 문자열과 이진 형식 속성 길이는 0보다 커야 합니다. 설정 유형 속성은 비어 있으면 안 됩니다. 값이 비어 있는 요청은 ValidationException으로 거부됩니다.

참고

새 항목이 기존의 항목을 대체하지 않도록 하려면 기본 키 속성 또는 속성에 대해 Exists로 설정된 false을 사용하여 조건부 입력 작업을 수행합니다.

PutItem 사용에 관한 자세한 내용은 DynamoDB의 항목 및 속성 작업 단원을 참조하세요.

요청

구문

// 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

항목에 대한 속성 맵으로서 항목을 정의하는 기본 키 값이 반드시 포함되어야 합니다. 항목에 대한 다른 속성 이름-값 페어가 제공될 수 있습니다. 기본 키에 대한 자세한 내용은 프라이머리 키 단원을 참조하세요.

형식: 속성 값에 대한 속성 이름의 맵.

 예
Expected

조건부 입력의 속성을 지정합니다. Expected 파라미터를 사용하면 속성 이름뿐만 아니라, DynamoDB에서 속성 값이 이미 존재하는지 또는 속성 값이 존재하며 이를 변경하기 전에 특정 값이 있는지 확인해야 하는지 여부를 제공할 수 있습니다.

형식: 존재하는 경우, 속성 값에 대한 속성 이름의 맵.

 아니요
Expected:AttributeName

조건부 입력에 대한 속성 이름입니다.

유형: 문자열

 아니요
Expected:AttributeName: ExpectedAttributeValue 이 파라미터를 사용하여 속성 이름-값 페어의 값이 존재할지 여부를 지정합니다.

다음 JSON 표기법은 항목의 "Color" 속성이 없을 경우 해당 항목을 바꿉니다.

"Expected" :
	{"Color":{"Exists":false}}

다음 JSON 표기법은 항목을 바꾸기 전에 이름이 "Color"인 속성의 기존 값이 "Yellow"인지 여부를 확인합니다.

"Expected" : 
	{"Color":{"Exists":true,{"Value":{"S":"Yellow"}}}

기본적으로 Expected 파라미터를 사용하고 Value를 제공하는 경우 DynamoDB는 속성이 존재하고 바꿀 현재 값이 있는 것으로 가정합니다. 따라서 {"Exists":true}가 내재되어 있으므로 지정하지 않아도 됩니다. 요청을 다음과 같이 줄일 수 있습니다.

"Expected" : 
	{"Color":{"Value":{"S":"Yellow"}}}
참고

확인할 속성 값이 없을 때 {"Exists":true}를 지정하면 DynamoDB는 오류를 반환합니다.

 아니요
ReturnValues

속성 이름-값 페어가 PutItem 요청으로 업데이트되기 전에 이를 가져오려면 이 파라미터를 사용합니다. 가능한 파라미터 값은 NONE(기본) 또는 ALL_OLD입니다. ALL_OLD가 지정되어 있으며 PutItem이 속성 이름-값 페어를 덮어쓴 경우, 이전 항목의 내용이 반환됩니다. 이 파라미터가 제공되지 않거나 NONE인 경우, 아무 것도 반환되지 않습니다.

유형: 문자열

 아니요

응답

구문

다음 구문 예는 요청에 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 프로비저닝된 용량 모드 섹션을 참조하세요.

형식: 숫자

특수 오류

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

예시

AWS SDK를 사용하는 예는 DynamoDB의 항목 및 속성 작업 단원을 참조하세요.

샘플 요청

// 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"
}

샘플 응답

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
}