Amazon DynamoDB
开发人员指南 (API Version 2012-08-10)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。点 击 Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

DynamoDB 低级 API

DynamoDB 低级 API 是 Amazon DynamoDB 的协议级接口。在此级别,每个 HTTP(S) 请求的格式必须正确并带有有效的数字签名。

AWS 开发工具包代表您构建低级 DynamoDB API 请求并处理来自 DynamoDB 的响应。这可让您专注于应用程序逻辑而不是低级详细信息。不过,您仍可通过大致了解低级 DynamoDB API 的工作方式获益。

有关低级 DynamoDB API 的更多信息,请参阅 Amazon DynamoDB API Reference

注意

DynamoDB 流 具有自己的低级 API,此 API 独立于 DynamoDB 的低级 API 且完全受 AWS 开发工具包支持。

有关更多信息,请参阅 使用 DynamoDB 流 捕获表活动。有关低级 DynamoDB 流 API,请参阅 DynamoDB 流 API 参考

低级 DynamoDB API 使用 JavaScript 对象表示法 (JSON) 作为通信协议格式。JSON 以层次结构的方式呈现数据,因此可同时传递数据值和数据结构。名称/值对以 name:value 格式定义。数据层次结构通过名称/值对的嵌套括号方式来定义。

DynamoDB 只将 JSON 用作传输协议而非存储格式。AWS 开发工具包使用 JSON 将数据发送到 DynamoDB,DynamoDB 通过 JSON 进行响应,但 DynamoDB 不以 JSON 格式持续存储数据。

注意

有关 JSON 的更多信息,请参阅 JSON.org 网站上的 JSON 简介

请求格式

DynamoDB 低级 API 接受 HTTP(S) POST 请求作为输入。AWS 开发工具包为您构建这些请求。

假设您有一个名为 Pets 的表和一个包含 AnimalType (分区键) 和 Name (排序键) 的键架构。这两个属性的类型为字符串。为了从 Pets 中检索项目,AWS 开发工具包构建了一个请求,如下所示:

Copy
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) 响应负载包含来自操作的结果,如以下示例所示:

Copy
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 开发工具包会将响应数据返回给应用程序以供进一步的处理。

注意

如果 DynamoDB 无法处理请求,它会返回 HTTP 错误代码和消息。AWS 开发工具包会以异常形式将这些错误代码和消息传播到应用程序。有关更多信息,请参阅 错误处理

数据类型描述符

低级 DynamoDB API 协议要求每个属性均带有数据类型描述符。数据类型描述符 是告知 DynamoDB 如何解释每个属性的令牌。

请求格式响应格式中的示例说明了如何使用数据类型描述符。GetItem 请求为字符串类型的 Pets 键架构属性 (AnimalTypeName) 指定 SGetItem 响应包含一个 Pets 项目,该项目带有字符串 (S)、数字 (N)、映射 (M) 和列表 (L) 类型的属性。

以下是 DynamoDB 数据类型描述符的完整列表:

  • S – 字符串

  • N – 数字

  • B – 二进制

  • BOOL – 布尔值

  • NULL – Null

  • M – 映射

  • L – 列表

  • SS – 字符串集

  • NN – 数字集

  • BB – 二进制集

注意

有关 DynamoDB 数据类型的详细描述,请参阅数据类型

数字数据

不同的编程语言提供对 JSON 的不同级别的支持。在某些情况下,您可能会决定使用第三方库来验证和分析 JSON 文档。

一些第三方库基于 JSON 数字类型而构建,并提供它们自己的类型,例如 intlongdouble。但是,DynamoDB 中的本机数字数据类型不能精确映射到其他数据类型,因此这些类型区别会造成冲突。此外,很多 JSON 库不能处理固定精度的数字,它们会将包含小数点的数字序列自动推断为双精度数据类型。

为了解决这些问题,DynamoDB 提供了不会造成数据丢失的单一数字类型。为了避免不必要的双精度值隐式转化,DynamoDB 将字符串用于数字值的数据传输。此方法可以灵活地更新属性值,同时能够保证排序语义的正确性,例如将“01”、“2”和“03”值按适当的顺序排列。

如果数字精度对您的应用程序十分重要,您应该先将数字值转换为字符串,然后再将它们传递到 DynamoDB。

二进制数据

DynamoDB 支持二进制属性。但是,JSON 不支持在本地编码二进制数据。要在请求中发送二进制数据,您需要将其编码为 Base64 格式。收到请求后,DynamoDB 会将 Base64 数据解码回二进制数据。

Internet Engineering Task Force (IETF) 网站上的 RFC 4648 中描述了 DynamoDB 使用的 Base64 编码方案。