DynamoDB 低级 API - Amazon DynamoDB
请求格式响应格式数据类型描述符数值数据二进制数据

DynamoDB 低级 API

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

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

有关低级 DynamoDB API 的更多信息，请参阅Amazon DynamoDB API 参考。

注意

DynamoDB Streams 具有自己的低级别 API，此 API 独立于 DynamoDB 的低级别 API 且完全受 AWS SDK 支持。

有关更多信息，请参阅 将更改数据捕获用于 DynamoDB Streams。有关低级 DynamoDB Streams API，请参阅Amazon DynamoDB Streams API 参考。

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

DynamoDB 只将 JSON 用作传输协议而非存储格式。AWS SDK使用 JSON 将数据发送到 DynamoDB，DynamoDB 会通过 JSON 进行响应。DynamoDB 不会以 JSON 格式持久存储数据。

注意

有关 JSON 的更多信息，请参阅 JSON.org 网站的介绍 JSON。

DynamoDB 低级别 API 以及 AWS SDK 如何处理协议级别的请求和响应。

请求格式

DynamoDB 低级别 API 接受 HTTP(S) POST 请求作为输入。AWS SDK 为您构建这些请求。

假设您有一个名为 Pets 的表和一个包含 AnimalType（分区键）和 Name（排序键）的键架构。这两个属性的类型为 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 操作，参数为 TableName 和 Key。

响应格式

收到请求后，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 错误处理。

数据类型描述符

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

请求格式和响应格式中的示例说明了如何使用数据类型描述符。GetItem 请求为 string 类型的 Pets 键架构属性（AnimalType 和 Name）指定 S。GetItem 响应包含一个 Pets 项目，该项目带有 string (S)、number (N)、map (M) 和 list (L) 类型的属性。

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

  • S – String

  • N – Number

  • B – Binary

  • BOOL – Boolean

  • NULL – Null

  • M – Map

  • L – List

  • SS – String Set

  • NS – Number Set

  • BS – Binary Set

注意

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

数值数据

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

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

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

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

二进制数据

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

DynamoDB 使用的 base64 编码方案在 Internet Engineering Task Force (IETF) 网站的 RFC 4648 介绍。