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

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

DynamoDB 的解析器映射模板参考

Amazon AppSync DynamoDB 解析器使您能够使用 GraphQL 存储和检索账户中现有 Amazon DynamoDB 表中的数据。此解析器的工作原理是允许您将传入的 GraphQL 请求映射到 DynamoDB 调用，然后将 DynamoDB 响应映射回 GraphQL。本节介绍支持的 DynamoDB 操作的映射模板。

GetItem

GetItem请求映射文档允许您告诉Amazon AppSync DynamoDB 解析器向 DynamoDBGetItem 发出请求，并允许您指定：

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

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

字段定义如下：

GetItem 字段

从 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 解析器向 DynamoDBPutItem 发出请求，并允许您指定以下内容：

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

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

字段定义如下：

PutItem 字段

写入 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 解析器向 DynamoDBUpdateItem 发出请求，并允许您指定以下内容：

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

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

字段定义如下：

UpdateItem 字段

在 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 解析器向 DynamoDBDeleteItem 发出请求，并允许您指定以下内容：

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

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

字段定义如下：

DeleteItem 字段

从 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请求映射文档允许您告诉Amazon AppSync DynamoDB 解析器向 DynamoDBQuery 发出请求，并允许您指定以下内容：

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" | "ALL_PROJECTED_ATTRIBUTES" | "SPECIFIC_ATTRIBUTES",
    "filter" : {
        ...
    },
    "projection" : {
        ...
    }
}

字段定义如下：

查询字段

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 解析器向 DynamoDBScan 发出请求，并允许您指定以下内容：

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

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

字段定义如下：

扫描字段

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",
    "basePartitionKey": "Base Tables PartitionKey",
    "deltaIndexName": "delta-index-name",
    "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 解析器向 DynamoDB 发出BatchGetItem请求，以检索多个项目，可能是跨多个表检索多个项目。对于此请求模板，您必须指定以下各项：

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,            
            "projection" : {
                 ...
            }
        },
        "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,
            "projection" : {
                 ...
            }
        }
    }
}

字段定义如下：

BatchGetItem 字段

要记住的事项：

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

{
  "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 Batch 教程进行操作：DynamoDB 批处理解析器。

BatchDeleteItem

BatchDeleteItem请求映射文档允许您告诉Amazon AppSync DynamoDB 解析器向 DynamoDBBatchWriteItem 发出请求，请求删除多个项目，可能跨多个表。对于此请求模板，您必须指定以下各项：

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
        }],
    }
}

字段定义如下：

BatchDeleteItem 字段

要记住的事项：

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

{
  "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 Batch 教程进行操作：DynamoDB 批处理解析器。

BatchPutItem

BatchPutItem请求映射文档允许您告诉Amazon AppSync DynamoDB 解析器向 DynamoDBBatchWriteItem 发出请求，请求放置多个项目，可能跨多个表。对于此请求模板，您必须指定以下各项：

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
        }],
    }
}

字段定义如下：

BatchPutItem 字段

要记住的事项：

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

{
  "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 Batch 教程进行操作：DynamoDB 批处理解析器。

TransactGetItems

TransactGetItems请求映射文档允许您告诉Amazon 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
           },
           "projection" : {
                ...
           }
       },
       ## Second request item
       {
           "table": "table2",
           "key": {
               "foo": ... typed value,
               "bar": ... typed value
           },
           "projection" : {
                ...
           }
       }
    ]
}

字段定义如下：

TransactGetItems 字段

要记住的事项：

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

{
    "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 事务教程教程教程：DynamoDB 事务解析器。

TransactWriteItems

TransactWriteItems请求映射文档允许您告诉Amazon AppSync DynamoDB 解析器向 DynamoDBTransactWriteItems 发出请求，请求写入多个项目，可能写入多个表。对于此请求模板，您必须指定以下各项：

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
           }
       }
    ]
}

TransactWriteItems 字段

要记住的事项：

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

{
    "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 事务教程教程教程：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值分配给某个key部分（可能在GetItem请求映射文档中）中的id字段。

"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

使用Query和Scan操作在 DynamoDB 中查询对象时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)
    }
}

条件表达式

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

Amazon AppSync DynamoDB 解析器允许在PutItemUpdateItem、和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 解析器会在 GraphQL 响应error部分的data字段中返回变异错误以及 DynamoDB 中对象的当前值。但是，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 解析器会在 GraphQL 响应error部分的data字段中返回变异错误和 DynamoDB 中对象的当前值。但是，Amazon AppSync DynamoDB 解析器提供了一些额外功能，可帮助开发人员处理一些常见的边缘案例：

此过程的流程图为：

检查所需的结果

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

如果 DynamoDB 中对象的当前状态与预期结果不同，则Amazon AppSync DynamoDB 解析器将遵循配置的策略，拒绝突变或调用 Lambda 函数来确定下一步要做什么。

遵循 “拒绝” 策略

遵循Reject策略时，Amazon 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策略时，Amazon AppSync DynamoDB 解析器调用 Lambda 函数来决定下一步要做什么。Lambda 函数选择下列选项之一：

Lambda 调用请求

Amazon AppSync 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 函数可以检查调用负载并应用任何业务逻辑来决定Amazon AppSync DynamoDB 解析器应如何处理故障。有三种选项可用于处理条件检查失败：

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

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。

对于PutItemDeleteItem、和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
}

下列字段指定条件：

投影

使用GetItem、Scan、、和TransactGetItems操作读取 DynamoDB 中的对象时，您可以选择指定用于标识所需属性的投影。QueryBatchGetItem投影具有以下结构，类似于滤镜：

"projection" : {
    "expression" : "projection expression"
    "expressionNames" : {
        "#name" : "name",
    }
}

字段定义如下：

示例 1

以下示例是 VTL 映射模板的投影部分，其中仅从 DynamoDB 返回id属author性和和：

"projection" : {
    "expression" : "#author, id",
    "expressionNames" : {
        "#author" : "author"
    }
}