BatchWriteItem - Amazon DynamoDB
설명요청응답특수 오류예제

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