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 解析器向 DynamoDB 发出 GetItem 请求，并允许您指定：

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

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

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

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

通过使用 Query 请求映射文档，您可以指示 Amazon 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" | "ALL_PROJECTED_ATTRIBUTES" | "SPECIFIC_ATTRIBUTES",
    "filter" : {
        ...
    },
    "projection" : {
        ...
    }
}

字段定义如下：

Query 字段

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

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

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

字段定义如下：

Scan 字段

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",
    "basePartitionKey": "Base Tables PartitionKey",
    "deltaIndexName": "delta-index-name",
    "limit" : 10,
    "nextToken" : "aPaginationToken",
    "lastSync" :  1550000000000,
    "filter" : {
        ...
    }
}

字段定义如下：

Sync 字段

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

BatchDeleteItem

通过使用 BatchDeleteItem 请求映射文档，您可以指示 Amazon AppSync DynamoDB 解析器对 DynamoDB 发出 BatchWriteItem 请求以删除多个项目（可能位于多个表中）。对于此请求模板，您必须指定以下各项：

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

BatchPutItem

通过使用 BatchPutItem 请求映射文档，您可以指示 Amazon AppSync DynamoDB 解析器对 DynamoDB 发出 BatchWriteItem 请求以放置多个项目（可能位于多个表中）。对于此请求模板，您必须指定以下各项：

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 批处理教程“教程：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 解析器对 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
           }
       }
    ]
}

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在 GraphQL 和 DynamoDB 之间转换时，AppSync 需要一些提示，否则，它必须对如何在表中设置数据结构做出一些假设。

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

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

{ "S" : "identifier" }

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

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

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

支持的类型

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

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

类型系统（响应映射）

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

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

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

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

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

本节介绍了 Amazon AppSync 如何转换以下 DynamoDB 标量、文档和集类型：

Filters

在使用 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 和 DeleteItem DynamoDB 操作变更 DynamoDB 中的对象时，您可以选择指定一个条件表达式，以根据执行操作之前 DynamoDB 中的已有对象状态控制请求是否应成功。

Amazon AppSync DynamoDB 解析器允许在 PutItem、UpdateItem 和 DeleteItem 请求映射文档中指定条件表达式，并提供在条件失败并且未更新对象时遵循的策略。

示例 1

以下 PutItem 映射文档没有条件表达式。因此，即使已存在具有相同键的项目，它也会将项目放置在 DynamoDB 中，从而覆盖现有的项目。

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

示例 2

以下 PutItem 映射文档确实具有一个条件表达式，只有在 DynamoDB 中不 存在具有相同键的项目时，该操作才会成功。

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

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

在处理条件检查失败一节中更详细地介绍了这些内容。

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

指定条件

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”策略

在遵循 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”策略

在遵循 Custom 策略时，Amazon AppSync DynamoDB 解析器调用 Lambda 函数以决定后续操作。Lambda 函数选择下列选项之一：

Lambda 调用请求

Amazon 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 函数可以检查调用负载，并应用任何业务逻辑以决定 Amazon 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
}

下列字段指定条件：

投影

在使用 GetItem、Scan、Query、BatchGetItem 和 TransactGetItems 操作读取 DynamoDB 中的对象时，您可以选择指定一个投影以指定所需的属性。投影具有以下结构，与筛选条件类似：

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

字段定义如下：

示例 1

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

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