Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 Amazon Web Services 服务入门。

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

DynamoDB 解析程序映射模板参考

这些区域有：Amazon AppSync DynamoDB 解析器允许您使用GraphQL以存储和检索您账户中现有的 Amazon DynamoDB 表中的数据。此解析程序的工作方式是：使您可以将传入的 GraphQL 请求映射到 DynamoDB 调用，然后将 DynamoDB 响应映射回 GraphQL。本部分介绍支持的 DynamoDB 操作的映射模板。

GetItem

这些区域有：GetItem请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个GetItem请求发送到 DynamoDB，并使您能够指定：

GetItem 映射文档具有以下结构：

{
    "version" : "2017-02-28",
    "operation" : "GetItem",
    "key" : {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "consistentRead" : true
}

字段定义如下：

从 DynamoDB 返回的项目自动转换为 GraphQL 和 JSON 基元类型，并且可用于映射上下文 ($context.result)。

有关 DynamoDB 类型转换的更多信息，请参阅类型系统（响应映射）.

有关响应映射模板的更多信息，请参阅解析程序映射模板概述。

示例

下面是 GraphQL 查询 getThing(foo: String!, bar: String!) 的一个映射模板：

{
    "version" : "2017-02-28",
    "operation" : "GetItem",
    "key" : {
        "foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
        "bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
    },
    "consistentRead" : true
}

有关 DynamoDB GetItem API 的更多信息，请参阅 DynamoDB API 文档。

PutItem

这些区域有：PutItem请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个PutItem请求发送到 DynamoDB，并使您能够指定以下各项：

PutItem 映射文档具有以下结构：

{
    "version" : "2018-05-29",
    "operation" : "PutItem",
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "attributeValues" : {
        "baz" : ... typed value
    },
    "condition" : {
       ...
    },
    "_version" : 1
}

字段定义如下：

写入 DynamoDB 的项目自动转换为 GraphQL 和 JSON 基元类型，并且可用于映射上下文 ($context.result)。

有关 DynamoDB 类型转换的更多信息，请参阅类型系统（响应映射）.

有关响应映射模板的更多信息，请参阅解析程序映射模板概述。

示例 1

下面是 GraphQL 更改 updateThing(foo: String!, bar: String!, name: String!, version: Int!) 的一个映射模板：

如果带指定键的项目不存在，则会创建它。如果带指定键的项已存在，则会覆盖它。

{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key": {
        "foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
        "bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
    },
    "attributeValues" : {
        "name"    : $util.dynamodb.toDynamoDBJson($ctx.args.name),
        "version" : $util.dynamodb.toDynamoDBJson($ctx.args.version)
    }
}

示例 2

下面是 GraphQL 更改 updateThing(foo: String!, bar: String!, name: String!, expectedVersion: Int!) 的一个映射模板：

此示例进行检查，以确保当前在 DynamoDB 中的项目具有version字段设置为expectedVersion.

{
    "version" : "2017-02-28",
    "operation" : "PutItem",
    "key": {
        "foo" : $util.dynamodb.toDynamoDBJson($ctx.args.foo),
        "bar" : $util.dynamodb.toDynamoDBJson($ctx.args.bar)
    },
    "attributeValues" : {
        "name"    : $util.dynamodb.toDynamoDBJson($ctx.args.name),
        #set( $newVersion = $context.arguments.expectedVersion + 1 )
        "version" : $util.dynamodb.toDynamoDBJson($newVersion)
    },
    "condition" : {
        "expression" : "version = :expectedVersion",
        "expressionValues" : {
            ":expectedVersion" : $util.dynamodb.toDynamoDBJson($expectedVersion)
        }
    }
}

有关 DynamoDB PutItem API 的更多信息，请参阅 DynamoDB API 文档。

UpdateItem

这些区域有：UpdateItem请求映射文档使你能够告诉Amazon AppSync DynamoDB 解析器创建一个UpdateItem请求发送到 DynamoDB，并允许您指定以下各项：

UpdateItem 映射文档具有以下结构：

{
    "version" : "2018-05-29",
    "operation" : "UpdateItem",
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "update" : {
        "expression" : "someExpression",
        "expressionNames" : {
           "#foo" : "foo"
       },
       "expressionValues" : {
           ":bar" : ... typed value
       }
    },
    "condition" : {
        ...
    },
    "_version" : 1
}

字段定义如下：

在 DynamoDB 中更新的项目自动转换为 GraphQL 和 JSON 基元类型，并且可用于映射上下文 ($context.result)。

有关 DynamoDB 类型转换的更多信息，请参阅类型系统（响应映射）.

有关响应映射模板的更多信息，请参阅解析程序映射模板概述。

示例 1

下面是 GraphQL 更改 upvote(id: ID!) 的一个映射模板：

在本示例中，DynamoDB 中的一个项目如下所示upvotes和version字段增加 1。

{
    "version" : "2017-02-28",
    "operation" : "UpdateItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    },
    "update" : {
        "expression" : "ADD #votefield :plusOne, version :plusOne",
        "expressionNames" : {
            "#votefield" : "upvotes"
        },
        "expressionValues" : {
            ":plusOne" : { "N" : 1 }
        }
    }
}

