Amazon DynamoDB
개발자 안내서 (API 버전 2012-08-10)

DynamoDB하위 수준 API

Amazon DynamoDB 하위 수준 API는 DynamoDB의 프로토콜 수준 인터페이스입니다. 이 수준에서는 모든 HTTP(S) 요청이 올바른 형식이어야 하며, 유효한 디지털 서명이 있어야 합니다.

AWS SDK는 사용자를 대신하여 하위 수준 DynamoDB API 요청을 구성하고 DynamoDB의 응답을 처리합니다. 이로써 하위 수준 세부 사항 대신 애플리케이션 로직에 집중할 수 있습니다. 그러나 하위 수준 DynamoDB API의 원리에 대한 기본적 이해는 여전히 도움이 될 수 있습니다.

하위 수준 DynamoDB API에 대한 자세한 내용은 Amazon DynamoDB API Reference 단원을 참조하십시오.

참고

DynamoDB 스트림의 자체 하위 수준 API는 DynamoDB의 그것과 별개이며, AWS SDK가 전면 지원합니다.

자세한 내용은 DynamoDB 스트림를 사용하여 Table Activity 캡처하기 단원을 참조하십시오. 하위 수준 DynamoDB 스트림 API는 DynamoDB 스트림 API 레퍼런스 단원을 참조하십시오.

하위 수준 DynamoDB API는 JavaScript Object Notation(JSON)을 연결 프로토콜 형식으로 사용합니다. JSON은 데이터를 계층 구조로 나타내므로 데이터 값과 데이터 구조 모두 동시에 전달됩니다. 이름 값 페어는 name:value 형식으로 정의됩니다. 데이터 계층은 이름-값 페어의 중첩된 대괄호로 정의됩니다.

DynamoDB는 JSON을 오직 전송 프로토콜로 사용하며 스토리지 형식으로는 사용하지 않습니다. AWS SDK는 JSON을 사용하여 DynamoDB에 데이터를 보내고 DynamoDB는 JSON으로 응답합니다. DynamoDB는 데이터를 JSON 형식으로 지속적으로 저장하지 않습니다.

참고

JSON에 대한 자세한 내용은 JSON.org 웹 사이트에서 JSON 소개를 참조하십시오.

요청 형식

DynamoDB 하위 수준 API는 HTTP(S) POST 요청을 입력으로 받아들입니다. AWS SDK는 이 요청을 구성합니다.

AnimalType(파티션 키)과 Name(정렬 키)으로 구성된 키 스키마가 포함된 Pets라는 이름의 테이블이 있는 경우 이 두 가지 속성 모두 string 유형입니다. Pets에서 항목을 검색하기 위해 AWS SDK는 다음 요청을 구성합니다.

POST / HTTP/1.1 Host: dynamodb.<region>.<domain>; Accept-Encoding: identity Content-Length: <PayloadSizeBytes> User-Agent: <UserAgentString> Content-Type: application/x-amz-json-1.0 Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=<Headers>, Signature=<Signature> X-Amz-Date: <Date> X-Amz-Target: DynamoDB_20120810.GetItem { "TableName": "Pets", "Key": { "AnimalType": {"S": "Dog"}, "Name": {"S": "Fido"} } }

이 요청에 대해 다음을 참조하십시오.

  • Authorization 헤더에는 DynamoDB가 요청을 인증하는 데 필요한 정보가 포함되어 있습니다. 자세한 내용은 Amazon Web Services 일반 참조AWS API 요청 서명서명 버전 4 서명 프로세스를 참조하십시오.

  • X-Amz-Target 헤더에는 DynamoDB 작업의 이름인 GetItem이 포함되어 있습니다. (여기에 하위 API 버전(이 경우에는 20120810)도 포함됩니다.)

  • 요청의 페이로드(본문)에는 JSON 형식의 작업을 위한 파라미터가 포함되어 있습니다. GetItem 작업의 경우, 파라미터는 TableNameKey입니다.

응답 형식

DynamoDB는 요청을 수신하면 이를 처리하고 응답을 반환합니다. 이전에 나온 요청의 경우 다음 예제와 같이 HTTP(S) 응답 페이로드에 해당 작업 결과가 포함됩니다.

