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

# 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)。