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

# AWS AppSync DynamoDB 的解析器映射模板参考
<a name="resolver-mapping-template-reference-dynamodb"></a>

**注意**  
我们现在主要支持 APPSYNC\$1JS 运行时系统及其文档。请考虑使用 APPSYNC\$1JS 运行时系统和[此处](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)的指南。

D AWS AppSync ynamoDB 函数允许您使用 [GraphQL](https://graphql.org) 存储和检索账户中现有亚马逊 DynamoDB 表中的数据，方法是将传入的 GraphQL 请求映射到 DynamoDB 调用，然后将 DynamoDB 响应映射回 GraphQL。本节介绍了支持的 DynamoDB 操作的请求和响应处理程序：
+  [GetItem](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-getitem.html)-该 GetItem 请求允许您告诉 DynamoDB 函数向 DynamoDB 发出 GetItem 请求，并允许您在 DynamoDB 中指定项目的密钥以及是否使用一致性读取。
+  [ PutItem ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-putitem.html)- PutItem 请求映射文档允许您告诉 DynamoDB 函数向 DynamoDB 发出 PutItem 请求，并允许您指定 DynamoDB 中项目的密钥、项目的全部内容（由键和属性值组成）以及操作成功所需的条件。
+  [ UpdateItem ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-updateitem.html)-该 UpdateItem 请求允许您告诉 DynamoDB 函数向 DynamoDB 发出 UpdateItem 请求，并允许您在 DynamoDB 中指定项目的密钥、描述如何在 DynamoDB 中更新项目的更新表达式以及操作成功的条件。
+  [ DeleteItem ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-deleteitem.html)-该 DeleteItem 请求允许您告诉 DynamoDB 函数向 DynamoDB 发出 DeleteItem 请求，并允许您在 DynamoDB 中指定项目的密钥以及操作成功的条件。
+  [Query](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-query.html)：通过使用 Query 请求对象，您可以指示 DynamoDB 解析器对 DynamoDB 发出 Query 请求，并可以指定键表达式、要使用的索引、其他筛选条件、要返回的项目数量、是否使用一致性读取、查询方向（向前或向后）以及分页标记。
+  [Scan](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-scan.html)：通过使用 Scan 请求，您可以指示 DynamoDB 函数对 DynamoDB 发出 Scan 请求，并可以指定排除结果的筛选条件、要使用的索引、要返回的项目数量、是否使用一致性读取、分页令牌和并行扫描。
+  [Sync](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-sync.html)：通过使用 Sync 请求对象，您可以从 DynamoDB 表中检索所有结果，然后仅接收自上次查询以来更改的数据（增量更新）。只能向版本控制的 DynamoDB 数据来源发出 Sync 请求。您可以指定排除结果的筛选条件、要返回的项目数量、分页令牌以及上次同步操作的启动时间。
+  [ BatchGetItem ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-batch-get-item.html)- BatchGetItem 请求对象允许您告诉 DynamoDB 函数向 DynamoDB 发出 BatchGetItem 请求，以检索多个项目，可能跨多个表。对于此请求对象，您必须指定要从中检索项目的表名称，以及要从每个表中检索的项目的键。
+  [ BatchDeleteItem ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-batch-delete-item.html)- BatchDeleteItem 请求对象允许您告诉 DynamoDB 函数向 DynamoDB 发出 BatchWriteItem 请求，要求删除多个项目，可能跨多个表。对于此请求对象，您必须指定要从中删除项目的表名称，以及要从每个表中删除的项目的键。
+  [ BatchPutItem ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-batch-put-item.html)- BatchPutItem 请求对象允许您告诉 DynamoDB 函数向 DynamoDB 发出 BatchWriteItem 请求，要求将多个项目放置在多个表中。对于此请求对象，您必须指定要放置项目的表名称和要放入每个表中的完整项目。
+  [ TransactGetItems ](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-transact-get-items.html)- TransactGetItems 请求对象允许您告诉 DynamoDB 函数向 DynamoDB 发出 TransactGetItems 请求，以检索多个项目，可能跨多个表。对于此请求对象，您必须指定要从中检索项目的每个请求项目的表名称，以及要从每个表中检索的每个请求项目的键。
+  [ TransactWriteItems ](https://docs.aws.amazon.com/appsync/latest/devguide/js-aws-appsync-resolver-reference-dynamodb-transact-write-items.html)- TransactWriteItems 请求对象允许您告诉 DynamoDB 函数向 DynamoDB 发出写入多个项目（可能写入多个表）的 TransactWriteItems 请求。对于此请求对象，您必须指定每个请求项目的目标表名称、要执行的每个请求项目的操作以及要写入的每个请求项目的键。
+  [类型系统（请求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.html)-详细了解 DynamoDB 类型如何集成到请求中。 AWS AppSync 
+  [类型系统（响应映射）](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.html)：详细了解 DynamoDB 类型如何在响应有效载荷中自动转换为 GraphQL 或 JSON。
+  [筛选条件](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-filter.html)：详细了解查询和扫描操作的筛选条件。
+  [条件表达式](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-condition-expressions.html)-了解有关 PutItem UpdateItem、和 DeleteItem 运算的条件表达式的更多信息。
+  [交易条件表达式](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-transaction-condition-expressions.html)-了解有关 TransactWriteItems 操作条件表达式的更多信息。
+  [投影](https://docs.aws.amazon.com/appsync/latest/devguide/aws-appsync-resolver-mapping-template-reference-dynamodb-projections.html)：详细了解如何在读取操作中指定属性。

# GetItem
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-getitem"></a>

`GetItem`请求映射文档允许您告诉 D AWS AppSync ynamoDB 解析器向 DynamoDB 发出`GetItem`请求，并允许您指定：
+ DynamoDB 中的项目的键
+ 是否使用一致性读取

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

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

字段定义如下：

## GetItem 字段
<a name="getitem-list"></a>

### GetItem 字段列表
<a name="getitem-list-col"></a>

 **`version`**   
模板定义版本。目前支持 `2017-02-28` 和 `2018-05-29`。该值为必填项。

 **`operation`**   
要执行的 DynamoDB 操作。要执行 `GetItem` DynamoDB 操作，该字段必须设置为 `GetItem`。该值为必填项。

 **`key`**   
DynamoDB 中的项目的键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。该值为必填项。

 **`consistentRead`**   
是否对 DynamoDB 执行强一致性读取。这是可选的，默认值为 `false`。

**`projection`**  
用于指定从 DynamoDB 操作返回的属性的投影。有关投影的更多信息，请参阅[投影](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-projections)。该字段是可选的。

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

有关 DynamoDB 类型转换的更多信息，请参阅[类型系统（响应映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)。

有关响应映射模板的更多信息，请参阅[解析器映射模板概述](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)。

## 示例
<a name="example"></a>

以下示例是 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 文档](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html)。

# PutItem
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-putitem"></a>

`PutItem`请求映射文档允许您告诉 D AWS AppSync ynamoDB 解析器向 DynamoDB 发出`PutItem`请求，并允许您指定以下内容：
+ DynamoDB 中的项目的键
+ 项目的完整内容（包括 `key` 和 `attributeValues`）
+ 操作成功执行的条件

`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 字段
<a name="putitem-list"></a>

### PutItem 字段列表
<a name="putitem-list-col"></a>

 **`version`**   
模板定义版本。目前支持 `2017-02-28` 和 `2018-05-29`。该值为必填项。

 **`operation`**   
要执行的 DynamoDB 操作。要执行 `PutItem` DynamoDB 操作，该字段必须设置为 `PutItem`。该值为必填项。

 **`key`**   
DynamoDB 中的项目的键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。该值为必填项。

 **`attributeValues`**   
要放入 DynamoDB 中的项目的其余属性。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。该字段是可选的。

 **`condition`**   
根据 DynamoDB 中已有的对象状态，确定请求是否应成功的条件。如果未指定条件，则 `PutItem` 请求将覆盖该项目的任何现有条目。有关条件的更多信息，请参阅[条件表达式](aws-appsync-resolver-mapping-template-reference-dynamodb-condition-expressions.md)。该值为可选项。

 **`_version`**   
表示项目的最新已知版本的数值。该值为可选项。该字段用于*冲突检测*，仅受版本控制的数据来源支持。

**`customPartitionKey`**  
启用后，此字符串值将修改启用版本控制后增量同步表使用的`ds_sk`和`ds_pk`记录的格式（有关更多信息，请参阅*《AWS AppSync 开发人员指南》*中的[冲突检测和同步](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)）。如果启用，还会启用 `populateIndexFields` 条目处理。该字段是可选的。

**`populateIndexFields`**  
一个布尔值，在**与 `customPartitionKey` 一起**启用时，它为增量同步表中的每个记录创建新条目，具体来说是在 `gsi_ds_pk` 和 `gsi_ds_sk` 列中创建新条目。有关更多信息，请参阅《AWS AppSync 开发人员指南》中的[冲突检测和同步](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)。**该字段是可选的。

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

有关 DynamoDB 类型转换的更多信息，请参阅[类型系统（响应映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)。

有关响应映射模板的更多信息，请参阅[解析器映射模板概述](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)。

## 示例 1
<a name="example-1"></a>

以下示例是 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
<a name="example-2"></a>

以下示例是 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 文档](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html)。

# UpdateItem
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-updateitem"></a>

`UpdateItem`请求映射文档允许您告诉 D AWS AppSync ynamoDB 解析器向 DynamoDB 发出`UpdateItem`请求，并允许您指定以下内容：
+ DynamoDB 中的项目的键
+ 描述如何更新 DynamoDB 中的项目的更新表达式
+ 操作成功执行的条件

`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 字段
<a name="updateitem-list"></a>

### UpdateItem 字段列表
<a name="updateitem-list-col"></a>

 **`version`**   
模板定义版本。目前支持 `2017-02-28` 和 `2018-05-29`。该值为必填项。

 **`operation`**   
要执行的 DynamoDB 操作。要执行 `UpdateItem` DynamoDB 操作，该字段必须设置为 `UpdateItem`。该值为必填项。

 **`key`**   
DynamoDB 中的项目的键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。该值为必填项。

 **`update`**   
`update` 部分用于指定一个更新表达式，以描述如何更新 DynamoDB 中的项目。有关如何编写更新表达式的更多信息，请参阅 [DynamoDB 文档 UpdateExpressions ](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)。此部分是必需的。  
`update` 部分有三个组成部分：    
** `expression` **  
更新表达式。该值为必填项。  
** `expressionNames` **  
以键值对形式替换表达式属性*名称* 占位符。键对应于 `expression` 中使用的名称占位符，值必须是与 DynamoDB 中的项目的属性名称对应的字符串。该字段是可选的，只应填充 `expression` 中使用的表达式属性名称占位符的替换内容。  
** `expressionValues` **  
以键值对形式替换表达式属性*值* 占位符。键对应于 `expression` 中使用的值占位符，而值必须为类型化值。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。必须指定此值。该字段是可选的，只应填充 `expression` 中使用的表达式属性值占位符的替换内容。

 **`condition`**   
根据 DynamoDB 中已有的对象状态，确定请求是否应成功的条件。如果未指定条件，则 `UpdateItem` 请求将更新现有条目，而不考虑其当前状态。有关条件的更多信息，请参阅[条件表达式](aws-appsync-resolver-mapping-template-reference-dynamodb-condition-expressions.md)。该值为可选项。

 **`_version`**   
表示项目的最新已知版本的数值。该值为可选项。该字段用于*冲突检测*，仅受版本控制的数据来源支持。

**`customPartitionKey`**  
启用后，此字符串值将修改启用版本控制后增量同步表使用的`ds_sk`和`ds_pk`记录的格式（有关更多信息，请参阅*《AWS AppSync 开发人员指南》*中的[冲突检测和同步](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)）。如果启用，还会启用 `populateIndexFields` 条目处理。该字段是可选的。

**`populateIndexFields`**  
一个布尔值，在**与 `customPartitionKey` 一起**启用时，它为增量同步表中的每个记录创建新条目，具体来说是在 `gsi_ds_pk` 和 `gsi_ds_sk` 列中创建新条目。有关更多信息，请参阅《AWS AppSync 开发人员指南》中的[冲突检测和同步](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)。**该字段是可选的。

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

有关 DynamoDB 类型转换的更多信息，请参阅[类型系统（响应映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)。

有关响应映射模板的更多信息，请参阅[解析器映射模板概述](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)。

## 示例 1
<a name="id3"></a>

以下示例是 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
<a name="id4"></a>

以下示例是 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 文档](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html)。

# DeleteItem
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-deleteitem"></a>

`DeleteItem`请求映射文档允许您告诉 D AWS AppSync ynamoDB 解析器向 DynamoDB 发出`DeleteItem`请求，并允许您指定以下内容：
+ DynamoDB 中的项目的键
+ 操作成功执行的条件

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

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

字段定义如下：

## DeleteItem 字段
<a name="deleteitem-list"></a>

### DeleteItem 字段列表
<a name="deleteitem-list-col"></a>

** `version` **  
模板定义版本。目前支持 `2017-02-28` 和 `2018-05-29`。该值为必填项。

** `operation` **  
要执行的 DynamoDB 操作。要执行 `DeleteItem` DynamoDB 操作，该字段必须设置为 `DeleteItem`。该值为必填项。

** `key` **  
DynamoDB 中的项目的键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。该值为必填项。

** `condition` **  
根据 DynamoDB 中已有的对象状态，确定请求是否应成功的条件。如果未指定条件，则 `DeleteItem` 请求将删除项目，而不考虑其当前状态。有关条件的更多信息，请参阅[条件表达式](aws-appsync-resolver-mapping-template-reference-dynamodb-condition-expressions.md)。该值为可选项。

** `_version` **  
表示项目的最新已知版本的数值。该值为可选项。该字段用于*冲突检测*，仅受版本控制的数据来源支持。

**`customPartitionKey`**  
启用后，此字符串值将修改启用版本控制后增量同步表使用的`ds_sk`和`ds_pk`记录的格式（有关更多信息，请参阅*《AWS AppSync 开发人员指南》*中的[冲突检测和同步](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)）。如果启用，还会启用 `populateIndexFields` 条目处理。该字段是可选的。

**`populateIndexFields`**  
一个布尔值，在**与 `customPartitionKey` 一起**启用时，它为增量同步表中的每个记录创建新条目，具体来说是在 `gsi_ds_pk` 和 `gsi_ds_sk` 列中创建新条目。有关更多信息，请参阅《AWS AppSync 开发人员指南》中的[冲突检测和同步](https://docs.aws.amazon.com/appsync/latest/devguide/conflict-detection-and-sync.html)。**该字段是可选的。

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

有关 DynamoDB 类型转换的更多信息，请参阅[类型系统（响应映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)。

有关响应映射模板的更多信息，请参阅[解析器映射模板概述](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)。

## 示例 1
<a name="id6"></a>

以下示例是 GraphQL 变更 `deleteItem(id: ID!)` 的映射模板。如果具有此 ID 的项目存在，它将被删除。

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

## 示例 2
<a name="id7"></a>

以下示例是 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 文档](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteItem.html)。

# Query
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-query"></a>

`Query`请求映射文档允许您告诉 D AWS AppSync ynamoDB 解析器向 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 字段
<a name="query-list"></a>

### Query 字段列表
<a name="query-list-col"></a>

** `version` **  
模板定义版本。目前支持 `2017-02-28` 和 `2018-05-29`。该值为必填项。

** `operation` **  
要执行的 DynamoDB 操作。要执行 `Query` DynamoDB 操作，该字段必须设置为 `Query`。该值为必填项。

** `query` **  
`query` 部分用于指定一个键条件表达式，用于描述要从 DynamoDB 中检索哪些项目。有关如何编写关键条件表达式的更多信息，请参阅 [DynamoDB 文档 KeyConditions ](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.KeyConditions.html)。必须指定此部分。    
** `expression` **  
查询表达式。必须指定该字段。  
** `expressionNames` **  
以键值对形式替换表达式属性*名称* 占位符。键对应于 `expression` 中使用的名称占位符，值必须是与 DynamoDB 中的项目的属性名称对应的字符串。该字段是可选的，只应填充 `expression` 中使用的表达式属性名称占位符的替换内容。  
** `expressionValues` **  
以键值对形式替换表达式属性*值* 占位符。键对应于 `expression` 中使用的值占位符，而值必须为类型化值。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。该值为必填项。该字段是可选的，只应填充 `expression` 中使用的表达式属性值占位符的替换内容。

** `filter` **  
另一个筛选条件，该筛选条件可用于在从 DynamoDB 返回结果之前先筛选结果。有关筛选条件的更多信息，请参阅[筛选条件](aws-appsync-resolver-mapping-template-reference-dynamodb-filter.md)。该字段是可选的。

** `index` **  
要查询的索引的名称。除了哈希键的主键索引以外，您还可以通过 DynamoDB 查询操作扫描本地二级索引和全局二级索引。如果指定，这会指示 DynamoDB 查询指定的索引。如果省略，则将查询主键索引。

** `nextToken` **  
继续之前查询的分页标记。这应已从之前查询中获得。该字段是可选的。

** `limit` **  
要评估的最大项目数（不一定是匹配项目数）。该字段是可选的。

** `scanIndexForward` **  
一个布尔值，指示是向前还是向后查询。该字段是可选的，默认值为 `true`。

** `consistentRead` **  
一个布尔值，用于指示在查询 DynamoDB 时是否使用一致性读取。该字段是可选的，默认值为 `false`。

** `select` **  
默认情况下， AWS AppSync DynamoDB 解析器仅返回投影到索引中的属性。如果需要更多属性，则可以设置该字段。该字段是可选的。支持的值为：    
** `ALL_ATTRIBUTES` **  
返回指定的表或索引中的所有项目属性。如果您查询本地二级索引，则 DynamoDB 从父表中为索引中的每个匹配项目获取整个项目。如果索引配置为投影所有项目属性，则可以从本地二级索引中获得所有数据，而不要求提取。  
** `ALL_PROJECTED_ATTRIBUTES` **  
仅在查询索引时才允许。检索已投影到索引的所有属性。如果索引配置为投影所有属性，则此返回值等同于指定 `ALL_ATTRIBUTES`。  
**`SPECIFIC_ATTRIBUTES`**  
仅返回 `projection` 的 `expression` 中列出的属性。该返回值相当于指定 `projection` 的 `Select`，而不指定 `expression` 的任何值。

**`projection`**  
用于指定从 DynamoDB 操作返回的属性的投影。有关投影的更多信息，请参阅[投影](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-projections)。该字段是可选的。

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

有关 DynamoDB 类型转换的更多信息，请参阅[类型系统（响应映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)。

有关响应映射模板的更多信息，请参阅[解析器映射模板概述](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)。

结果的结构如下所示：

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

字段定义如下：

** `items` **  
包含 DynamoDB 查询返回的项目的列表。

** `nextToken` **  
如果可能有更多结果，则 `nextToken` 包含一个分页标记，您可以在另一个请求中使用该标记。请注意，它 AWS AppSync 会加密并混淆从 DynamoDB 返回的分页令牌。这可防止您的表数据无意中泄露给调用方。另请注意，无法跨不同解析器使用这些分页标记。

** `scannedCount` **  
在应用筛选表达式（如果有）之前与查询条件表达式匹配的项目的数量。

## 示例
<a name="id9"></a>

以下示例是 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 文档](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html)。

