BatchWriteItem
중요
이 단원에서 언급되는 API 버전 2011-12-05는 사용 중단되었으며 새 애플리케이션에 사용해서는 안 됩니다.
현재 하위 수준 API에 대한 설명서는 Amazon DynamoDB API 참조 섹션을 참조하세요.
설명
이 작업을 사용하면 단일 호출로 여러 테이블에서 여러 항목을 추가하거나 삭제할 수 있습니다.
하나의 항목을 업로드하려면 PutItem
을 사용하고, 하나의 항목을 삭제하려면 DeleteItem
을 사용할 수 있습니다. 그러나 대용량의 데이터를 업로드하거나 삭제하려는 경우(예: Amazon EMR에서 대용량의 데이터를 업로드하거나 다른 데이터베이스의 데이터를 DynamoDB로 마이그레이션) BatchWriteItem
은 효과적인 대안을 제공합니다.
Java와 같은 언어를 사용하는 경우 스레드를 사용하여 항목을 동시에 업로드할 수 있습니다. 이는 애플리케이션의 스레드 처리를 복잡하게 합니다. 다른 언어는 스레딩을 지원하지 않습니다. 예를 들어 PHP를 사용하는 경우 한 번에 하나씩 항목을 업로드하거나 삭제해야 합니다. 두 경우 모두, BatchWriteItem
은 지정된 추가 및 삭제 작업이 동시에 처리되는 대안을 제공하여 스레드 풀 접근 방식을 제공하므로 애플리케이션을 복잡하게 하지 않습니다.
BatchWriteItem
작업에서 지정된 각각의 개별적 추가 및 삭제는 소비되는 용량 단위 기준으로는 동일하다는 점에 유의하세요. 다만 BatchWriteItem
이 지정된 작업을 동시에 수행하기 때문에 지연 시간은 줄어듭니다. 존재하지 않는 항목의 삭제 작업은 1 쓰기 용량 단위를 사용합니다. 사용되는 용량 단위에 대한 자세한 내용은 DynamoDB의 테이블 및 데이터 작업 단원을 참조하세요.
BatchWriteItem
을 사용하는 경우 다음 제한에 유의하세요.
-
단일 요청에서 최대 작업 - 총 최대 25개의 추가 또는 삭제 작업을 지정할 수 있습니다. 그러나 총 요청 크기는 1MB(HTTP 페이로드)를 초과할 수 없습니다.
-
항목을 추가 및 삭제하는 경우에만
BatchWriteItem
작업을 사용할 수 있습니다. 이 작업을 사용하여 기존 항목을 업데이트할 수 없습니다. -
원자성 작업이 아님 -
BatchWriteItem
에 지정된 개별 작업은 원자성입니다. 그러나BatchWriteItem
은 전체적으로 ‘최상의 노력’ 작업이며 원자성 작업이 아닙니다. 다시 말해BatchWriteItem
요청에서 일부 작업만 성공하고 다른 작업은 실패할 수 있습니다. 실패한 작업은 응답에서UnprocessedItems
필드로 반환됩니다. 실패 원인 중 일부는 테이블에 대해 구성된 할당된 처리량을 초과했거나 네트워크 오류와 같은 일시적 실패 때문일 수 있습니다. 요청을 조사하거나 선택적으로 재전송할 수 있습니다. 일반적으로BatchWriteItem
을 반복적으로 호출하고 반복될 때마다 처리되지 않은 항목을 확인한 다음, 그러한 항목을 포함시킨 새BatchWriteItem
요청을 제출합니다. -
항목을 반환하지 않음 -
BatchWriteItem
은 대용량의 데이터를 효율적으로 업로드하기 위한 것입니다. 그러나PutItem
및DeleteItem
에서 지원하는 일부 고급 작업을 제공하지 않습니다. 예를 들어DeleteItem
은 요청 본문의ReturnValues
필드를 지원하여 응답에서 삭제된 항목을 요청합니다.BatchWriteItem
작업은 응답에 항목을 반환하지 않습니다. -
PutItem
및DeleteItem
과는 달리BatchWriteItem
은 작업의 개별 쓰기 요청에 조건을 지정하도록 허용하지 않습니다. -
속성 값은 null이 될 수 없습니다. 문자열과 이진 형식 속성 길이는 0보다 커야 합니다. 설정 유형 속성은 비어 있으면 안 됩니다. 값이 비어 있는 요청은
ValidationException
으로 거부됩니다.
DynamoDB는 다음 중 하나가 true일 경우 전체 일괄 쓰기 작업을 거부합니다.
-
BatchWriteItem
요청에 지정된 하나 이상의 테이블이 존재하지 않는 경우. -
요청의 항목에 지정된 기본 키 속성이 해당하는 테이블의 기본 키 스키마와 일치하지 않는 경우.
-
동일한
BatchWriteItem
요청에서 동일한 항목에 대해 여러 작업을 수행하려는 경우. 예를 들어 동일한BatchWriteItem
요청에서 동일한 항목을 추가 및 삭제할 수 없습니다. -
총 요청 크기가 1MB 요청 크기(HTTP 페이로드) 제한을 초과하는 경우.
-
일괄의 개별 항목이 64KB 항목 크기 제한을 초과하는 경우.
요청
구문
// This header is abbreviated. For a sample of a complete header, see DynamoDB 하위 수준 API. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.BatchGetItem content-type: application/x-amz-json-1.0 { "RequestItems" : RequestItems } RequestItems { "
TableName1
" : [ Request, Request, ... ], "TableName2
" : [ Request, Request, ... ], ... } Request ::= PutRequest | DeleteRequest PutRequest ::= { "PutRequest" : { "Item" : { "Attribute-Name1
" : Attribute-Value, "Attribute-Name2
" : Attribute-Value, ... } } } DeleteRequest ::= { "DeleteRequest" : { "Key" : PrimaryKey-Value } } PrimaryKey-Value ::= HashTypePK | HashAndRangeTypePK HashTypePK ::= { "HashKeyElement" : Attribute-Value } HashAndRangeTypePK { "HashKeyElement" : Attribute-Value, "RangeKeyElement" : Attribute-Value, } Attribute-Value ::= String | Numeric| Binary | StringSet | NumericSet | BinarySet Numeric ::= { "N": "Number
" } String ::= { "S": "String
" } Binary ::= { "B": "Base64 encoded binary data
" } StringSet ::= { "SS": [ "String1
", "String2
", ... ] } NumberSet ::= { "NS": [ "Number1
", "Number2
", ... ] } BinarySet ::= { "BS": [ "Binary1
", "Binary2
", ... ] }
요청 본문에서 RequestItems
JSON 객체는 수행할 작업을 설명합니다. 작업은 테이블별로 그룹화됩니다. BatchWriteItem
을 사용하여 여러 테이블에서 여러 항목을 업데이트하거나 삭제할 수 있습니다. 각 쓰기 요청별로 작업에 대한 세부 정보 앞에 있는 요청 유형(PutItem
, DeleteItem
)을 확인해야 합니다.
-
PutRequest
의 경우, 항목, 즉 속성 및 해당 값 목록을 제공합니다. -
DeleteRequest
의 경우, 기본 키 이름과 값을 제공합니다.
응답
구문
다음은 응답에서 반환한 JSON 본문의 구문입니다.
{ "Responses" : ConsumedCapacityUnitsByTable "UnprocessedItems" : RequestItems } ConsumedCapacityUnitsByTable { "
TableName1
" : { "ConsumedCapacityUnits", :NumericValue
}, "TableName2
" : { "ConsumedCapacityUnits", :NumericValue
}, ... } RequestItems This syntax is identical to the one described in the JSON syntax in the request.
특수 오류
이 작업에는 특정 오류가 없습니다.
예제
다음 예에서는 HTTP POST 요청 및 BatchWriteItem
작업의 응답을 보여 줍니다. 이 요청은 Reply 및 Thread 테이블에서 다음 작업을 지정합니다.
-
Reply 테이블의 항목 추가 및 삭제
Thread 테이블로 항목 추가
AWS SDK를 사용하는 예는 항목 및 속성 작업 단원을 참조하세요.
샘플 요청
// This header is abbreviated. For a sample of a complete header, see DynamoDB 하위 수준 API. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.BatchGetItem content-type: application/x-amz-json-1.0 { "RequestItems":{ "Reply":[ { "PutRequest":{ "Item":{ "ReplyDateTime":{ "S":"2012-04-03T11:04:47.034Z" }, "Id":{ "S":"DynamoDB#DynamoDB Thread 5" } } } }, { "DeleteRequest":{ "Key":{ "HashKeyElement":{ "S":"DynamoDB#DynamoDB Thread 4" }, "RangeKeyElement":{ "S":"oops - accidental row" } } } } ], "Thread":[ { "PutRequest":{ "Item":{ "ForumName":{ "S":"DynamoDB" }, "Subject":{ "S":"DynamoDB Thread 5" } } } } ] } }
샘플 응답
다음 응답 예에서는 Thread 및 Reply 테이블에서 성공한 추가 작업 및 Reply 테이블에서 (테이블에서 할당된 처리량을 초과하는 경우 발생하는 병목 현상 등의 이유로) 실패한 삭제 작업을 보여 줍니다. JSON 응답에서 다음을 참고하세요.
-
Responses
객체는Thread
및Reply
테이블에서 성공적인 추가 작업의 결과로 이 두 테이블에서 1 용량 단위가 사용되었다는 것을 보여 줍니다. -
UnprocessedItems
객체는Reply
테이블에서 성공하지 못한 삭제 작업을 보여 줍니다. 새BatchWriteItem
호출을 발행하여 처리되지 않은 이러한 요청을 처리할 수 있습니다.
HTTP/1.1 200 OK x-amzn-RequestId: G8M9ANLOE5QA26AEUHJKJE0ASBVV4KQNSO5AEMVJF66Q9ASUAAJG Content-Type: application/x-amz-json-1.0 Content-Length: 536 Date: Thu, 05 Apr 2012 18:22:09 GMT { "Responses":{ "Thread":{ "ConsumedCapacityUnits":1.0 }, "Reply":{ "ConsumedCapacityUnits":1.0 } }, "UnprocessedItems":{ "Reply":[ { "DeleteRequest":{ "Key":{ "HashKeyElement":{ "S":"DynamoDB#DynamoDB Thread 4" }, "RangeKeyElement":{ "S":"oops - accidental row" } } } } ] } }