示例 2

下面是 GraphQL 更改 updateItem(id: ID!, title: String, author: String, expectedVersion: Int!) 的一个映射模板：

这是一个复杂的示例，用于检查参数并动态生成更新表达式，此表达式仅包含由客户端提供的参数。例如，如果省略了 title 和 author，则不会更新它们。如果指定了参数但其值为null，则会从 DynamoDB 中的对象删除该字段。最后，操作具有一个条件，此条件验证当前在 DynamoDB 中的项目是否有version字段设置为expectedVersion：

{
    "version" : "2017-02-28",

    "operation" : "UpdateItem",

    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    },

    ## Set up some space to keep track of things we're updating **
    #set( $expNames  = {} )
    #set( $expValues = {} )
    #set( $expSet = {} )
    #set( $expAdd = {} )
    #set( $expRemove = [] )

    ## Increment "version" by 1 **
    $!{expAdd.put("version", ":newVersion")}
    $!{expValues.put(":newVersion", { "N" : 1 })}

    ## Iterate through each argument, skipping "id" and "expectedVersion" **
    #foreach( $entry in $context.arguments.entrySet() )
        #if( $entry.key != "id" && $entry.key != "expectedVersion" )
            #if( (!$entry.value) && ("$!{entry.value}" == "") )
                ## If the argument is set to "null", then remove that attribute from the item in DynamoDB **

                #set( $discard = ${expRemove.add("#${entry.key}")} )
                $!{expNames.put("#${entry.key}", "$entry.key")}
            #else
                ## Otherwise set (or update) the attribute on the item in DynamoDB **

                $!{expSet.put("#${entry.key}", ":${entry.key}")}
                $!{expNames.put("#${entry.key}", "$entry.key")}

                #if( $entry.key == "ups" || $entry.key == "downs" )
                    $!{expValues.put(":${entry.key}", { "N" : $entry.value })}
                #else
                    $!{expValues.put(":${entry.key}", { "S" : "${entry.value}" })}
                #end
            #end
        #end
    #end

    ## Start building the update expression, starting with attributes we're going to SET **
    #set( $expression = "" )
    #if( !${expSet.isEmpty()} )
        #set( $expression = "SET" )
        #foreach( $entry in $expSet.entrySet() )
            #set( $expression = "${expression} ${entry.key} = ${entry.value}" )
            #if ( $foreach.hasNext )
                #set( $expression = "${expression}," )
            #end
        #end
    #end

    ## Continue building the update expression, adding attributes we're going to ADD **
    #if( !${expAdd.isEmpty()} )
        #set( $expression = "${expression} ADD" )
        #foreach( $entry in $expAdd.entrySet() )
            #set( $expression = "${expression} ${entry.key} ${entry.value}" )
            #if ( $foreach.hasNext )
                #set( $expression = "${expression}," )
            #end
        #end
    #end

    ## Continue building the update expression, adding attributes we're going to REMOVE **
    #if( !${expRemove.isEmpty()} )
        #set( $expression = "${expression} REMOVE" )

        #foreach( $entry in $expRemove )
            #set( $expression = "${expression} ${entry}" )
            #if ( $foreach.hasNext )
                #set( $expression = "${expression}," )
            #end
        #end
    #end

    ## Finally, write the update expression into the document, along with any expressionNames and expressionValues **
    "update" : {
        "expression" : "${expression}"
        #if( !${expNames.isEmpty()} )
            ,"expressionNames" : $utils.toJson($expNames)
        #end
        #if( !${expValues.isEmpty()} )
            ,"expressionValues" : $utils.toJson($expValues)
        #end
    },

    "condition" : {
        "expression"       : "version = :expectedVersion",
        "expressionValues" : {
            ":expectedVersion" : $util.dynamodb.toDynamoDBJson($ctx.args.expectedVersion)
        }
    }
}

有关 DynamoDB UpdateItem API 的更多信息，请参阅 DynamoDB API 文档。

DeleteItem

这些区域有：DeleteItem请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个DeleteItem请求发送到 DynamoDB，并使您能够指定以下各项：

DeleteItem 映射文档具有以下结构：

{
    "version" : "2018-05-29",
    "operation" : "DeleteItem",
    "key": {
        "foo" : ... typed value,
        "bar" : ... typed value
    },
    "condition" : {
        ...
    },
    "_version" : 1
}

字段定义如下：

从 DynamoDB 删除的项目自动转换为 GraphQL 和 JSON 基元类型，并且可用于映射上下文 ($context.result)。

有关 DynamoDB 类型转换的更多信息，请参阅类型系统（响应映射）.

有关响应映射模板的更多信息，请参阅解析程序映射模板概述。

示例 1

下面是 GraphQL 更改 deleteItem(id: ID!) 的一个映射模板：如果具有此 ID 的项目存在，它将被删除。

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

示例 2

下面是 GraphQL 更改 deleteItem(id: ID!, expectedVersion: Int!) 的一个映射模板：如果具有此 ID 的项目存在，它将被删除，但仅当其 version 字段设置为 expectedVersion 时：

