本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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

`PutItem` 請求映射文件可讓您指示 AWS AppSync DynamoDB 函數向 DynamoDB 提出`PutItem`請求，並可讓您指定下列項目：
+ DynamoDB 中項目的索引鍵
+ 項目 (由 `key` 和 `attributeValues` 組成) 的完整內容
+ 操作成功的條件

`PutItem` 請求具有下列結構：

```
type DynamoDBPutItemRequest = {
  operation: 'PutItem';
  key: { [key: string]: any };
  attributeValues: { [key: string]: any};
  condition?: ConditionCheckExpression;
  customPartitionKey?: string;
  populateIndexFields?: boolean;
  _version?: number;
};
```

欄位定義如下：

## PutItem 欄位
<a name="js-putitem-list"></a>

### PutItem 欄位清單
<a name="js-putitem-list-col"></a>

 **`operation`**   
要執行的 DynamoDB 操作。若要執行 `PutItem` DynamoDB 操作，這必須設為 `PutItem`。此值為必填。

 **`key`**   
DynamoDB 中項目的索引鍵。DynamoDB 項目可能具有單一雜湊索引鍵，或雜湊索引鍵和排序索引鍵，視資料表結構而定。如需如何指定「輸入值」的詳細資訊，請參閱[類型系統 （請求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。此值為必填。

 **`attributeValues`**   
將放入 DynamoDB 的項目其餘屬性。如需如何指定「輸入值」的詳細資訊，請參閱[類型系統 （請求映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-request)。此欄位為選用欄位。

 **`condition`**   
決定要求是否成功的條件，可根據已存在於 DynamoDB 的物件狀態。如果沒有指定條件，`PutItem` 要求會覆寫該項目的任何現有資料項目。如需條件的詳細資訊，請參閱[條件表達式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-condition-expressions)。此值是選用的。

 **`_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 的項目會自動轉換為 GraphQL 和 JSON 基本類型，並可在內容結果 () 中使用`context.result`。

如需 DynamoDB 類型轉換的詳細資訊，請參閱[類型系統 （回應映射）](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-typed-values-responses)。

如需 JavaScript 解析程式的詳細資訊，請參閱 [JavaScript 解析程式概觀](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-overview-js.html)。

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

下列範例是 GraphQL 變動 的函數請求處理常式`updateThing(foo: String!, bar: String!, name: String!, version: Int!)`。

若無指定索引鍵的項目，則會建立該項目。若已有指定索引鍵的項目，則會覆寫該項目。

```
import { util } from '@aws-appsync/utils';
export function request(ctx) {
  const { foo, bar, ...values} = ctx.args
  return {
    operation: 'PutItem',
    key: util.dynamodb.toMapValues({foo, bar}),
    attributeValues: util.dynamodb.toMapValues(values),
  };
}
```

## 範例 2
<a name="js-example-2"></a>

下列範例是 GraphQL 變動 的函數請求處理常式`updateThing(foo: String!, bar: String!, name: String!, expectedVersion: Int!)`。

此範例會驗證目前在 DynamoDB 中的項目已將 `version` 欄位設定為 `expectedVersion`。

```
import { util } from '@aws-appsync/utils';
export function request(ctx) {
  const { foo, bar, name, expectedVersion } = ctx.args;
  const values = { name, version: expectedVersion + 1 };
  let condition = util.transform.toDynamoDBConditionExpression({
    version: { eq: expectedVersion },
  });

  return {
    operation: 'PutItem',
    key: util.dynamodb.toMapValues({ foo, bar }),
    attributeValues: util.dynamodb.toMapValues(values),
    condition,
  };
}
```

如需 DynamoDB `PutItem` API 的詳細資訊，請參閱 [DynamoDB API 文件](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html)。