HTTP/1.1 200 OK x-amzn-RequestId: <RequestId> x-amz-crc32: <Checksum> Content-Type: application/x-amz-json-1.0 Content-Length: <PayloadSizeBytes> Date: <Date> { "Item": { "Age": {"N": "8"}, "Colors": { "L": [ {"S": "White"}, {"S": "Brown"}, {"S": "Black"} ] }, "Name": {"S": "Fido"}, "Vaccinations": { "M": { "Rabies": { "L": [ {"S": "2009-03-17"}, {"S": "2011-09-21"}, {"S": "2014-07-08"} ] }, "Distemper": {"S": "2015-10-13"} } }, "Breed": {"S": "Beagle"}, "AnimalType": {"S": "Dog"} } }

이때 AWS SDK는 추가 처리를 위해 애플리케이션에게 응답 데이터를 반환합니다.

참고

DynamoDB가 요청을 처리할 수 없는 경우 HTTP 오류 코드 및 메시지를 반환합니다. AWS SDK는 이를 예외 형식으로 애플리케이션에 전파합니다. 자세한 내용은 오류 처리 단원을 참조하십시오.

데이터 형식 서술자

하위 수준 DynamoDB API 프로토콜에서는 각 속성에 데이터 형식 서술자가 포함되어야 합니다. 데이터 형식 서술자는 DynamoDB에게 각 속성을 해석하는 방법을 알려 주는 토큰입니다.

요청 형식응답 형식의 예는 데이터 형식 서술자가 어떻게 사용되는지 보여 줍니다. GetItem 요청은 Pets 키 스키마 속성(AnimalTypeName)에 대해 S를 지정하며, 이는 string 유형입니다. GetItem 응답에는 속성이 string(S), number(N), map(M) 및 list(L) 유형인 Pets 항목이 포함되어 있습니다.

다음은 DynamoDB 데이터 형식 서술자의 완전한 목록입니다.

  • S – 문자열

  • N – 숫자

  • B – 이진수

  • BOOL – 부울

  • NULL – Null

  • M – 맵

  • L – 목록

  • SS – 문자열 집합

  • NS – 숫자 집합

  • BS – 이진수 집합

참고

DynamoDB 데이터 형식에 대한 자세한 내용은 데이터 형식 단원을 참조하십시오.

숫자 데이터

프로그래밍 언어마다 JSON 지원 수준이 다릅니다. 경우에 따라서는 JSON 문서를 확인하고 구문 분석하는 데 타사 라이브러리를 사용해야 할 수도 있습니다.

일부 타사 라이브러리는 JSON 숫자 형식을 기초로 int, long 또는 double 같은 자체 형식을 제공합니다. 그러나 DynamoDB의 기본 숫자 데이터 형식은 이러한 다른 데이터 형식에 정확히 매핑되지 않으므로 이러한 형식 구분은 충돌을 야기할 수 있습니다. 뿐만 아니라 많은 JSON 라이브러리는 고정 전체 자릿수 숫자 값을 처리하지 않으며, 소수점을 포함하는 숫자열의 double 데이터 형식을 자동으로 유추합니다.

DynamoDB는 이러한 문제를 해결하기 위해 데이터 손실이 없는 단일 숫자 형식을 제공합니다. 또한 사용자의 동의 없이 double 값으로 암시적으로 변환되는 것을 방지하기 위해 DynamoDB는 숫자 값의 데이터 전송에 문자열을 사용합니다. 이러한 접근 방식은 속성 값을 업데이트하는 데 유연성을 제공하는 동시에 "1", "2", "3"을 적절한 순서로 입력하는 등 적절한 정렬 의미 체계를 유지합니다.

애플리케이션에 숫자 전체 자릿수가 중요한 경우, DynamoDB로 전달하기 전에 숫자 값을 문자열로 변환해야 합니다.

이진 데이터

DynamoDB는 이진 속성을 지원합니다. 그러나 JSON은 이진 데이터 인코딩은 기본적으로 지원하지 않습니다. 요청에서 이진 데이터를 보내려면 Base64 형식으로 인코딩해야 합니다. DynamoDB는 요청을 받아 Base64를 다시 이진수로 디코딩합니다.

DynamoDB에서 사용되는 base64 인코딩 체계는 IETF(Internet Engineering Task Force) 웹 사이트의 RFC 4648에 설명되어 있습니다.