# Scan
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-scan"></a>

`Scan`请求映射文档允许您告诉 D AWS AppSync ynamoDB 解析器向 DynamoDB 发出`Scan`请求，并允许您指定以下内容：
+ 排除结果的筛选条件
+ 要使用的索引
+ 要返回多少个项目
+ 是否使用一致性读取
+ 分页标记
+ 并行扫描

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

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

字段定义如下：

## Scan 字段
<a name="scan-list"></a>

### Scan 字段列表
<a name="scan-list-col"></a>

** `version` **  
模板定义版本。目前支持 `2017-02-28` 和 `2018-05-29`。该值为必填项。

** `operation` **  
要执行的 DynamoDB 操作。要执行 `Scan` DynamoDB 操作，该字段必须设置为 `Scan`。该值为必填项。

** `filter` **  
一个筛选条件，可用于在返回来自 DynamoDB 的结果之前对其进行筛选。有关筛选条件的更多信息，请参阅[筛选条件](aws-appsync-resolver-mapping-template-reference-dynamodb-filter.md)。该字段是可选的。

** `index` **  
要查询的索引的名称。除了哈希键的主键索引以外，您还可以通过 DynamoDB 查询操作扫描本地二级索引和全局二级索引。如果指定，这会指示 DynamoDB 查询指定的索引。如果省略，则将查询主键索引。

