$util.dynamodb 中的 DynamoDB 帮助程序 - Amazon AppSync
toDynamoDBtoString 实用程序toNumber 实用程序toBinary 实用程序toBoolean 实用程序toNull 实用程序toList 实用程序toMap 实用程序S3Object 实用程序
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

$util.dynamodb 中的 DynamoDB 帮助程序

注意

我们现在主要支持 APPSYNC_JS 运行时环境及其文档。请考虑使用 APPSYNC_JS 运行时环境和此处的指南。

$util.dynamodb 包含一些帮助程序方法，可以更轻松地在 Amazon DynamoDB 中写入和读取数据，例如自动类型映射和格式设置。这些方法旨在自动将基元类型和列表映射到正确的 DynamoDB 输入格式，即格式 { "TYPE" : VALUE } 的 Map。

例如，以前用于在 DynamoDB 中创建新项目的请求映射模板可能如下所示：

{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key": {
        "id" : { "S" : "$util.autoId()" }
    },
    "attributeValues" : {
         "title" : { "S" : $util.toJson($ctx.args.title) },
         "author" : { "S" : $util.toJson($ctx.args.author) },
         "version" : { "N", $util.toJson($ctx.args.version) }
    }
}

如果我们想为对象添加字段，则必须在架构中更新 GraphQL 查询，还要更新请求映射模板。不过，我们现在可以重构请求映射模板，以使其自动选取在架构中添加的新字段，并使用正确的类型将其添加到 DynamoDB 中：

{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key": {
        "id" : $util.dynamodb.toDynamoDBJson($util.autoId())
    },
    "attributeValues" : $util.dynamodb.toMapValuesJson($ctx.args)
}

在上一示例中，我们使用 $util.dynamodb.toDynamoDBJson(...) 帮助程序自动获取生成的 ID，并将其转换为字符串属性的 DynamoDB 表示形式。然后，我们获取所有参数，将其转换为其 DynamoDB 表示形式，并输出到模板中的 attributeValues 字段。

每个帮助程序均有两个版本：一个版本返回对象（例如 $util.dynamodb.toString(...)）；一个版本将对象返回为 JSON 字符串（例如 $util.dynamodb.toStringJson(...)）。在上一示例中，我们使用了将数据返回为 JSON 字符串的版本。如果您希望在模板中使用对象之前处理对象，可以选择返回对象，如下所示：

{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key": {
        "id" : $util.dynamodb.toDynamoDBJson($util.autoId())
    },

    #set( $myFoo = $util.dynamodb.toMapValues($ctx.args) )
    #set( $myFoo.version = $util.dynamodb.toNumber(1) )
    #set( $myFoo.timestamp = $util.dynamodb.toString($util.time.nowISO8601()))

    "attributeValues" : $util.toJson($myFoo)
}

在上一示例中，我们将转换的参数作为映射返回，而不是 JSON 字符串；并在使用 version 最终输出到模板中的 timestamp 字段之前添加了 attributeValues 和 $util.toJson(...) 字段。

每个帮助程序的 JSON 版本等效于在 $util.toJson(...) 中包装非 JSON 版本。例如，以下语句是完全相同的：

$util.toStringJson("Hello, World!")
$util.toJson($util.toString("Hello, World!"))

toDynamoDB

$util.dynamodb.toDynamoDB(Object) : Map

DynamoDB 的常规对象转换工具，可以将输入对象转换为相应的 DynamoDB 表示形式。表示某些类型的方式是自主的：例如，使用列表 ("L") 而不使用集 ("SS", "NS", "BS")。这会返回一个描述 DynamoDB 属性值的对象。

字符串示例

Input:      $util.dynamodb.toDynamoDB("foo")
Output:     { "S" : "foo" }

数字示例

Input:      $util.dynamodb.toDynamoDB(12345)
Output:     { "N" : 12345 }

布尔值示例

Input:      $util.dynamodb.toDynamoDB(true)
Output:     { "BOOL" : true }

列表示例

Input:      $util.dynamodb.toDynamoDB([ "foo", 123, { "bar" : "baz" } ])
Output:     {
               "L" : [
                   { "S" : "foo" },
                   { "N" : 123 },
                   {
                       "M" : {
                           "bar" : { "S" : "baz" }
                       }
                   }
               ]
           }

映射示例

Input:      $util.dynamodb.toDynamoDB({ "foo": "bar", "baz" : 1234, "beep": [ "boop"] })
Output:     {
               "M" : {
                   "foo"  : { "S" : "bar" },
                   "baz"  : { "N" : 1234 },
                   "beep" : {
                       "L" : [
                           { "S" : "boop" }
                       ]
                   }
               }
           }
