# BatchGetItem
**중요**
***이 단원에서 언급되는 API 버전 2011-12-05는 사용 중단되었으며 새 애플리케이션에 사용해서는 안 됩니다.***
**현재 하위 수준 API에 대한 설명서는 [Amazon DynamoDB API 참조](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/) 섹션을 참조하세요.**
## 설명
`BatchGetItem` 작업은 기본 키를 사용하여 여러 테이블에서 다수의 항목에 대한 속성을 반환합니다. 단일 작업에서 가져올 수 있는 최대 항목 수는 100개입니다. 또한 가져오는 항목 크기도 1MB로 제한됩니다. 응답 크기 제한을 벗어났거나, 테이블의 프로비저닝된 처리량을 초과하거나 내부 처리 오류가 발생하여 일부 결과만 반환되는 경우에는 DynamoDB가 `UnprocessedKeys` 값을 반환합니다. 그러면 다음 항목을 가져올 때 작업을 다시 시도할 수 있습니다. DynamoDB는 이러한 제한을 유지하기 위해 페이지당 반환되는 항목 수를 자동으로 조정합니다. 예를 들어 항목 100개를 가져오려고 해도 각 항목 크기가 50KB라면 시스템은 20개와 해당하는 `UnprocessedKeys` 값만 반환합니다. 따라서 다음 페이지에서 결과를 확인할 수 있습니다. 원한다면 애플리케이션에 자체 로직을 추가하여 결과 페이지를 단일 집합으로 어셈블할 수 있습니다.
요청에 포함된 각 테이블마다 프로비저닝 처리량이 부족하여 처리할 수 있는 항목이 없을 경우에는 DynamoDB가 `ProvisionedThroughputExceededException` 오류를 반환합니다.
**참고**
기본적으로 `BatchGetItem`는 요청에 속한 모든 테이블에 최종적 일관된 읽기(Eventually Consistent Read)를 실행합니다. 그렇지 않고 consistent read를 원할 때는 테이블마다 `ConsistentRead` 파라미터를 `true`로 설정할 수 있습니다.
`BatchGetItem` 은 항목을 병렬 방식으로 가져오기 때문에 응답 지연 시간을 최소화합니다.
애플리케이션을 설계할 때 DynamoDB는 반환되는 응답에서 속성의 순서 방식을 보장하지 않습니다. 따라서 항목 별로 응답을 구문 분석하려면 요청 항목마다 `AttributesToGet`에 기본 키 값을 추가해야 합니다.
요청된 항목이 존재하지 않으면 해당 항목 응답에서는 아무것도 반환되지 않습니다. 존재하지 않는 항목에 대한 요청은 읽기 형식에 따라 최소 읽기 용량 단위를 사용합니다. 자세한 내용은 [DynamoDB 항목 크기 및 형식](CapacityUnitCalculations.md) 단원을 참조하십시오.
## 요청
### 구문
```
// 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 | 기본 키로 가져올 테이블 이름과 해당 항목의 컨테이너. 항목 요청 시 각 테이블 이름은 작업당 한 번만 불러올 수 있습니다.유형: 문자열 기본값: None | 예 |
| Table | 가져올 항목이 저장되어 있는 테이블 이름. 이 엔트리는 레이블이 없는 기존 테이블을 지정하는 단순 문자열입니다. 유형: 문자열 기본값: None | 예 |
| Table:Keys | 지정 테이블의 항목을 정의하는 기본 키 값. 기본 키에 대한 자세한 내용은 [프라이머리 키](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey) 단원을 참조하세요. 형식: 키 | 예 |
| Table:AttributesToGet | 지정 테이블에 속한 속성 이름 배열. 속성 이름을 지정하지 않으면 모든 속성이 반환됩니다. 일부 속성을 찾을 수 없는 경우 결과에 표시되지 않습니다. 유형: 배열 | 아니요 |
| Table:ConsistentRead | `true`로 설정하면 consistent read가 발생하고, 그 밖의 경우에는 eventually consistent가 사용됩니다. 타입: 부울 | 아니요 |
## 응답
### 구문
```
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 | 항목이 저장되어 있는 테이블 이름. 이 엔트리는 레이블이 없는 테이블을 지정하는 단순 문자열입니다.유형: 문자열 |
| Items | 작업 파라미터를 만족하는 속성 이름과 값이 저장되는 컨테이너.형식: 속성 이름 맵과 속성의 데이터 형식 및 값. |
| ConsumedCapacityUnits | 각 테이블마다 사용되는 읽기 용량 단위 수. 이 값은 할당 처리량에 적용되는 수를 나타냅니다. 존재하지 않는 항목에 대한 요청은 읽기 형식에 따라 최소 읽기 용량 단위를 사용합니다. 자세한 정보는 [DynamoDB 프로비저닝된 용량 모드](provisioned-capacity-mode.md) 섹션을 참조하세요. 형식: 숫자 |
| UnprocessedKeys | 응답 크기 제한에 걸려 현재 응답에서 처리되지 않은 테이블 배열과 각 테이블 키가 저장됩니다. `UnprocessedKeys` 값은 `RequestItems` 파라미터와 동일한 형태가 됩니다(따라서 이 값을 이어지는 `BatchGetItem` 작업에 직접 입력해도 됩니다). 자세한 내용은 위의 `RequestItems` 파라미터를 참조하세요.유형: 배열 |
| UnprocessedKeys: Table: Keys | 항목, 그리고 항목과 연동된 속성을 정의하는 기본 키 속성 값. 기본 키에 대한 자세한 내용은 [프라이머리 키](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey) 단원을 참조하세요.형식: 속성 이름-값 페어의 배열. |
| UnprocessedKeys: Table: AttributesToGet | 지정 테이블에 속한 속성 이름. 속성 이름을 지정하지 않으면 모든 속성이 반환됩니다. 일부 속성을 찾을 수 없는 경우 결과에 표시되지 않습니다. 형식: 속성 이름 배열. |
| UnprocessedKeys: Table: ConsistentRead | `true`로 설정하면 지정 테이블에 consistent read가 사용되고, 그렇지 않으면 최종적 일관된 읽기(Eventually Consistent Read)가 사용됩니다. 유형: 부울. |
## 특수 오류
****
| Error | 설명 |
| --- | --- |
| ProvisionedThroughputExceededException | 할당이 허용되는 최대 처리량을 초과하였습니다. |
## 예시
다음은 BatchGetItem 작업을 사용해 HTTP POST 요청 및 응답을 나타낸 예제입니다. AWS SDK를 사용하는 예는 [DynamoDB의 항목 및 속성 작업](WorkingWithItems.md) 단원을 참조하세요.
### 샘플 요청
다음은 두 가지 다른 테이블에서 속성을 요청하는 예제입니다.
```
// 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":{}
}
```