BatchGetItem - Amazon DynamoDB

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

BatchGetItem

중요

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

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

설명

BatchGetItem 작업은 기본 키를 사용하여 여러 테이블에서 다수의 항목에 대한 속성을 반환합니다. 단일 작업에서 가져올 수 있는 최대 항목 수는 100개입니다. 또한 가져오는 항목 크기도 1MB로 제한됩니다. 응답 크기 제한을 벗어났거나, 테이블의 프로비저닝된 처리량을 초과하거나 내부 처리 오류가 발생하여 일부 결과만 반환되는 경우에는 DynamoDB가 UnprocessedKeys 값을 반환합니다. 그러면 다음 항목을 가져올 때 작업을 다시 시도할 수 있습니다. DynamoDB는 이러한 제한을 유지하기 위해 페이지당 반환되는 항목 수를 자동으로 조정합니다. 예를 들어 항목 100개를 가져오려고 해도 각 항목 크기가 50KB라면 시스템은 20개와 해당하는 UnprocessedKeys 값만 반환합니다. 따라서 다음 페이지에서 결과를 확인할 수 있습니다. 원한다면 애플리케이션에 자체 로직을 추가하여 결과 페이지를 단일 집합으로 어셈블할 수 있습니다.

요청에 포함된 각 테이블마다 프로비저닝 처리량이 부족하여 처리할 수 있는 항목이 없을 경우에는 DynamoDB가 ProvisionedThroughputExceededException 오류를 반환합니다.

참고

기본적으로 BatchGetItem는 요청에 속한 모든 테이블에 최종적 일관된 읽기(Eventually Consistent Read)를 실행합니다. 그렇지 않고 consistent read를 원할 때는 테이블마다 ConsistentRead 파라미터를 true로 설정할 수 있습니다.

BatchGetItem 은 항목을 병렬 방식으로 가져오기 때문에 응답 지연 시간을 최소화합니다.

애플리케이션을 설계할 때 DynamoDB는 반환되는 응답에서 속성의 순서 방식을 보장하지 않습니다. 따라서 항목 별로 응답을 구문 분석하려면 요청 항목마다 AttributesToGet에 기본 키 값을 추가해야 합니다.

요청된 항목이 존재하지 않으면 해당 항목 응답에서는 아무것도 반환되지 않습니다. 존재하지 않는 항목에 대한 요청은 읽기 형식에 따라 최소 읽기 용량 단위를 사용합니다. 자세한 정보는 DynamoDB 항목 크기 및 형식을 참조하십시오.

요청

구문

// 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": {"Table1": {"Keys": [{"HashKeyElement": {"S":"KeyValue1"}, "RangeKeyElement":{"N":"KeyValue2"}}, {"HashKeyElement": {"S":"KeyValue3"}, "RangeKeyElement":{"N":"KeyValue4"}}, {"HashKeyElement": {"S":"KeyValue5"}, "RangeKeyElement":{"N":"KeyValue6"}}], "AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]}, "Table2": {"Keys": [{"HashKeyElement": {"S":"KeyValue4"}}, {"HashKeyElement": {"S":"KeyValue5"}}], "AttributesToGet": ["AttributeName4", "AttributeName5", "AttributeName6"] } } }
이름 설명 필수
RequestItems

기본 키로 가져올 테이블 이름과 해당 항목의 컨테이너. 항목 요청 시 각 테이블 이름은 작업당 한 번만 불러올 수 있습니다.

유형: String

기본값: None

Table

가져올 항목이 저장되어 있는 테이블 이름. 이 엔트리는 레이블이 없는 기존 테이블을 지정하는 단순 문자열입니다.

유형: String

기본값: None

Table:Keys

지정 테이블의 항목을 정의하는 기본 키 값. 기본 키에 대한 자세한 내용은 프라이머리 키 단원을 참조하세요.

형식: 키

Table:AttributesToGet

지정 테이블에 속한 속성 이름 배열. 속성 이름을 지정하지 않으면 모든 속성이 반환됩니다. 일부 속성을 찾을 수 없는 경우 결과에 표시되지 않습니다.

형식: 배열

아니요
Table:ConsistentRead

true로 설정하면 consistent read가 발생하고, 그 밖의 경우에는 eventually consistent가 사용됩니다.

유형: Boolean

아니요

응답

구문