$util.dynamodb.toDynamoDBJson(Object) : String

与 $util.dynamodb.toDynamoDB(Object) : Map 相同，但以 JSON 编码字符串形式返回 DynamoDB 属性值。

toString 实用程序

$util.dynamodb.toString(String) : String

将输入字符串转换为 DynamoDB 字符串格式。这会返回一个描述 DynamoDB 属性值的对象。

Input:      $util.dynamodb.toString("foo")
Output:     { "S" : "foo" }
$util.dynamodb.toStringJson(String) : Map

与 $util.dynamodb.toString(String) : String 相同，但以 JSON 编码字符串形式返回 DynamoDB 属性值。

$util.dynamodb.toStringSet(List<String>) : Map

将包含字符串的列表转换为 DynamoDB 字符串集格式。这会返回一个描述 DynamoDB 属性值的对象。

Input:      $util.dynamodb.toStringSet([ "foo", "bar", "baz" ])
Output:     { "SS" : [ "foo", "bar", "baz" ] }
$util.dynamodb.toStringSetJson(List<String>) : String

与 $util.dynamodb.toStringSet(List<String>) : Map 相同，但以 JSON 编码字符串形式返回 DynamoDB 属性值。

toNumber 实用程序

$util.dynamodb.toNumber(Number) : Map

将数字转换为 DynamoDB 数字格式。这会返回一个描述 DynamoDB 属性值的对象。

Input:      $util.dynamodb.toNumber(12345)
Output:     { "N" : 12345 }
$util.dynamodb.toNumberJson(Number) : String

与 $util.dynamodb.toNumber(Number) : Map 相同，但以 JSON 编码字符串形式返回 DynamoDB 属性值。

$util.dynamodb.toNumberSet(List<Number>) : Map

将数字列表转换为 DynamoDB 数字集格式。这会返回一个描述 DynamoDB 属性值的对象。

Input:      $util.dynamodb.toNumberSet([ 1, 23, 4.56 ])
Output:     { "NS" : [ 1, 23, 4.56 ] }
$util.dynamodb.toNumberSetJson(List<Number>) : String

与 $util.dynamodb.toNumberSet(List<Number>) : Map 相同，但以 JSON 编码字符串形式返回 DynamoDB 属性值。

toBinary 实用程序

$util.dynamodb.toBinary(String) : Map

将编码为 Base64 字符串的二进制数据转换为 DynamoDB 二进制格式。这会返回一个描述 DynamoDB 属性值的对象。

Input:      $util.dynamodb.toBinary("foo")
Output:     { "B" : "foo" }
$util.dynamodb.toBinaryJson(String) : String

与 $util.dynamodb.toBinary(String) : Map 相同，但以 JSON 编码字符串形式返回 DynamoDB 属性值。

$util.dynamodb.toBinarySet(List<String>) : Map

将编码为 Base64 字符串的二进制数据列表转换为 DynamoDB 二进制集格式。这会返回一个描述 DynamoDB 属性值的对象。

Input:      $util.dynamodb.toBinarySet([ "foo", "bar", "baz" ])
Output:     { "BS" : [ "foo", "bar", "baz" ] }
$util.dynamodb.toBinarySetJson(List<String>) : String

与 $util.dynamodb.toBinarySet(List<String>) : Map 相同，但以 JSON 编码字符串形式返回 DynamoDB 属性值。

toBoolean 实用程序

$util.dynamodb.toBoolean(Boolean) : Map

将布尔值转换为相应的 DynamoDB 布尔值格式。这会返回一个描述 DynamoDB 属性值的对象。

Input:      $util.dynamodb.toBoolean(true)
Output:     { "BOOL" : true }
$util.dynamodb.toBooleanJson(Boolean) : String

与 $util.dynamodb.toBoolean(Boolean) : Map 相同，但以 JSON 编码字符串形式返回 DynamoDB 属性值。

toNull 实用程序

$util.dynamodb.toNull() : Map

使用 DynamoDB Null 格式返回 Null。这会返回一个描述 DynamoDB 属性值的对象。

Input:      $util.dynamodb.toNull()
Output:     { "NULL" : null }
$util.dynamodb.toNullJson() : String

与 $util.dynamodb.toNull() : Map 相同，但以 JSON 编码字符串形式返回 DynamoDB 属性值。

toList 实用程序

$util.dynamodb.toList(List) : Map

将对象列表转换为 DynamoDB 列表格式。列表中的每个项目也会转换为相应的 DynamoDB 格式。表示某些嵌套对象的方式是自主的：例如，使用列表 ("L") 而不使用集 ("SS", "NS", "BS")。这会返回一个描述 DynamoDB 属性值的对象。