** `limit` **  
单次评估的最大项目数。该字段是可选的。

** `consistentRead` **  
一个布尔值，用于指示在查询 DynamoDB 时是否使用一致性读取。该字段是可选的，默认值为 `false`。

** `nextToken` **  
继续之前查询的分页标记。这应已从之前查询中获得。该字段是可选的。

** `select` **  
默认情况下， AWS AppSync DynamoDB 解析器仅返回投影到索引中的任何属性。如果需要更多属性，则可以设置该字段。该字段是可选的。支持的值为：    
** `ALL_ATTRIBUTES` **  
返回指定的表或索引中的所有项目属性。如果您查询本地二级索引，则 DynamoDB 从父表中为索引中的每个匹配项目获取整个项目。如果索引配置为投影所有项目属性，则可以从本地二级索引中获得所有数据，而不要求提取。  
** `ALL_PROJECTED_ATTRIBUTES` **  
仅在查询索引时才允许。检索已投影到索引的所有属性。如果索引配置为投影所有属性，则此返回值等同于指定 `ALL_ATTRIBUTES`。  
**`SPECIFIC_ATTRIBUTES`**  
仅返回 `projection` 的 `expression` 中列出的属性。该返回值相当于指定 `projection` 的 `Select`，而不指定 `expression` 的任何值。

** `totalSegments` **  
执行并行扫描时对表进行分区的分段数。该字段是可选的，但如果指定 `segment`，则必须指定该字段。

** `segment` **  
执行并行扫描时，此操作中的表分段。该字段是可选的，但如果指定 `totalSegments`，则必须指定该字段。

**`projection`**  
用于指定从 DynamoDB 操作返回的属性的投影。有关投影的更多信息，请参阅[投影](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-projections)。该字段是可选的。

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

有关 DynamoDB 类型转换的更多信息，请参阅[类型系统（响应映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)。

有关响应映射模板的更多信息，请参阅[解析器映射模板概述](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)。

结果的结构如下所示：

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

字段定义如下：

** `items` **  
包含 DynamoDB 扫描返回的项目的列表。

** `nextToken` **  
如果可能有更多结果，则`nextToken`包含可在其他请求中使用的分页令牌。 AWS AppSync 加密并混淆从 DynamoDB 返回的分页令牌。这可防止您的表数据无意中泄露给调用方。另外，无法跨不同的解析器使用这些分页标记。

** `scannedCount` **  
在应用筛选条件表达式（如果有）之前 DynamoDB 检索的项目数。

## 示例 1
<a name="id11"></a>

以下示例是 GraphQL 查询 `allPosts` 的映射模板。

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

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

## 示例 2
<a name="id12"></a>

以下示例是 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 文档](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html)。

# 同步
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-sync"></a>

通过使用 `Sync` 请求映射文档，您可以从 DynamoDB 表中检索所有结果，然后仅接收自上次查询以来更改的数据（增量更新）。只能对版本控制的 DynamoDB 数据来源发出 `Sync` 请求。您可以指定以下内容：
+ 排除结果的筛选条件
+ 要返回多少个项目
+ 分页标记
+ 上次 `Sync` 操作开始时间

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