HTTP/1.1 200 x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375 content-type: application/x-amz-json-1.0 content-length: 855 {"Responses": {"Table1": {"Items": [{"AttributeName1": {"S":"AttributeValue"}, "AttributeName2": {"N":"AttributeValue"}, "AttributeName3": {"SS":["AttributeValue", "AttributeValue", "AttributeValue"]} }, {"AttributeName1": {"S": "AttributeValue"}, "AttributeName2": {"S": "AttributeValue"}, "AttributeName3": {"NS": ["AttributeValue", "AttributeValue", "AttributeValue"]} }], "ConsumedCapacityUnits":1}, "Table2": {"Items": [{"AttributeName1": {"S":"AttributeValue"}, "AttributeName2": {"N":"AttributeValue"}, "AttributeName3": {"SS":["AttributeValue", "AttributeValue", "AttributeValue"]} }, {"AttributeName1": {"S": "AttributeValue"}, "AttributeName2": {"S": "AttributeValue"}, "AttributeName3": {"NS": ["AttributeValue", "AttributeValue","AttributeValue"]} }], "ConsumedCapacityUnits":1} }, "UnprocessedKeys": {"Table3": {"Keys": [{"HashKeyElement": {"S":"KeyValue1"}, "RangeKeyElement":{"N":"KeyValue2"}}, {"HashKeyElement": {"S":"KeyValue3"}, "RangeKeyElement":{"N":"KeyValue4"}}, {"HashKeyElement": {"S":"KeyValue5"}, "RangeKeyElement":{"N":"KeyValue6"}}], "AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]} } }
이름 설명
Responses

테이블 이름과 테이블의 각 항목 속성.

유형: 맵

Table

항목이 저장되어 있는 테이블 이름. 이 엔트리는 레이블이 없는 테이블을 지정하는 단순 문자열입니다.

유형: String

Items

작업 파라미터를 만족하는 속성 이름과 값이 저장되는 컨테이너.

형식: 속성 이름 맵과 속성의 데이터 형식 및 값.

ConsumedCapacityUnits

각 테이블마다 사용되는 읽기 용량 단위 수. 이 값은 할당 처리량에 적용되는 수를 나타냅니다. 존재하지 않는 항목에 대한 요청은 읽기 형식에 따라 최소 읽기 용량 단위를 사용합니다. 자세한 내용은 DynamoDB 프로비저닝된 용량 테이블의 설정 관리 단원을 참조하세요.

형식: 숫자

UnprocessedKeys

응답 크기 제한에 걸려 현재 응답에서 처리되지 않은 테이블 배열과 각 테이블 키가 저장됩니다. UnprocessedKeys 값은 RequestItems 파라미터와 동일한 형태가 됩니다(따라서 이 값을 이어지는 BatchGetItem 작업에 직접 입력해도 됩니다). 자세한 내용은 위의 RequestItems 파라미터를 참조하세요.

형식: 배열

UnprocessedKeys: Table: Keys

항목, 그리고 항목과 연동된 속성을 정의하는 기본 키 속성 값. 기본 키에 대한 자세한 내용은 프라이머리 키 단원을 참조하세요.

형식: 속성 이름-값 페어의 배열.

UnprocessedKeys: Table: AttributesToGet

지정 테이블에 속한 속성 이름. 속성 이름을 지정하지 않으면 모든 속성이 반환됩니다. 일부 속성을 찾을 수 없는 경우 결과에 표시되지 않습니다.

형식: 속성 이름 배열.

UnprocessedKeys: Table: ConsistentRead

true로 설정하면 지정 테이블에 consistent read가 사용되고, 그렇지 않으면 최종적 일관된 읽기(Eventually Consistent Read)가 사용됩니다.

유형: 부울.

특수 오류

오류 설명
ProvisionedThroughputExceededException

할당이 허용되는 최대 처리량을 초과하였습니다.

예시

다음은 BatchGetItem 작업을 사용해 HTTP POST 요청 및 응답을 나타낸 예제입니다. 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 content-length: 409 {"RequestItems": {"comp1": {"Keys": [{"HashKeyElement":{"S":"Casey"},"RangeKeyElement":{"N":"1319509152"}}, {"HashKeyElement":{"S":"Dave"},"RangeKeyElement":{"N":"1319509155"}}, {"HashKeyElement":{"S":"Riley"},"RangeKeyElement":{"N":"1319509158"}}], "AttributesToGet":["user","status"]}, "comp2": {"Keys": [{"HashKeyElement":{"S":"Julie"}},{"HashKeyElement":{"S":"Mingus"}}], "AttributesToGet":["user","friends"]} } }

샘플 응답

다음은 응답 예제입니다.

HTTP/1.1 200 OK x-amzn-RequestId: GTPQVRM4VJS792J1UFJTKUBVV4KQNSO5AEMVJF66Q9ASUAAJG content-type: application/x-amz-json-1.0 content-length: 373 Date: Fri, 02 Sep 2011 23:07:39 GMT {"Responses": {"comp1": {"Items": [{"status":{"S":"online"},"user":{"S":"Casey"}}, {"status":{"S":"working"},"user":{"S":"Riley"}}, {"status":{"S":"running"},"user":{"S":"Dave"}}], "ConsumedCapacityUnits":1.5}, "comp2": {"Items": [{"friends":{"SS":["Elisabeth", "Peter"]},"user":{"S":"Mingus"}}, {"friends":{"SS":["Dave", "Peter"]},"user":{"S":"Julie"}}], "ConsumedCapacityUnits":1} }, "UnprocessedKeys":{} }