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

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

DynamoDB 解析程序映射模板参考

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

GetItem

这些区域有：GetItem请求映射文档让你告诉AmazonAppSync 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 类型转换的更多信息，请参阅。类型系统（响应映射）.

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

Example

下面是 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请求映射文档让你告诉AmazonAppSync 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请求映射文档使你能够告诉AmazonAppSync 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请求映射文档让你告诉AmazonAppSync 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请求映射文档让你告诉AmazonAppSync 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
}

字段定义如下：

Example

下面是 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请求映射文档让你告诉AmazonAppSync 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请求映射文档让你告诉AmazonAppSync 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 教程与 App教程：DynamoDB Batch 解析程序.

BatchDeleteItem

这些区域有：BatchDeleteItem请求映射文档让你告诉AmazonAppSync 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 教程与 App教程：DynamoDB Batch 解析程序.

BatchPutItem

这些区域有：BatchPutItem请求映射文档让你告诉AmazonAppSync 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 教程与 App教程：DynamoDB Batch 解析程序.

TransactGetItems

这些区域有：TransactGetItems请求映射文档让你可以告诉AmazonAppSync 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 中。

有关更完整的示例，请遵循此处的 AppSync 的 DynamoDB 事务教程与 AppSync教程：DynamoDB 事务处理程序.

TransactWriteItems

这些区域有：TransactWriteItems请求映射文档让你告诉AmazonAppSync 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 中。

有关更完整的示例，请遵循此处的 AppSync 的 DynamoDB 事务教程与 AppSync教程：DynamoDB 事务处理程序.

类型系统（请求映射）

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

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

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

{ "S" : "identifier" }

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

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

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

支持的类型

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

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

类型系统（响应映射）

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

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

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

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

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

本部分介绍如何AmazonAppSync 会转换以下 DynamoDB 标量、文档和集类型：

Filters

当使用 DynamoDB 中查询对象时Query和Scan操作，您可以选择指定filter它会评估结果并仅返回所需值。

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

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

字段定义如下：

Example

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

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

条件表达式

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

这些区域有：AmazonAppSync 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)"
   }
}

默认情况下，如果条件检查失败，则AmazonAppSync DynamoDB 解析程序对更改返回错误，并在 DynamoDB 中返回中对象的当前值。data中字段中的errorGraphQL 响应的部分。但是，AmazonAppSync 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:..."
    }
}

下列字段指定条件：

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

处理条件检查失败

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

此过程的流程图为：

检查所需结果

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

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

遵循“拒绝”策略

当关注Reject策略，AmazonAppSync 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策略，AmazonAppSync DynamoDB 解析程序将调用 Lambda 函数以决定接下来做什么。Lambda 函数选择下列选项之一：

Lambda 调用请求

这些区域有：AmazonAppSync DynamoDB 解析程 Lambda 将调用在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 函数可以检查调用负载并应用任何业务逻辑，以决定如何使用AmazonAppSync 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
}

下列字段指定条件：