{
    "version" : "2017-02-28",
    "operation" : "DeleteItem",
    "key" : {
        "id" : $util.dynamodb.toDynamoDBJson($ctx.args.id)
    },
    "condition" : {
        "expression"       : "attribute_not_exists(id) OR version = :expectedVersion",
        "expressionValues" : {
            ":expectedVersion" : $util.dynamodb.toDynamoDBJson($expectedVersion)
        }
    }
}

有关 DynamoDB DeleteItem API 的更多信息，请参阅 DynamoDB API 文档。

Query

这些区域有：Query请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个Query请求发送到 DynamoDB，并使您能够指定以下各项：

Query 映射文档具有以下结构：

{
    "version" : "2017-02-28",
    "operation" : "Query",
    "query" : {
        "expression" : "some expression",
        "expressionNames" : {
            "#foo" : "foo"
        },
        "expressionValues" : {
            ":bar" : ... typed value
        }
    },
    "index" : "fooIndex",
    "nextToken" : "a pagination token",
    "limit" : 10,
    "scanIndexForward" : true,
    "consistentRead" : false,
    "select" : "ALL_ATTRIBUTES",
    "filter" : {
        ...
    }
}

字段定义如下：

来自 DynamoDB 的结果自动转换为 GraphQL 和 JSON 基元类型，并且可用于映射上下文 ($context.result)。

有关 DynamoDB 类型转换的更多信息，请参阅类型系统（响应映射）.

有关响应映射模板的更多信息，请参阅解析程序映射模板概述。

结果的结构如下所示：

{
    items = [ ... ],
    nextToken = "a pagination token",
    scannedCount = 10
}

字段定义如下：

示例

下面是 GraphQL 查询 getPosts(owner: ID!) 的一个映射模板。

在本示例中，将对表的全局二级索引执行查询，以返回指定的 ID 拥有的所有文章。

{
    "version" : "2017-02-28",
    "operation" : "Query",
    "query" : {
        "expression" : "ownerId = :ownerId",
        "expressionValues" : {
            ":ownerId" : $util.dynamodb.toDynamoDBJson($context.arguments.owner)
        }
    },
    "index" : "owner-index"
}

有关 DynamoDB Query API 的更多信息，请参阅 DynamoDB API 文档。

Scan

这些区域有：Scan请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个Scan请求发送到 DynamoDB，并使您能够指定以下各项：

Scan 映射文档具有以下结构：

{
    "version" : "2017-02-28",
    "operation" : "Scan",
    "index" : "fooIndex",
    "limit" : 10,
    "consistentRead" : false,
    "nextToken" : "aPaginationToken",
    "totalSegments" : 10,
    "segment" : 1,
    "filter" : {
        ...
    }
}

字段定义如下：

DynamoDB 扫描返回的结果自动转换为 GraphQL 和 JSON 基元类型，并且可用于映射上下文 ($context.result)。

有关 DynamoDB 类型转换的更多信息，请参阅类型系统（响应映射）.

有关响应映射模板的更多信息，请参阅解析程序映射模板概述。

结果的结构如下所示：

{
    items = [ ... ],
    nextToken = "a pagination token",
    scannedCount = 10
}

字段定义如下：

示例 1

下面是 GraphQL 查询 allPosts 的一个映射模板。

在本示例中，将返回表中的所有条目。

{
    "version" : "2017-02-28",
    "operation" : "Scan"
}

示例 2

下面是 GraphQL 查询 postsMatching(title: String!) 的一个映射模板。

在本示例中，将返回表中标题以 title 参数开头的所有条目。

{
    "version" : "2017-02-28",
    "operation" : "Scan",
    "filter" : {
        "expression" : "begins_with(title, :title)",
        "expressionValues" : {
            ":title" : $util.dynamodb.toDynamoDBJson($context.arguments.title)
        },
    }
}

有关 DynamoDB Scan API 的更多信息，请参阅 DynamoDB API 文档。

Sync（同步）

这些区域有：Sync请求映射文档允许您从 DynamoDB 表中检索所有结果，然后仅接收自上次查询（增量更新）以来更改的数据。Sync只能向受版本控制的 DynamoDB 数据源发出请求。您可以指定：

Sync 映射文档具有以下结构：

{
    "version" : "2018-05-29",
    "operation" : "Sync",
    "limit" : 10,
    "nextToken" : "aPaginationToken",
    "lastSync" :  1550000000000,
    "filter" : {
        ...
    }
}

字段定义如下：

DynamoDB 同步返回的结果自动转换为 GraphQL 和 JSON 基元类型，并且可用于映射上下文 ($context.result)。

有关 DynamoDB 类型转换的更多信息，请参阅类型系统（响应映射）.

有关响应映射模板的更多信息，请参阅解析程序映射模板概述。

结果的结构如下所示：

{
    items = [ ... ],
    nextToken = "a pagination token",
    scannedCount = 10,
    startedAt = 1550000000000
}

字段定义如下：

示例 1

