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

DynamoDB 解析程序映射模板参考

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

GetItem

GetItem 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 GetItem 请求，并使您能够指定：

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 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 PutItem 请求，并使您能够指定以下各项：

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 请求映射文档使您能够告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 UpdateItem 请求，并允许您指定以下各项：

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 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 DeleteItem 请求，并使您能够指定以下各项：

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 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 Query 请求，并使您能够指定以下各项：

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 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 Scan 请求，并使您能够指定以下各项：

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 表中检索所有结果，然后仅接收自上次查询（增量更新）以来更改的数据。只能对版本化的 DynamoDB 数据源发出 Sync 请求。您可以指定：

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 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 BatchGetItem 请求以检索多个项目，可能会跨多个表。对于此请求模板，您必须指定以下各项：

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

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 块中。

有关更完整的示例，请遵循此处的 AppSync 的 DynamoDB 批处理教程教程：DynamoDB 批处理解析程序。

BatchDeleteItem

BatchDeleteItem 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 BatchWriteItem 请求以删除多个项目，可能跨多个表。对于此请求模板，您必须指定以下各项：

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

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 块中。

有关更完整的示例，请遵循此处的 AppSync 的 DynamoDB 批处理教程教程：DynamoDB 批处理解析程序。

BatchPutItem

BatchPutItem 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 BatchWriteItem 请求以放置多个项目，可能跨多个表。对于此请求模板，您必须指定以下各项：

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

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 块中。

有关更完整的示例，请遵循此处的 AppSync 的 DynamoDB 批处理教程教程：DynamoDB 批处理解析程序。

TransactGetItems

TransactGetItems 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 TransactGetItems 请求以检索多个项目，可能会跨多个表。对于此请求模板，您必须指定以下各项：

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 请求映射文档可让您告知 AWS AppSync DynamoDB 解析程序向 DynamoDB 发出 TransactWriteItems 请求以写入多个项目，可能跨多个表。对于此请求模板，您必须指定以下各项：

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 事务解析程序操作。

类型系统（请求映射）

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

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

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

{ "S" : "identifier" }

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

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

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

支持的类型

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

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

类型系统（响应映射）

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

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

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

则 AWS AppSync DynamoDB 解析程序将其转换为 GraphQL 和 JSON 类型，如下所示：

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

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

筛选条件

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

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

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

字段定义如下：

示例

下面是映射模板的筛选条件部分，其中，如果标题以 title 参数开头，则仅返回从 DynamoDB 中检索的条目。

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

条件表达式

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

AWS 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)"
   }
}

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

下列字段指定条件：

其余字段告知 AWS AppSync DynamoDB 解析程序如何处理条件检查失败：

处理条件检查失败

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

此过程的流程图为：

检查所需结果

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

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

遵循“拒绝”策略

当遵循 Reject 策略时，AWS AppSync DynamoDB 解析程序将对更改返回错误，也会在 GraphQL 响应的 error 部分的 data 字段中返回 DynamoDB 中对象的当前值。从 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 策略时，AWS AppSync DynamoDB 解析程序将调用 Lambda 函数以决定后续操作。Lambda 函数选择下列选项之一：

Lambda 调用请求

AWS AppSync DynamoDB 解析程序将调用在 lambdaArn 中指定的 Lambda 函数。它将使用在数据源上配置的相同 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 函数可以检查调用负载并应用任何业务逻辑，以决定 AWS AppSync DynamoDB 解析程序应如何处理失败。有三种选项可用于处理条件检查失败：

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

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
}

下列字段指定条件：