Input:      $util.dynamodb.toList([ "foo", 123, { "bar" : "baz" } ])
Output:     {
               "L" : [
                   { "S" : "foo" },
                   { "N" : 123 },
                   {
                       "M" : {
                           "bar" : { "S" : "baz" }
                       }
                   }
               ]
           }
$util.dynamodb.toListJson(List) : String

与 $util.dynamodb.toList(List) : Map 相同，但以 JSON 编码字符串形式返回 DynamoDB 属性值。

toMap 实用程序

$util.dynamodb.toMap(Map) : Map

将映射转换为 DynamoDB 映射格式。映射中的每个值也会转换为相应的 DynamoDB 格式。表示某些嵌套对象的方式是自主的：例如，使用列表 ("L") 而不使用集 ("SS", "NS", "BS")。这会返回一个描述 DynamoDB 属性值的对象。

Input:      $util.dynamodb.toMap({ "foo": "bar", "baz" : 1234, "beep": [ "boop"] })
Output:     {
               "M" : {
                   "foo"  : { "S" : "bar" },
                   "baz"  : { "N" : 1234 },
                   "beep" : {
                       "L" : [
                           { "S" : "boop" }
                       ]
                   }
               }
           }
$util.dynamodb.toMapJson(Map) : String

与 $util.dynamodb.toMap(Map) : Map 相同，但以 JSON 编码字符串形式返回 DynamoDB 属性值。

$util.dynamodb.toMapValues(Map) : Map

创建映射的副本，其中每个值都已转换为相应的 DynamoDB 格式。表示某些嵌套对象的方式是自主的：例如，使用列表 ("L") 而不使用集 ("SS", "NS", "BS")。

Input:      $util.dynamodb.toMapValues({ "foo": "bar", "baz" : 1234, "beep": [ "boop"] })
Output:     {
               "foo"  : { "S" : "bar" },
               "baz"  : { "N" : 1234 },
               "beep" : {
                   "L" : [
                       { "S" : "boop" }
                   ]
               }
           }
注意

这与 $util.dynamodb.toMap(Map) : Map 略有不同，因为它仅返回 DynamoDB 属性值内容，而不返回整个属性值本身。例如，以下语句是完全相同的：

$util.dynamodb.toMapValues($map)
$util.dynamodb.toMap($map).get("M")
$util.dynamodb.toMapValuesJson(Map) : String

与 $util.dynamodb.toMapValues(Map) : Map 相同，但以 JSON 编码字符串形式返回 DynamoDB 属性值。

S3Object 实用程序

$util.dynamodb.toS3Object(String key, String bucket, String region) : Map

将键、存储桶和区域转换为 DynamoDB S3 对象表示形式。这会返回一个描述 DynamoDB 属性值的对象。

Input:      $util.dynamodb.toS3Object("foo", "bar", region = "baz")
Output:     { "S" : "{ \"s3\" : { \"key\" : \"foo", \"bucket\" : \"bar", \"region\" : \"baz" } }" }
$util.dynamodb.toS3ObjectJson(String key, String bucket, String region) : String

与 $util.dynamodb.toS3Object(String key, String bucket, String region) : Map 相同，但以 JSON 编码字符串形式返回 DynamoDB 属性值。

$util.dynamodb.toS3Object(String key, String bucket, String region, String version) : Map

将键、存储桶、区域和可选版本转换为 DynamoDB S3 对象表示形式。这会返回一个描述 DynamoDB 属性值的对象。

Input:      $util.dynamodb.toS3Object("foo", "bar", "baz", "beep")
Output:     { "S" : "{ \"s3\" : { \"key\" : \"foo\", \"bucket\" : \"bar\", \"region\" : \"baz\", \"version\" = \"beep\" } }" }
$util.dynamodb.toS3ObjectJson(String key, String bucket, String region, String version) : String

与 $util.dynamodb.toS3Object(String key, String bucket, String region, String version) : Map 相同，但以 JSON 编码字符串形式返回 DynamoDB 属性值。

$util.dynamodb.fromS3ObjectJson(String) : Map

接受 DynamoDB S3 对象的字符串值，并返回包含键、存储桶、区域和可选版本的映射。

Input:      $util.dynamodb.fromS3ObjectJson({ "S" : "{ \"s3\" : { \"key\" : \"foo\", \"bucket\" : \"bar\", \"region\" : \"baz\", \"version\" = \"beep\" } }" })
Output:     { "key" : "foo", "bucket" : "bar", "region" : "baz", "version" : "beep" }