下面是 GraphQL 查询 syncPosts(nextToken: String, lastSync: AWSTimestamp) 的一个映射模板。

在此示例中，如果省略 lastSync，则返回基本表中的所有条目。如果提供了 lastSync，则只返回增量同步表中自 lastSync 以来发生更改的条目。

{
    "version" : "2018-05-29",
    "operation" : "Sync",
    "limit": 100,
    "nextToken": $util.toJson($util.defaultIfNull($ctx.args.nextToken, null)),
    "lastSync": $util.toJson($util.defaultIfNull($ctx.args.lastSync, null))
}

BatchGetItem

这些区域有：BatchGetItem请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个BatchGetItem向 DynamoDB 发出请求以检索多个项目，可能会跨多个表。对于此请求模板，您必须指定以下各项：

DynamoDB BatchGetItem 限制适用，并且无法提供任何条件表达式。

BatchGetItem 映射文档具有以下结构：

{
    "version" : "2018-05-29",
    "operation" : "BatchGetItem",
    "tables" : {
        "table1": {
           "keys": [
              ## Item to retrieve Key
              {
                   "foo" : ... typed value,
                   "bar" : ... typed value
              },
              ## Item2 to retrieve Key
              {
                   "foo" : ... typed value,
                   "bar" : ... typed value
              }
            ],
            "consistentRead": true|false
        },
        "table2": {
           "keys": [
              ## Item3 to retrieve Key
              {
                   "foo" : ... typed value,
                   "bar" : ... typed value
              },
              ## Item4 to retrieve Key
              {
                   "foo" : ... typed value,
                   "bar" : ... typed value
              }
            ],
            "consistentRead": true|false
        }
    }
}

字段定义如下：

要记住的事项：

对于以下示例请求映射模板：

{
  "version": "2018-05-29",
  "operation": "BatchGetItem",
  "tables": {
    "authors": [
        {
          "author_id": {
            "S": "a1"
          }
        },
    ],
    "posts": [
        {
          "author_id": {
            "S": "a1"
          },
          "post_id": {
            "S": "p2"
          }
        }
    ],
  }
}

$ctx.result 中可用的调用结果如下所示：

{
   "data": {
     "authors": [null],
     "posts": [
        # Was retrieved
        {
          "author_id": "a1",
          "post_id": "p2",
          "post_title": "title",
          "post_description": "description",
        }
     ]
   },
   "unprocessedKeys": {
     "authors": [
        # This item was not processed due to an error
        {
          "author_id": "a1"
        }
      ],
     "posts": []
   }
}

$ctx.error 包含有关该错误的详细信息。保证键数据、unprocessedKeys 和请求映射模板中提供的每个表键都出现在调用结果中。已删除的项目显示在数据块中。尚未处理的项目将在数据块中标记为 null 并置于 unprocessedKeys 块中。

有关更完整的示例，请按照DynamoDB Batch 教程： AppSync 这里教程：DynamoDB Batch 解析程序.

BatchDeleteItem

这些区域有：BatchDeleteItem请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个BatchWriteItem向 DynamoDB 发出请求以删除多个项目，可能会跨多个表。对于此请求模板，您必须指定以下各项：

DynamoDB BatchWriteItem 限制适用，并且无法提供任何条件表达式。

BatchDeleteItem 映射文档具有以下结构：

{
    "version" : "2018-05-29",
    "operation" : "BatchDeleteItem",
    "tables" : {
        "table1": [
        ## Item to delete Key
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        },
        ## Item2 to delete Key
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        }],
        "table2": [
        ## Item3 to delete Key
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        },
        ## Item4 to delete Key
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        }],
    }
}

字段定义如下：

要记住的事项：

对于以下示例请求映射模板：

{
  "version": "2018-05-29",
  "operation": "BatchDeleteItem",
  "tables": {
    "authors": [
        {
          "author_id": {
            "S": "a1"
          }
        },
    ],
    "posts": [
        {
          "author_id": {
            "S": "a1"
          },
          "post_id": {
            "S": "p2"
          }
        }
    ],
  }
}

$ctx.result 中可用的调用结果如下所示：

{
   "data": {
     "authors": [null],
     "posts": [
        # Was deleted
        {
          "author_id": "a1",
          "post_id": "p2"
        }
     ]
   },
   "unprocessedKeys": {
     "authors": [
        # This key was not processed due to an error
        {
          "author_id": "a1"
        }
      ],
     "posts": []
   }
}

$ctx.error 包含有关该错误的详细信息。保证键数据、unprocessedKeys 和请求映射模板中提供的每个表键都出现在调用结果中。已删除的项目存在于数据块中。尚未处理的项目将在数据块中标记为 null 并置于 unprocessedKeys 块中。

有关更完整的示例，请按照DynamoDB Batch 教程： AppSync 这里教程：DynamoDB Batch 解析程序.

BatchPutItem

这些区域有：BatchPutItem请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个BatchWriteItem向 DynamoDB 发出请求以放置多个项目，可能会跨多个表。对于此请求模板，您必须指定以下各项：

DynamoDB BatchWriteItem 限制适用，并且无法提供任何条件表达式。