```
{
    "version" : "2018-05-29",
    "operation" : "Sync",
    "basePartitionKey": "Base Tables PartitionKey",
    "deltaIndexName": "delta-index-name",
    "limit" : 10,
    "nextToken" : "aPaginationToken",
    "lastSync" :  1550000000000,
    "filter" : {
        ...
    }
}
```

字段定义如下：

## Sync 字段
<a name="sync-list"></a>

### Sync 字段列表
<a name="sync-list-col"></a>

** `version` **  
模板定义版本。当前仅支持 `2018-05-29`。该值为必填项。

** `operation` **  
要执行的 DynamoDB 操作。要执行 `Sync` 操作，该字段必须设置为 `Sync`。该值为必填项。

** `filter` **  
一个筛选条件，可用于在返回来自 DynamoDB 的结果之前对其进行筛选。有关筛选条件的更多信息，请参阅[筛选条件](aws-appsync-resolver-mapping-template-reference-dynamodb-filter.md)。该字段是可选的。

** `limit` **  
单次评估的最大项目数。该字段是可选的。如果省略，则默认限制将设置为 `100` 个项目。该字段的最大值为 `1000` 个项目。

** `nextToken` **  
继续之前查询的分页标记。这应已从之前查询中获得。该字段是可选的。

** `lastSync` **  
最后一次成功 `Sync` 操作开始的时刻（以纪元毫秒为单位）。如果指定，则仅返回 `lastSync` 之后更改的项目。该字段是可选的，只有在从初始 `Sync` 操作中检索所有页面后才能填充。如果省略，将返回*基本* 表中的结果，否则将返回*增量* 表中的结果。

**`basePartitionKey`**  
执行 `Sync` 操作时使用的*基* 表的分区键。在表使用自定义分区键时，该字段允许执行 `Sync` 操作。此为可选字段。

**`deltaIndexName`**  
用于 `Sync` 操作的索引。在表使用自定义分区键时，需要使用该索引才能对整个增量存储表启用 `Sync` 操作。`Sync` 操作是对 GSI（在 `gsi_ds_pk` 和 `gsi_ds_sk` 上创建）执行的。该字段是可选的。

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

有关 DynamoDB 类型转换的更多信息，请参阅[类型系统（响应映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses.md)。