BatchPutItem 映射文档具有以下结构：

{
    "version" : "2018-05-29",
    "operation" : "BatchPutItem",
    "tables" : {
        "table1": [
        ## Item to put
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        },
        ## Item2 to put
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        }],
        "table2": [
        ## Item3 to put
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        },
        ## Item4 to put
        {
             "foo" : ... typed value,
             "bar" : ... typed value
        }],
    }
}

字段定义如下：

要记住的事项：

对于以下示例请求映射模板：

{
  "version": "2018-05-29",
  "operation": "BatchPutItem",
  "tables": {
    "authors": [
        {
          "author_id": {
            "S": "a1"
          },
          "author_name": {
            "S": "a1_name"
          }
        },
    ],
    "posts": [
        {
          "author_id": {
            "S": "a1"
          },
          "post_id": {
            "S": "p2"
          },
          "post_title": {
            "S": "title"
          }
        }
    ],
  }
}

$ctx.result 中可用的调用结果如下所示：

{
   "data": {
     "authors": [
         null
     ],
     "posts": [
        # Was inserted
        {
          "author_id": "a1",
          "post_id": "p2",
          "post_title": "title"
        }
     ]
   },
   "unprocessedItems": {
     "authors": [
        # This item was not processed due to an error
        {
          "author_id": "a1",
          "author_name": "a1_name"
        }
      ],
     "posts": []
   }
}

$ctx.error 包含有关该错误的详细信息。保证键数据、unprocessedItems 和请求映射模板中提供的每个表键都出现在调用结果中。已插入的项目存在于数据块中。尚未处理的项目将在数据块中标记为 null 并置于 unprocessedItems 块中。

有关更完整的示例，请按照DynamoDB Batch 教程： AppSync 这里教程：DynamoDB Batch 解析程序.

TransactGetItems

这些区域有：TransactGetItems请求映射文档可以让你告诉Amazon AppSync DynamoDB 解析器创建一个TransactGetItems向 DynamoDB 发出请求以检索多个项目，可能会跨多个表。对于此请求模板，您必须指定以下各项：

DynamoDB TransactGetItems 限制适用，并且无法提供任何条件表达式。

TransactGetItems 映射文档具有以下结构：

{
    "version": "2018-05-29",
    "operation": "TransactGetItems",
    "transactItems": [
       ## First request item
       {
           "table": "table1",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           }
       },
       ## Second request item
       {
           "table": "table2",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           }
       }
    ]
}

字段定义如下：

要记住的事项：

对于以下示例请求映射模板：

{
    "version": "2018-05-29",
    "operation": "TransactGetItems",
    "transactItems": [
       ## First request item
       {
           "table": "posts",
           "key": {
               "post_id": {
                 "S": "p1"
               }
           }
       },
       ## Second request item
       {
           "table": "authors",
           "key": {
               "author_id": {
                 "S": a1
               }
           }
       }
    ]
}

如果事务成功并且只检索第一个请求的项目，则 $ctx.result 中可用的调用结果如下所示：

{
    "items": [
       {
           // Attributes of the first requested item
           "post_id": "p1",
           "post_title": "title",
           "post_description": "description"
       },
       // Could not retrieve the second requested item
       null,
    ],
    "cancellationReasons": null
}

如果交易由于以下原因而失败TransactionCanceledException由第一个请求项目引起，调用结果可用$ctx.result如下所示：

{
    "items": null,
    "cancellationReasons": [
       {
           "type":"Sample error type",
           "message":"Sample error message"
       },
       {
           "type":"None",
           "message":"None"
       }
    ]
}

$ctx.error 包含有关该错误的详细信息。键 items 和 cancellationReasons 保证出现在 $ctx.result 中。

有关更完整的示例，请按照教程：DynamoDB 事务教程： AppSync 这里教程：DynamoDB 事务解析程序.

TransactWriteItems

这些区域有：TransactWriteItems请求映射文档让你告诉Amazon AppSync DynamoDB 解析器创建一个TransactWriteItems向 DynamoDB 发出请求以写入多个项目，可能跨多个表。对于此请求模板，您必须指定以下各项：

DynamoDB TransactWriteItems 限制适用。

TransactWriteItems 映射文档具有以下结构：

{
    "version": "2018-05-29",
    "operation": "TransactWriteItems",
    "transactItems": [
       {
           "table": "table1",
           "operation": "PutItem",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           },
           "attributeValues": {
               "baz": ... typed value
           },
           "condition": {
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       },
       {
           "table":"table2",
           "operation": "UpdateItem",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           },
           "update": {
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               }
           },
           "condition": {
               "expression": "someExpression",
               "expressionNames": {
                   "#foo":"foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       },
       {
           "table": "table3",
           "operation": "DeleteItem",
           "key":{
               "foo": ... typed value,
               "bar": ... typed value
           },
           "condition":{
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       },
       {
           "table": "table4",
           "operation": "ConditionCheck",
           "key":{
               "foo": ... typed value,
               "bar": ... typed value
           },
           "condition":{
               "expression": "someExpression",
               "expressionNames": {
                   "#foo": "foo"
               },
               "expressionValues": {
                   ":bar": ... typed value
               },
               "returnValuesOnConditionCheckFailure": true|false
           }
       }
    ]
}

要记住的事项：

对于以下示例请求映射模板：

{
    "version": "2018-05-29",
    "operation": "TransactWriteItems",
    "transactItems": [
       {
           "table": "posts",
           "operation": "PutItem",
           "key": {
               "post_id": {
                   "S": "p1"
               }
           },
           "attributeValues": {
               "post_title": {
                   "S": "New title"
               },
               "post_description": {
                   "S": "New description"
               }
           },
           "condition": {
               "expression": "post_title = :post_title",
               "expressionValues": {
                   ":post_title": {
                       "S": "Expected old title"
                   }
               }
           }
       },
       {
           "table":"authors",
           "operation": "UpdateItem",
           "key": {
               "author_id": {
                   "S": "a1"
               },
           },
           "update": {
               "expression": "SET author_name = :author_name",
               "expressionValues": {
                   ":author_name": {
                       "S": "New name"
                   }
               }
           },
       }
    ]
}

如果事务成功，$ctx.result 中可用的调用结果如下所示：

{
    "keys": [
       // Key of the PutItem request
       {
           "post_id": "p1",
       },
       // Key of the UpdateItem request
       {
           "author_id": "a1"
       }
    ],
    "cancellationReasons": null
}

如果事务因条件检查失败而失败 PutItem 请求，调用结果如下所示$ctx.result如下所示：

{
    "keys": null,
    "cancellationReasons": [
       {
           "item": {
               "post_id": "p1",
               "post_title": "Actual old title",
               "post_description": "Old description"
           },
           "type": "ConditionCheckFailed",
           "message": "The condition check failed."
       },
       {
           "type": "None",
           "message": "None"
       }
    ]
}

$ctx.error 包含有关该错误的详细信息。键 keys 和 cancellationReasons 保证出现在 $ctx.result 中。

有关更完整的示例，请按照教程：DynamoDB 事务教程： AppSync 这里教程：DynamoDB 事务解析程序.

类型系统（请求映射）

使用Amazon AppSync DynamoDB 解析器来调用你的 DynamoDB 表，Amazon AppSync 需要知道该调用中要使用的每个值的类型。这是因为 DynamoDB 比 GraphQL 或 JSON 支持更多的基元类型（如集和二进制数据）。Amazon AppSync 当在 GraphQL 和 DynamoDB 之间转换时，需要一些提示，否则它会对如何设定表中数据的结构做出一些假设。

有关 DynamoDB 数据类型的更多信息，请参阅 DynamoDB数据类型描述符和数据类型文档中）。

DynamoDB 值由包含单个键值对的 JSON 对象表示。键指定 DynamoDB 类型，而值指定值本身。在下面的示例中，键 S 表示值是一个字符串，值 identifier 是字符串值本身。

{ "S" : "identifier" }

请注意，JSON 对象不能具有多于一个键值对。如果指定了多个键值对，将不会解析请求映射文档。

DynamoDB 值用在请求映射文档中您需要指定一个值用在请求映射文档中您需要指定一个值。您需要这样做的一些地方包括：key 和 attributeValue 部分以及表达式部分的 expressionValues 部分。在以下示例中，DynamoDB 字符串值identifier正在分配给id中返回的子位置类型key部分（可能在GetItem请求映射文档）。

"key" : {
   "id" : { "S" : "identifier" }
}

支持的类型

Amazon AppSync 支持以下 DynamoDB 标量、文档和集类型：

有关每个类型的更多信息，请参阅 DynamoDB 文档。

类型系统（响应映射）

收到来自 DynamoDB 的响应时，Amazon AppSync 会自动将其转换为 GraphQL 和 JSON 基元类型。DynamoDB 中的每个属性都会被解码并在响应映射上下文中返回。

例如，如果 DynamoDB 返回以下内容：

{
    "id" : { "S" : "1234" },
    "name" : { "S" : "Nadia" },
    "age" : { "N" : 25 }
}

然后是Amazon AppSync DynamoDB 解析程序将其转换为 GraphQL 和 JSON 类型，如下所示：

{
    "id" : "1234",
    "name" : "Nadia",
    "age" : 25
}

本部分说明 Amazon AppSync 如何转换以下 DynamoDB 标量、文档和集类型：

Filters

在 DynamoDB 中使用查询对象时Query和Scan操作，您可选择指定filter，将计算结果并仅返回所需值。

Query 或 Scan 映射文档的筛选映射部分具有以下结构：

"filter" : {
    "expression" : "filter expression"
    "expressionNames" : {
        "#name" : "name",
    },
    "expressionValues" : {
        ":value" : ... typed value
    },
}

字段定义如下：

示例

下面是映射模板的筛选条件部分，其中，如果标题以title参数。

"filter" : {
    "expression" : "begins_with(#title, :title)",
    "expressionNames" : {
        "#title" : "title"
    },
    "expressionValues" : {
        ":title" : $util.dynamodb.toDynamoDBJson($context.arguments.title)
    }
}

条件表达式

当您在 DynamoDB 中使用变更对象时PutItem、UpdateItem, 和DeleteItemDynamoDB 操作，您可以选择性地指定条件表达式，以根据在执行操作前已在 DynamoDB 中的对象状态控制请求是否应成功。

这些区域有：Amazon AppSync DynamoDB 解析器允许在中指定条件表达式PutItem、UpdateItem, 和DeleteItem请求映射文档，还提供了一个策略供在条件失败和未更新对象时遵循。

示例 1

以下 PutItem 映射文档没有条件表达式。因此，它会将项目放置在 DynamoDB 中，从而覆盖现有项目，从而覆盖现有项目。

{
   "version" : "2017-02-28",
   "operation" : "PutItem",
   "key" : {
      "id" : { "S" : "1" }
   }
}

示例 2

以下PutItem映射文档确实有一个条件表达式，仅当具有相同键（或在具有相同键）时，此表达式才允许操作成功不中返回的DynamoDB。

{
   "version" : "2017-02-28",
   "operation" : "PutItem",
   "key" : {
      "id" : { "S" : "1" }
   },
   "condition" : {
      "expression" : "attribute_not_exists(id)"
   }
}

默认情况下，如果条件检查失败，则Amazon AppSync DynamoDB 解析程序将对更改返回错误，并在 DynamoDB 中返回中对象的当前值data中返回的子位置类型errorGraphQL 响应的部分。但是，Amazon AppSync DynamoDB 解析程序提供了一些额外功能，以帮助开发人员处理一些常见的边缘情况：

这些内容将在处理条件检查失败部分中更详细地介绍。

有关 DynamoDB 条件表达式的更多信息，请参阅DynamoDB ConditionExpressions 文档.

指定条件

PutItem、UpdateItem 和 DeleteItem 请求映射文档都允许指定可选的 condition 部分。如果省略，则不会进行条件检查。如果指定，条件必须为 true，操作才能成功。

condition 部分具有以下结构：

"condition" : {
    "expression" : "someExpression"
    "expressionNames" : {
        "#foo" : "foo"
    },
    "expressionValues" : {
        ":bar" : ... typed value
    },
    "equalsIgnore" : [ "version" ],
    "consistentRead" : true,
    "conditionalCheckFailedHandler" : {
        "strategy" : "Custom",
        "lambdaArn" : "arn:..."
    }
}

下列字段指定条件：

剩下的字段告诉Amazon AppSync DynamoDB 解析程序如何处理条件检查失败：

处理条件检查失败

默认情况下，当条件检查失败时，Amazon AppSync DynamoDB 解析程序将对更改返回错误，并在 DynamoDB 中返回中对象的当前值data中返回的子位置类型errorGraphQL 响应的部分。但是，Amazon AppSync DynamoDB 解析程序提供了一些额外功能，以帮助开发人员处理一些常见的边缘情况：

此过程的流程图为：

检查所需结果

当条件检查失败时，Amazon AppSync DynamoDB 解析器执行GetItemDynamoDB 请求从 DynamoDB 获取项目的当前值。默认情况下，它将使用强一致性读取，但这可以使用 condition 数据块中的 consistentRead 字段进行配置，并将当前值与预期结果进行比较：

如果 DynamoDB 中对象的当前状态与预期结果不同，则Amazon AppSync DynamoDB 解析程序将遵循所配置的策略，以拒绝更改或者调用 Lambda 函数来确定接下来要做什么。

遵循“拒绝”策略

当关注Reject策略，Amazon AppSync DynamoDB 解析程序将对更改返回错误，也会在 DynamoDB 中返回中对象的当前值data中返回的子位置类型errorGraphQL 响应的部分。从 DynamoDB 返回的项目将放入响应映射模板，以便将其转换为客户端预期的格式，也将按选择集进行筛选。

例如，给定以下更改请求：

mutation {
    updatePerson(id: 1, name: "Steve", expectedVersion: 1) {
        Name
        theVersion
    }
}

如果从 DynamoDB 返回的项目如下所示：

{
   "id" : { "S" : "1" },
   "name" : { "S" : "Steve" },
   "version" : { "N" : 8 }
}

并且响应映射模板如下所示：

{
   "id" : $util.toJson($context.result.id),
   "Name" : $util.toJson($context.result.name),
   "theVersion" : $util.toJson($context.result.version)
}

GraphQL 响应如下所示：

{
  "data": null,
  "errors": [
    {
      "message": "The conditional request failed (Service: AmazonDynamoDBv2; Status Code: 400; Error Code: ConditionalCheckFailedException; Request ID: ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGHIJKLMNOPQRSTUVWXYZ)"
      "errorType": "DynamoDB:ConditionalCheckFailedException",
      "data": {
        "Name": "Steve",
        "theVersion": 8
      },
      ...
    }
  ]
}

另外，如果返回的对象中的任何字段在更改成功后已由其他解析程序填充，则当在 error 部分中返回此对象时，将不会对这些字段进行解析。

遵循“自定义”策略

当关注Custom策略，Amazon AppSync DynamoDB 解析程序将调用 Lambda 函数以决定后续操作。Lambda 函数选择下列选项之一：

Lambda 调用请求

这些区域有：Amazon AppSync DynamoDB 解析程序将调用在lambdaArn. 它将使用在数据源上配置的相同 service-role-arn。调用的负载具有以下结构：

{
    "arguments": { ... },
    "requestMapping": {... },
    "currentValue": { ... },
    "resolver": { ... },
    "identity": { ... }
}

字段定义如下：

负载的完整示例：

{
    "arguments": {
        "id": "1",
        "name": "Steve",
        "expectedVersion": 1
    },
    "requestMapping": {
        "version" : "2017-02-28",
        "operation" : "PutItem",
        "key" : {
           "id" : { "S" : "1" }
        },
        "attributeValues" : {
           "name" : { "S" : "Steve" },
           "version" : { "N" : 2 }
        },
        "condition" : {
           "expression" : "version = :expectedVersion",
           "expressionValues" : {
               ":expectedVersion" : { "N" : 1 }
           },
           "equalsIgnore": [ "version" ]
        }
    },
    "currentValue": {
        "id" : { "S" : "1" },
        "name" : { "S" : "Steve" },
        "version" : { "N" : 8 }
    },
    "resolver": {
        "tableName": "People",
        "awsRegion": "us-west-2",
        "parentType": "Mutation",
        "field": "updatePerson",
        "outputType": "Person"
    },
    "identity": {
        "accountId": "123456789012",
        "sourceIp": "x.x.x.x",
        "user": "AIDAAAAAAAAAAAAAAAAAA",
        "userArn": "arn:aws:iam::123456789012:user/appsync"
    }
}

Lambda 调用响应

Lambda 函数可以检查调用负载并应用任何业务逻辑，以决定Amazon AppSync DynamoDB 解析器应处理该故障。有三种选项可用于处理条件检查失败：

在下面的示例中，Lambda 函数处理失败的 PutItem 请求。业务逻辑将查看进行调用的用户。如果是由jeffTheAdmin，它会重试请求，更新version和expectedVersion来自当前位于 DynamoDB 中的项目。否则，业务逻辑将拒绝更改。

exports.handler = (event, context, callback) => {
    console.log("Event: "+ JSON.stringify(event));

    // Business logic goes here.

    var response;
    if ( event.identity.user == "jeffTheAdmin" ) {
        response = {
            "action" : "retry",
            "retryMapping" : {
                "attributeValues" : event.requestMapping.attributeValues,
                "condition" : {
                    "expression" : event.requestMapping.condition.expression,
                    "expressionValues" : event.requestMapping.condition.expressionValues
                }
            }
        }
        response.retryMapping.attributeValues.version = { "N" : event.currentValue.version.N + 1 }
        response.retryMapping.condition.expressionValues[':expectedVersion'] = event.currentValue.version

    } else {
        response = { "action" : "reject" }
    }

    console.log("Response: "+ JSON.stringify(response))
    callback(null, response)
};

事务条件表达式

事务条件表达式可用于 TransactWriteItems 中所有四种类型的操作的请求映射模板，即 PutItem、DeleteItem、UpdateItem 和 ConditionCheck。

对于 PutItem、DeleteItem 和 UpdateItem，事务条件表达式是可选的。对于 ConditionCheck，事务条件表达式是必需的。

示例 1

以下事务 DeleteItem 映射文档没有条件表达式。因此，它会删除 DynamoDB 中的项目。

{
   "version": "2018-05-29",
   "operation": "TransactWriteItems",
   "transactItems": [
      {
         "table": "posts",
         "operation": "DeleteItem",
         "key": {
            "id": { "S" : "1" }
         }
      }
   ]
}

示例 2

以下事务型 DeleteItem 映射文档确实有一个事务条件表达式，只有当该文章的作者等于某个名称时，才允许操作成功。

{
   "version": "2018-05-29",
   "operation": "TransactWriteItems",
   "transactItems": [
      {
         "table": "posts",
         "operation": "DeleteItem",
         "key": {
            "id": { "S" : "1" }
         }
         "condition": {
            "expression": "author = :author",
            "expressionValues": {
               ":author": { "S" : "Chunyan" }
            }
         }
      }
   ]
}

如果条件检查失败，则会导致 TransactionCanceledException，错误详细信息将在 $ctx.result.cancellationReasons 中返回。请注意，默认情况下，DynamoDB 中使条件检查失败的旧项目将在中返回$ctx.result.cancellationReasons

指定条件

PutItem、UpdateItem 和 DeleteItem 请求映射文档都允许指定可选的 condition 部分。如果省略，则不会进行条件检查。如果指定，条件必须为 true，操作才能成功。ConditionCheck 必须具有要指定的 condition 部分。条件必须为 true，整个事务才能成功。

condition 部分具有以下结构：

"condition": {
    "expression": "someExpression",
    "expressionNames": {
        "#foo": "foo"
    },
    "expressionValues": {
        ":bar": ... typed value
    },
    "returnValuesOnConditionCheckFailure": false
}

下列字段指定条件：