有关响应映射模板的更多信息，请参阅[解析器映射模板概述](resolver-mapping-template-reference-overview.md#aws-appsync-resolver-mapping-template-reference-overview)。

结果的结构如下所示：

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

字段定义如下：

** `items` **  
包含同步操作返回的项目的列表。

** `nextToken` **  
如果可能有更多结果，则`nextToken`包含可在其他请求中使用的分页令牌。 AWS AppSync 加密并混淆从 DynamoDB 返回的分页令牌。这可防止您的表数据无意中泄露给调用方。另外，无法跨不同的解析器使用这些分页标记。

** `scannedCount` **  
在应用筛选条件表达式（如果有）之前 DynamoDB 检索的项目数。

** `startedAt` **  
同步操作开始的时刻，以纪元毫秒为单位，您可以在本地存储该值并在其他请求中将其用作 `lastSync` 参数。如果请求中包含分页令牌，则该值将与请求针对第一页结果返回的值相同。

## 示例
<a name="id14"></a>

以下示例是 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
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-batch-get-item"></a>

`BatchGetItem`请求映射文档允许您告诉 D AWS AppSync ynamoDB 解析器向 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 字段
<a name="BatchGetItem-list"></a>

### BatchGetItem 字段列表
<a name="BatchGetItem-list-col"></a>

** `version` **  
模板定义版本。仅支持 `2018-05-29`。该值为必填项。

** `operation` **  
要执行的 DynamoDB 操作。要执行 `BatchGetItem` DynamoDB 操作，该字段必须设置为 `BatchGetItem`。该值为必填项。

** `tables` **  
要从中检索项目的 DynamoDB 表。该值是一个映射，其中表名称被指定为映射的键。必须提供至少一个表。该 `tables` 值为必填项。    
** `keys` **  
DynamoDB 键列表，表示要检索的项目的主键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。  
** `consistentRead` **  
执行*GetItem*操作时是否使用一致性读取。此值是可选的，默认为 *false*。  
**`projection`**  
用于指定从 DynamoDB 操作返回的属性的投影。有关投影的更多信息，请参阅[投影](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-projections)。该字段是可选的。

要记住的事项：
+ 如果尚未从表中检索某个项目，则 *null* 元素将显示在该表的数据块中。
+ 根据在请求映射模板中提供调用结果的顺序，将按表对这些结果进行排序。
+ `BatchGetItem` 中的每个 `Get` 命令都是原子性的，但可以部分处理一个批次。如果由于错误而部分处理一个批处理，则未处理的键将作为 *unprocessedKeys* 块内的调用结果的一部分返回。
+  `BatchGetItem` 限制为 100 个键。

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

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

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

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

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

要获得更完整的示例，请按照 DynamoDB 批处理教程进行操作，这里[有 AppSync 教程：Dynamo](tutorial-dynamodb-batch.md#aws-appsync-tutorial-dynamodb-batch) DB 批处理解析器。

# BatchDeleteItem
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-batch-delete-item"></a>

`BatchDeleteItem`请求映射文档允许您告诉 D AWS AppSync ynamoDB 解析器向 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 字段
<a name="BatchDeleteItem-list"></a>

### BatchDeleteItem 字段列表
<a name="BatchDeleteItem-list-col"></a>

** `version` **  
模板定义版本。仅支持 `2018-05-29`。该值为必填项。

** `operation` **  
要执行的 DynamoDB 操作。要执行 `BatchDeleteItem` DynamoDB 操作，该字段必须设置为 `BatchDeleteItem`。该值为必填项。

** `tables` **  
要从中删除项目的 DynamoDB 表。每个表是 DynamoDB 键列表，表示要删除的项目的主键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。必须提供至少一个表。`tables` 值是必需的。

要记住的事项：
+ 与 `DeleteItem` 操作相反，响应中不会返回完全删除的项目。只返回传递的键。
+ 如果尚未从表中删除某个项目，*null* 元素将显示在该表的数据块中。
+ 根据在请求映射模板中提供调用结果的顺序，将按表对这些结果进行排序。
+ `BatchDeleteItem` 中的每个 `Delete` 命令都是原子性的。但是，可以部分处理一个批处理。如果由于错误而部分处理一个批处理，则未处理的键将作为 *unprocessedKeys* 块内的调用结果的一部分返回。
+  `BatchDeleteItem` 限制为 25 个键。
+ **不**支持与冲突检测功能一起使用此操作。两者同时使用可能会导致错误。

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

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

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

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

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

要获得更完整的示例，请按照 DynamoDB 批处理教程进行操作，这里[有 AppSync 教程：Dynamo](tutorial-dynamodb-batch.md#aws-appsync-tutorial-dynamodb-batch) DB 批处理解析器。

# BatchPutItem
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-batch-put-item"></a>

`BatchPutItem`请求映射文档允许您告诉 D AWS AppSync ynamoDB 解析器向 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 字段
<a name="BatchPutItem-list"></a>

### BatchPutItem 字段列表
<a name="BatchPutItem-list-col"></a>

** `version` **  
模板定义版本。仅支持 `2018-05-29`。该值为必填项。

** `operation` **  
要执行的 DynamoDB 操作。要执行 `BatchPutItem` DynamoDB 操作，该字段必须设置为 `BatchPutItem`。该值为必填项。

** `tables` **  
要在其中放置项目的 DynamoDB 表。每个表条目表示要为该特定表插入的 DynamoDB 项目列表。必须提供至少一个表。该值为必填项。

要记住的事项：
+ 如果成功，响应中将返回完全插入的项目。
+ 如果尚未向表中插入项目，*null* 元素将显示在该表的数据块中。
+ 根据在请求映射模板中提供插入的项目的顺序，按表对这些项目进行排序。
+ `BatchPutItem` 中的每个 `Put` 命令都是原子性的，但可以部分处理一个批次。如果由于错误而部分处理一个批处理，则未处理的键将作为 *unprocessedKeys* 块内的调用结果的一部分返回。
+  `BatchPutItem` 限制为 25 个项目。
+ **不**支持与冲突检测功能一起使用此操作。两者同时使用可能会导致错误。

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

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

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

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

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

要获得更完整的示例，请按照 DynamoDB 批处理教程进行操作，这里[有 AppSync 教程：Dynamo](tutorial-dynamodb-batch.md#aws-appsync-tutorial-dynamodb-batch) DB 批处理解析器。

# TransactGetItems
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-transact-get-items"></a>

`TransactGetItems`请求映射文档允许您告诉 D AWS AppSync ynamoDB 解析器向 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 字段
<a name="TransactGetItems-list"></a>

### TransactGetItems 字段列表
<a name="TransactGetItems-list-col"></a>

** `version` **  
模板定义版本。仅支持 `2018-05-29`。该值为必填项。

** `operation` **  
要执行的 DynamoDB 操作。要执行 `TransactGetItems` DynamoDB 操作，该字段必须设置为 `TransactGetItems`。该值为必填项。

** `transactItems` **  
要包含的请求项目。该值是请求项目的数组。必须提供至少一个请求项目。该 `transactItems` 值为必填项。    
** `table` **  
要从中检索项目的 DynamoDB 表。该值是表名的字符串。该 `table` 值为必填项。  
** `key` **  
DynamoDB 键，表示要检索的项目的主键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。  
**`projection`**  
用于指定从 DynamoDB 操作返回的属性的投影。有关投影的更多信息，请参阅[投影](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-mapping-template-reference-dynamodb.html#aws-appsync-resolver-mapping-template-reference-dynamodb-projections)。该字段是可选的。

要记住的事项：
+ 如果事务成功，`items` 块中检索项目的顺序将与请求项目的顺序相同。
+ 交易是以 all-or-nothing某种方式进行的。如果任何请求项目导致错误，则整个交易都不会执行，并返回错误详细信息。
+ 无法检索的请求项目不是错误。相反，*null* 元素会出现在相应位置的 *items* 块中。
+ 如果交易的错误是 *TransactionCanceledException*，则`cancellationReasons`区块将被填充。`cancellationReasons` 块中取消原因的顺序将与请求项目的顺序相同。
+  `TransactGetItems` 限制为 100 个请求项目。

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

```
{
    "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 有教[程：Dynamo](tutorial-dynamodb-transact.md#aws-appsync-tutorial-dynamodb-transact) DB 事务解析器。

# TransactWriteItems
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-transact-write-items"></a>

`TransactWriteItems`请求映射文档允许您告诉 D AWS AppSync ynamoDB 解析器向 DynamoDB `TransactWriteItems` 请求写入多个项目，可能写入多个表。对于此请求模板，您必须指定以下各项：
+ 每个请求项目的目标表名称
+ 要执行的每个请求项目的操作。支持四种类型的操作：*PutItem*、*UpdateItem*DeleteItem**、和 *ConditionCheck* 
+ 要写入的每个请求项目的键

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 字段
<a name="TransactWriteItems-list"></a>

### TransactWriteItems 字段列表
<a name="TransactWriteItems-list-col"></a>

**字段定义如下：**    
** `version` **  
模板定义版本。仅支持 `2018-05-29`。该值为必填项。  
** `operation` **  
要执行的 DynamoDB 操作。要执行 `TransactWriteItems` DynamoDB 操作，该字段必须设置为 `TransactWriteItems`。该值为必填项。  
** `transactItems` **  
要包含的请求项目。该值是请求项目的数组。必须提供至少一个请求项目。该 `transactItems` 值为必填项。  
对于 `PutItem`，字段定义如下：    
** `table` **  
目标 DynamoDB 表。该值是表名的字符串。该 `table` 值为必填项。  
** `operation` **  
要执行的 DynamoDB 操作。要执行 `PutItem` DynamoDB 操作，该字段必须设置为 `PutItem`。该值为必填项。  
** `key` **  
DynamoDB 键，表示要放置的项目的主键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。该值为必填项。  
** `attributeValues` **  
要放入 DynamoDB 中的项目的其余属性。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。该字段是可选的。  
** `condition` **  
根据 DynamoDB 中已有的对象状态，确定请求是否应成功的条件。如果未指定条件，则 `PutItem` 请求将覆盖该项目的任何现有条目。您可以指定在状况检查失败时是否重新检索现有项目。有关事务条件的更多信息，请参阅[事务条件表达式](aws-appsync-resolver-mapping-template-reference-dynamodb-transaction-condition-expressions.md)。该值为可选项。
对于 `UpdateItem`，字段定义如下：    
** `table` **  
要更新的 DynamoDB 表。该值是表名的字符串。该 `table` 值为必填项。  
** `operation` **  
要执行的 DynamoDB 操作。要执行 `UpdateItem` DynamoDB 操作，该字段必须设置为 `UpdateItem`。该值为必填项。  
** `key` **  
DynamoDB 键，表示要更新的项目的主键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。该值为必填项。  
** `update` **  
`update` 部分用于指定一个更新表达式，以描述如何更新 DynamoDB 中的项目。有关如何编写更新表达式的更多信息，请参阅 [DynamoDB 文档 UpdateExpressions ](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)。此部分是必需的。  
** `condition` **  
根据 DynamoDB 中已有的对象状态，确定请求是否应成功的条件。如果未指定条件，则 `UpdateItem` 请求将更新现有条目，而不考虑其当前状态。您可以指定在状况检查失败时是否重新检索现有项目。有关事务条件的更多信息，请参阅[事务条件表达式](aws-appsync-resolver-mapping-template-reference-dynamodb-transaction-condition-expressions.md)。该值为可选项。
对于 `DeleteItem`，字段定义如下：    
** `table` **  
要在其中删除项目的 DynamoDB 表。该值是表名的字符串。该 `table` 值为必填项。  
** `operation` **  
要执行的 DynamoDB 操作。要执行 `DeleteItem` DynamoDB 操作，该字段必须设置为 `DeleteItem`。该值为必填项。  
** `key` **  
DynamoDB 键，表示要删除的项目的主键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。该值为必填项。  
** `condition` **  
根据 DynamoDB 中已有的对象状态，确定请求是否应成功的条件。如果未指定条件，则 `DeleteItem` 请求将删除项目，而不考虑其当前状态。您可以指定在状况检查失败时是否重新检索现有项目。有关事务条件的更多信息，请参阅[事务条件表达式](aws-appsync-resolver-mapping-template-reference-dynamodb-transaction-condition-expressions.md)。该值为可选项。
对于 `ConditionCheck`，字段定义如下：    
** `table` **  
要在其中检查条件的 DynamoDB 表。该值是表名的字符串。该 `table` 值为必填项。  
** `operation` **  
要执行的 DynamoDB 操作。要执行 `ConditionCheck` DynamoDB 操作，该字段必须设置为 `ConditionCheck`。该值为必填项。  
** `key` **  
DynamoDB 键，表示要检查条件的项目的主键。DynamoDB 项目可能具有单个哈希键，也可能具有哈希键和排序键，具体取决于表结构。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。该值为必填项。  
** `condition` **  
根据 DynamoDB 中已有的对象状态，确定请求是否应成功的条件。您可以指定在状况检查失败时是否重新检索现有项目。有关事务条件的更多信息，请参阅[事务条件表达式](aws-appsync-resolver-mapping-template-reference-dynamodb-transaction-condition-expressions.md)。该值为必填项。

要记住的事项：
+ 如果成功，响应中只返回请求项目的键。键的顺序将与请求项目的顺序相同。
+ 交易是以 all-or-nothing某种方式进行的。如果任何请求项目导致错误，则整个交易都不会执行，并返回错误详细信息。
+ 不能有两个请求项目针对同一个项目。否则它们会导致*TransactionCanceledException*错误。
+ 如果交易的错误是 *TransactionCanceledException*，则`cancellationReasons`区块将被填充。如果请求项目的条件检查失败**且** 您没有将 `returnValuesOnConditionCheckFailure` 指定为 `false`，则表中存在的项目将被检索并存储在 `cancellationReasons` 块的相应位置的 `item` 中。
+  `TransactWriteItems` 限制为 100 个请求项目。
+ **不**支持与冲突检测功能一起使用此操作。两者同时使用可能会导致错误。

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

```
{
    "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 有教[程：Dynamo](tutorial-dynamodb-transact.md#aws-appsync-tutorial-dynamodb-transact) DB 事务解析器。

# 类型系统（请求映射）
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request"></a>

使用 D AWS AppSync ynamoDB 解析器调用您的 DynamoDB 表时 AWS AppSync ，需要知道要在该调用中使用的每个值的类型。这是因为 DynamoDB 支持的类型基元比 GraphQL 或 JSON 多（例如集合和二进制数据）。 AWS AppSync 在 GraphQL 和 DynamoDB 之间进行转换时需要一些提示，否则它将不得不对表中的数据结构做出一些假设。

有关 DynamoDB 数据类型的更多信息，请参阅 DynamoDB [数据类型描述符](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.LowLevelAPI.html#Programming.LowLevelAPI.DataTypeDescriptors)和[数据类型](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes)文档。

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

```
{ "S" : "identifier" }
```

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

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

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

 **支持的类型** 

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

**字符串类型 `S` **  
单个字符串值。DynamoDB 字符串值表示为：  

```
{ "S" : "some string" }
```
示例用法如下：  

```
"key" : {
   "id" : { "S" : "some string" }
}
```

**字符串集类型 `SS` **  
一组字符串值。DynamoDB 字符串集值表示为：  

```
{ "SS" : [ "first value", "second value", ... ] }
```
示例用法如下：  

```
"attributeValues" : {
   "phoneNumbers" : { "SS" : [ "+1 555 123 4567", "+1 555 234 5678" ] }
}
```

**数字类型 `N` **  
单个数字值。DynamoDB 数字值表示为：  

```
{ "N" : 1234 }
```
示例用法如下：  

```
"expressionValues" : {
   ":expectedVersion" : { "N" : 1 }
}
```

**数字集类型 `NS` **  
一组数字值。DynamoDB 数字集值表示为：  

```
{ "NS" : [ 1, 2.3, 4 ... ] }
```
示例用法如下：  

```
"attributeValues" : {
   "sensorReadings" : { "NS" : [ 67.8, 12.2, 70 ] }
}
```

**二进制类型 `B` **  
二进制值。DynamoDB 二进制值表示为：  

```
{ "B" : "SGVsbG8sIFdvcmxkIQo=" }
```
请注意，该值实际上是一个字符串，其中字符串是二进制数据的 base64 编码表示形式。 AWS AppSync 将此字符串解码回其二进制值，然后再将其发送到 DynamoDB。 AWS AppSync 使用 RFC 2045 中定义的 base64 解码方案：任何不在 base64 字母表中的字符都将被忽略。  
示例用法如下：  

```
"attributeValues" : {
   "binaryMessage" : { "B" : "SGVsbG8sIFdvcmxkIQo=" }
}
```

**二进制集类型 `BS` **  
一组二进制值。DynamoDB 二进制集值表示为：  

```
{ "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] }
```
请注意，该值实际上是一个字符串，其中字符串是二进制数据的 base64 编码表示形式。 AWS AppSync 将此字符串解码回其二进制值，然后再将其发送到 DynamoDB。 AWS AppSync 使用 RFC 2045 中定义的 base64 解码方案：任何不在 base64 字母表中的字符都将被忽略。  
示例用法如下：  

```
"attributeValues" : {
   "binaryMessages" : { "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ] }
}
```

**布尔值类型 `BOOL` **  
布尔值。DynamoDB 布尔值表示为：  

```
{ "BOOL" : true }
```
请注意，只有 `true` 和 `false` 是有效值。  
示例用法如下：  

```
"attributeValues" : {
   "orderComplete" : { "BOOL" : false }
}
```

**列表类型 `L` **  
任何其他支持的 DynamoDB 值列表。DynamoDB 列表值表示为：  

```
{ "L" : [ ... ] }
```
请注意，该值是一个复合值，其中，列表可以包含零个或更多任何支持的 DynamoDB 值（包括其他列表）。此列表还可以包含不同类型的混合。  
示例用法如下：  

```
{ "L" : [
      { "S"  : "A string value" },
      { "N"  : 1 },
      { "SS" : [ "Another string value", "Even more string values!" ] }
   ]
}
```

**映射类型 `M` **  
表示其他支持的 DynamoDB 值的键值对的无序集合。DynamoDB 映射值表示为：  

```
{ "M" : { ... } }
```
请注意，一个映射可以包含零个或零个以上的键值对。键必须是一个字符串，值可以是任何支持的 DynamoDB 值（包括其他映射）。此映射还可以包含不同类型的混合。  
示例用法如下：  

```
{ "M" : {
      "someString" : { "S"  : "A string value" },
      "someNumber" : { "N"  : 1 },
      "stringSet"  : { "SS" : [ "Another string value", "Even more string values!" ] }
   }
}
```

**Null 类型 `NULL` **  
Null 值。DynamoDB Null 值表示为：  

```
{ "NULL" : null }
```
示例用法如下：  

```
"attributeValues" : {
   "phoneNumbers" : { "NULL" : null }
}
```

有关每个类型的更多信息，请参阅 [DynamoDB 文档](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html)。

# 类型系统（响应映射）
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-responses"></a>

收到来自 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 标量、文档和集合类型：

**字符串类型 `S` **  
单个字符串值。DynamoDB 字符串值以字符串形式返回。  
例如，如果 DynamoDB 返回以下 DynamoDB 字符串值：  

```
{ "S" : "some string" }
```
AWS AppSync 将其转换为字符串：  

```
"some string"
```

**字符串集类型 `SS` **  
一组字符串值。DynamoDB 字符串集值以字符串列表形式返回。  
例如，如果 DynamoDB 返回以下 DynamoDB 字符串集值：  

```
{ "SS" : [ "first value", "second value", ... ] }
```
AWS AppSync 将其转换为字符串列表：  

```
[ "+1 555 123 4567", "+1 555 234 5678" ]
```

**数字类型 `N` **  
单个数字值。DynamoDB 数字值以数字形式返回。  
例如，如果 DynamoDB 返回以下 DynamoDB 数字值：  

```
{ "N" : 1234 }
```
AWS AppSync 将其转换为数字：  

```
1234
```

**数字集类型 `NS` **  
一组数字值。DynamoDB 数字集值以数字列表形式返回。  
例如，如果 DynamoDB 返回以下 DynamoDB 数字集值：  

```
{ "NS" : [ 67.8, 12.2, 70 ] }
```
AWS AppSync 将其转换为数字列表：  

```
[ 67.8, 12.2, 70 ]
```

**二进制类型 `B` **  
二进制值。DynamoDB 二进制值以字符串形式返回，其中包含该值的 Base64 表示形式。  
例如，如果 DynamoDB 返回以下 DynamoDB 二进制值：  

```
{ "B" : "SGVsbG8sIFdvcmxkIQo=" }
```
AWS AppSync 将其转换为包含该值的 base64 表示形式的字符串：  

```
"SGVsbG8sIFdvcmxkIQo="
```
请注意，二进制数据按照 [RFC 4648](https://tools.ietf.org/html/rfc4648) 和 [RFC 2045](https://tools.ietf.org/html/rfc2045) 中指定的方式根据 base64 编码方案进行编码。

**二进制集类型 `BS` **  
一组二进制值。DynamoDB 二进制集值以字符串列表形式返回，其中包含这些值的 Base64 表示形式。  
例如，如果 DynamoDB 返回以下 DynamoDB 二进制集值：  

```
{ "BS" : [ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ] }
```
AWS AppSync 将其转换为包含以下值的 base64 表示形式的字符串列表：  

```
[ "SGVsbG8sIFdvcmxkIQo=", "SG93IGFyZSB5b3U/Cg==" ... ]
```
请注意，二进制数据按照 [RFC 4648](https://tools.ietf.org/html/rfc4648) 和 [RFC 2045](https://tools.ietf.org/html/rfc2045) 中指定的方式根据 base64 编码方案进行编码。

**布尔值类型 `BOOL` **  
布尔值。DynamoDB 布尔值以布尔值形式返回。  
例如，如果 DynamoDB 返回以下 DynamoDB 布尔值：  

```
{ "BOOL" : true }
```
AWS AppSync 将其转换为布尔值：  

```
true
```

**列表类型 `L` **  
任何其他支持的 DynamoDB 值列表。DynamoDB 列表值以值列表形式返回，其中还会转换每个内部值。  
例如，如果 DynamoDB 返回以下 DynamoDB 列表值：  

```
{ "L" : [
      { "S"  : "A string value" },
      { "N"  : 1 },
      { "SS" : [ "Another string value", "Even more string values!" ] }
   ]
}
```
AWS AppSync 将其转换为转换后的值列表：  

```
[ "A string value", 1, [ "Another string value", "Even more string values!" ] ]
```

**映射类型 `M` **  
任何其他受支持的 DynamoDB 值的 key/value 集合。DynamoDB 地图值以 JSON 对象的形式返回， key/value 每个值也将在其中进行转换。  
例如，如果 DynamoDB 返回以下 DynamoDB 映射值：  

```
{ "M" : {
      "someString" : { "S"  : "A string value" },
      "someNumber" : { "N"  : 1 },
      "stringSet"  : { "SS" : [ "Another string value", "Even more string values!" ] }
   }
}
```
AWS AppSync 将其转换为 JSON 对象：  

```
{
   "someString" : "A string value",
   "someNumber" : 1,
   "stringSet"  : [ "Another string value", "Even more string values!" ]
}
```

**Null 类型 `NULL` **  
Null 值。  
例如，如果 DynamoDB 返回以下 DynamoDB Null 值：  

```
{ "NULL" : null }
```
AWS AppSync 将其转换为空值：  

```
null
```

# 筛选条件
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-filter"></a>

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

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

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

字段定义如下：

** `expression` **  
查询表达式。有关如何编写筛选表达式的更多信息，请参阅 [DynamoDB 和 Dynam QueryFilter oDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.QueryFilter.html) 文档[。 ScanFilter](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.ScanFilter.html)必须指定该字段。

** `expressionNames` **  
以键值对形式替换表达式属性*名称* 占位符。键对应于 `expression` 中使用的名称占位符。该值必须是与 DynamoDB 中的项目的属性名称对应的字符串。该字段是可选的，只应填充 `expression` 中使用的表达式属性名称占位符的替换内容。

** `expressionValues` **  
以键值对形式替换表达式属性*值* 占位符。键对应于 `expression` 中使用的值占位符，而值必须为类型化值。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。必须指定此值。该字段是可选的，只应填充 `expression` 中使用的表达式属性值占位符的替换内容。

## 示例
<a name="id18"></a>

以下示例是映射模板的筛选条件部分，其中，只有在标题以 `title` 参数开头时，才会返回从 DynamoDB 中检索的条目。

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

# 条件表达式
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-condition-expressions"></a>

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

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

## 示例 1
<a name="id19"></a>

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

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

## 示例 2
<a name="id20"></a>

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

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

默认情况下，如果条件检查失败， AWS AppSync DynamoDB 解析器会返回变异错误。但是， AWS AppSync DynamoDB 解析器提供了一些其他功能来帮助开发人员处理一些常见的边缘情况：
+ 如果 D AWS AppSync ynamoDB 解析器可以确定 DynamoDB 中的当前值与所需结果相匹配，则它会将该操作视为成功了。
+ 您可以将解析器配置为调用自定义 Lambda 函数来决定 Dynam AWS AppSync oDB 解析器应如何处理故障，而不是返回错误。

在[处理条件检查失败](#aws-appsync-resolver-mapping-template-reference-dynamodb-condition-handling)一节中更详细地介绍了这些内容。

[有关 DynamoDB 条件表达式的更多信息，请参阅 DynamoDB 文档。 ConditionExpressions ](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html)

## 指定条件
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-condition-specification"></a>

`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:..."
    }
}
```

下列字段指定条件：

** `expression` **  
更新表达式本身。有关如何编写条件表达式的更多信息，请参阅 [DynamoDB 文档 ConditionExpressions ](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html)。必须指定该字段。

** `expressionNames` **  
以键值对形式替换表达式属性名称占位符。键对应于 *expression* 中使用的名称占位符，值必须是与 DynamoDB 中的项目的属性名称对应的字符串。该字段是可选的，只应填充 *expression* 中使用的表达式属性名称占位符的替换内容。

** `expressionValues` **  
以键值对形式替换表达式属性值占位符。键对应于 expression 中使用的值占位符，而值必须为类型化值。有关如何指定“类型化值”的更多信息，请参阅[类型系统（请求映射）](aws-appsync-resolver-mapping-template-reference-dynamodb-typed-values-request.md)。必须指定此值。该字段是可选的，只应填充 expression 中使用的表达式属性值占位符的替换内容。

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

** `equalsIgnore` **  
当使用`PutItem`操作时条件检查失败时，D AWS AppSync ynamoDB 解析器会将当前在 DynamoDB 中的项目与其尝试写入的项目进行比较。如果两者相同，则它会将操作视为已成功。您可以使用该`equalsIgnore`字段来指定在执行比较时 AWS AppSync 应忽略的属性列表。例如，如果唯一的区别是 `version` 属性，则会将操作视为成功。该字段是可选的。

** `consistentRead` **  
当条件检查失败时，使用强一致性读取从 DynamoDB AWS AppSync 获取项目的当前值。您可以使用此字段告诉 AWS AppSync DynamoDB 解析器改用最终一致性读取。该字段是可选的，默认值为 `true`。

** `conditionalCheckFailedHandler` **  
本节允许您指定 D AWS AppSync ynamoDB 解析器在将 DynamoDB 中的当前值与预期结果进行比较后如何处理条件检查失败。此部分是可选的。如果省略，它默认为 `Reject` 策略。    
** `strategy` **  
 AWS AppSync DynamoDB 解析器在将 DynamoDB 中的当前值与预期结果进行比较后采取的策略。该字段为必填字段，有以下可能的值：    
** `Reject` **  
变更失败，向 GraphQL 响应中添加一个错误。  
** `Custom` **  
 AWS AppSync DynamoDB 解析器调用自定义 Lambda 函数来决定如何处理条件检查失败。当 `strategy` 设置为 `Custom` 时，`lambdaArn` 字段必须包含要调用的 Lambda 函数的 ARN。  
** `lambdaArn` **  
要调用的 Lambda 函数的 ARN，用于确定 DynamoDB 解析器应如何处理 AWS AppSync 条件检查失败。当 `strategy` 设置为 `Custom` 时，必须指定该字段。有关如何使用该功能的更多信息，请参阅[处理条件检查失败](#aws-appsync-resolver-mapping-template-reference-dynamodb-condition-handling)。

## 处理条件检查失败
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-condition-handling"></a>

默认情况下，当条件检查失败时，D AWS AppSync ynamoDB 解析器会返回变异错误，并返回 DynamoDB 中对象的当前值。但是， AWS AppSync DynamoDB 解析器提供了一些其他功能来帮助开发人员处理一些常见的边缘情况：
+ 如果 D AWS AppSync ynamoDB 解析器可以确定 DynamoDB 中的当前值与所需结果相匹配，则它会将该操作视为成功了。
+ 您可以将解析器配置为调用自定义 Lambda 函数来决定 Dynam AWS AppSync oDB 解析器应如何处理故障，而不是返回错误。

此过程的流程图为：

![\[Flowchart showing process for transforming requests with mutation attempts and value checks.\]](http://docs.aws.amazon.com/zh_cn/appsync/latest/devguide/images/DynamoDB-condition-check-failure-handling.png)


### 检查所需的结果
<a name="checking-for-the-desired-result"></a>

当条件检查失败时，D AWS AppSync ynamoDB 解析器会执行 DynamoDB 请求`GetItem`，以从 DynamoDB 获取项目的当前值。默认情况下，它将使用强一致性读取，但这可以使用 `condition` 数据块中的 `consistentRead` 字段进行配置，并将当前值与预期结果进行比较：
+ 对于该`PutItem`操作，D AWS AppSync ynamoDB 解析器会将当前值与其尝试写入的值进行比较，不包括比较中列出的`equalsIgnore`任何属性。如果项目相同，则将操作视为成功并返回从 DynamoDB 中检索的项目。否则，它将遵循所配置的策略。

  例如，如果 `PutItem` 请求映射文档如下所示：

  ```
  {
     "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" ]
     }
  }
  ```

  当前位于 DynamoDB 中的项目如下所示：

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

  D AWS AppSync ynamoDB 解析器会将其尝试写入的项目与当前值进行比较，发现唯一的区别在于字段，但是由于配置为忽略`version``version`该字段，因此它会将操作视为成功并返回从 DynamoDB 检索到的项目。
+ 对于该`DeleteItem`操作， AWS AppSync DynamoDB 解析器会进行检查以验证是否已从 DynamoDB 返回了项目。如果没有返回项目，它会将该操作视为已成功。否则，它将遵循所配置的策略。
+ 对于该`UpdateItem`操作，D AWS AppSync ynamoDB 解析器没有足够的信息来确定 DynamoDB 中当前的项目是否与预期结果匹配，因此遵循了配置的策略。

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

### 遵循“reject”策略
<a name="following-the-reject-strategy"></a>

遵循该`Reject`策略时， AWS AppSync 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",
      ...
    }
  ]
}
```

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

### 遵循“custom”策略
<a name="following-the-custom-strategy"></a>

遵循`Custom`策略时， AWS AppSync DynamoDB 解析器会调用 Lambda 函数来决定下一步要做什么。Lambda 函数选择下列选项之一：
+  `reject` 变更。这会告诉 D AWS AppSync ynamoDB 解析器像配置的策略`Reject`一样行事，返回变异错误和 DynamoDB 中对象的当前值，如上一节所述。
+  `discard` 变更。这会告诉 AWS AppSync DynamoDB 解析器以静默方式忽略条件检查失败，并在 DynamoDB 中返回该值。
+  `retry` 变更。这会告诉 AWS AppSync DynamoDB 解析器使用新的请求映射文档重试变更。

 **Lambda 调用请求** 

 AWS AppSync DynamoDB 解析器调用中指定的 Lambda 函数。`lambdaArn`它将使用在数据来源上配置的相同 `service-role-arn`。调用的负载具有以下结构：

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

字段定义如下：

** `arguments` **  
来自 GraphQL 变更的参数。这与可用于 `$context.arguments` 中的请求映射文档的参数相同。

** `requestMapping` **  
用于此操作的请求映射文档。

** `currentValue` **  
DynamoDB 中的对象的当前值。

** `resolver` **  
有关 AWS AppSync 解析器的信息。

** `identity` **  
有关调用方的信息。这与可用于 `$context.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 函数可以检查调用负载并应用任何业务逻辑来决定 DynamoDB 解析器应如何处理 AWS AppSync 故障。有三种选项可用于处理条件检查失败：
+  `reject` 变更。此选项的响应负载必须具有此结构：

  ```
  {
      "action": "reject"
  }
  ```

  这告诉 D AWS AppSync ynamoDB 解析器表现得像配置的策略`Reject`一样，返回变异错误和 DynamoDB 中对象的当前值，如上一节所述。
+  `discard` 变更。此选项的响应负载必须具有此结构：

  ```
  {
      "action": "discard"
  }
  ```

  这会告诉 AWS AppSync DynamoDB 解析器以静默方式忽略条件检查失败，并在 DynamoDB 中返回该值。
+  `retry` 变更。此选项的响应负载必须具有此结构：

  ```
  {
      "action": "retry",
      "retryMapping": { ... }
  }
  ```

  这会告诉 AWS AppSync DynamoDB 解析器使用新的请求映射文档重试变更。`retryMapping` 部分的结构取决于 DynamoDB 操作，并且是该操作的完整请求映射文档的子集。

  对于 `PutItem`，`retryMapping` 部分具有以下结构。有关该`attributeValues`字段的说明，请参见[PutItem](aws-appsync-resolver-mapping-template-reference-dynamodb-putitem.md)。

  ```
  {
      "attributeValues": { ... },
      "condition": {
          "equalsIgnore" = [ ... ],
          "consistentRead" = true
      }
  }
  ```

  对于 `UpdateItem`，`retryMapping` 部分具有以下结构。有关该`update`部分的说明，请参见[UpdateItem](aws-appsync-resolver-mapping-template-reference-dynamodb-updateitem.md)。

  ```
  {
      "update" : {
          "expression" : "someExpression"
          "expressionNames" : {
              "#foo" : "foo"
          },
          "expressionValues" : {
              ":bar" : ... typed value
          }
      },
      "condition": {
          "consistentRead" = true
      }
  }
  ```

  对于 `DeleteItem`，`retryMapping` 部分具有以下结构。

  ```
  {
      "condition": {
          "consistentRead" = true
      }
  }
  ```

  无法指定要使用的不同的操作或键。 AWS AppSync DynamoDB 解析器仅允许对同一个对象重试相同的操作。另外，`condition` 部分不允许指定 `conditionalCheckFailedHandler`。如果重试失败，则 Dynamo AWS AppSync DB 解析器将遵循该策略。`Reject`

在下面的示例中，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)
};
```

# 事务条件表达式
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-transaction-condition-expressions"></a>

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

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

## 示例 1
<a name="id22"></a>

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

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

## 示例 2
<a name="id23"></a>

以下事务 `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` 中返回。

## 指定条件
<a name="id24"></a>

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

`condition` 部分具有以下结构：

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

下列字段指定条件：

** `expression` **  
更新表达式本身。有关如何编写条件表达式的更多信息，请参阅 [DynamoDB 文档 ConditionExpressions ](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html)。必须指定该字段。

** `expressionNames` **  
以键值对形式替换表达式属性名称占位符。键对应于 *expression* 中使用的名称占位符，值必须是与 DynamoDB 中的项目的属性名称对应的字符串。该字段是可选的，只应填充 *expression* 中使用的表达式属性名称占位符的替换内容。

** `expressionValues` **  
以键值对形式替换表达式属性值占位符。键对应于 expression 中使用的值占位符，而值必须为类型化值。有关如何指定“类型化值”的更多信息，请参阅“类型系统（请求映射）”。必须指定此值。该字段是可选的，只应填充 expression 中使用的表达式属性值占位符的替换内容。

** `returnValuesOnConditionCheckFailure` **  
指定在条件检查失败时是否重新检索 DynamoDB 中的项目。检索到的项目将位于 `$ctx.result.cancellationReasons[$index].item` 中，其中 `$index` 是未通过条件检查的请求项目的索引。该值默认为 true。

# 投影
<a name="aws-appsync-resolver-mapping-template-reference-dynamodb-projections"></a>

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

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

字段定义如下：

**`expression`**   
投影表达式，它是一个字符串。要检索单个属性，请指定其名称。对于多个属性，名称必须是逗号分隔值。有关编写投影表达式的更多信息，请参阅 [DynamoDB 投影表达式](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html)文档。该字段为必填。

 **`expressionNames`**   
以键值对形式替换表达式属性*名称*占位符。键对应于 `expression` 中使用的名称占位符。该值必须是与 DynamoDB 中的项目的属性名称对应的字符串。该字段是可选的，只应填充 `expression` 中使用的表达式属性名称占位符的替换内容。有关 `expressionNames` 的更多信息，请参阅 [DynamoDB 文档](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeNames.html)。

## 示例 1
<a name="id25"></a>

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

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

**提示**  
[你可以使用 \$1context.info 访问你的 GraphQL 请求选择集。 selectionSetList](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-context-reference.html#aws-appsync-resolver-context-reference-info)。可以通过该字段根据您的要求动态构建投影表达式。

**注意**  
在将投影表达式与 `Query` 和 `Scan` 运算一起使用时，`select` 的值必须为 `SPECIFIC_ATTRIBUTES`。有关更多信息，请参阅 [DynamoDB 文档](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html#DDB-Query-request-Select)。