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

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

`TransactWriteItems` 請求物件可讓您指示 AWS AppSync DynamoDB 函數向 DynamoDB 提出`TransactWriteItems`請求，以寫入多個項目，可能寫入多個資料表。對於此請求物件，您必須指定下列項目：
+ 每個請求項目的目標資料表名稱
+ 每個請求項目要執行的操作。有四種支援的操作類型：*PutItem*、*UpdateItem*、*DeleteItem* 以及 *ConditionCheck* 
+ 每個要寫入之請求項目的索引鍵

套用 DynamoDB `TransactWriteItems` 限制。

`TransactWriteItems` 請求物件具有下列結構：

```
type DynamoDBTransactWriteItemsRequest = {
  operation: 'TransactWriteItems';
  transactItems: TransactItem[];
};
type TransactItem =
  | TransactWritePutItem
  | TransactWriteUpdateItem
  | TransactWriteDeleteItem
  | TransactWriteConditionCheckItem;
type TransactWritePutItem = {
  table: string;
  operation: 'PutItem';
  key: { [key: string]: any };
  attributeValues: { [key: string]: string};
  condition?: TransactConditionCheckExpression;
};
type TransactWriteUpdateItem = {
  table: string;
  operation: 'UpdateItem';
  key: { [key: string]: any };
  update: DynamoDBExpression;
  condition?: TransactConditionCheckExpression;
};
type TransactWriteDeleteItem = {
  table: string;
  operation: 'DeleteItem';
  key: { [key: string]: any };
  condition?: TransactConditionCheckExpression;
};
type TransactWriteConditionCheckItem = {
  table: string;
  operation: 'ConditionCheck';
  key: { [key: string]: any };
  condition?: TransactConditionCheckExpression;
};
type TransactConditionCheckExpression = {
  expression: string;
  expressionNames?: { [key: string]: string};
  expressionValues?: { [key: string]: any};
  returnValuesOnConditionCheckFailure: boolean;
};
```

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

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

**欄位定義如下：**    
** `operation` **  
要執行的 DynamoDB 操作。若要執行 `TransactWriteItems` DynamoDB 操作，這必須設為 `TransactWriteItems`。此值為必填。  
** `transactItems` **  
要包含的請求項目。此值是請求項目的陣列。必須提供至少一個請求項目。`transactItems` 值為必填。  
對於 `PutItem`，欄位定義如下：    
** `table` **  
目的地 DynamoDB 資料表。此值是資料表名稱的字串。`table` 值為必填。  
** `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-transaction-condition-expressions)。此值是選用的。
對於 `UpdateItem`，欄位定義如下：    
** `table` **  
要更新的 DynamoDB 資料表。此值是資料表名稱的字串。`table` 值為必填。  
** `operation` **  
要執行的 DynamoDB 操作。若要執行 `UpdateItem` DynamoDB 操作，這必須設為 `UpdateItem`。此值為必填。  
** `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)。此值為必填。  
** `update` **  
`update` 本節可讓您指定更新表達式，描述如何在 DynamoDB 中更新項目。如需有關如何撰寫更新表達式的詳細資訊，請參閱 [DynamoDB UpdateExpressions 文件](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)。此區段是必須的。  
** `condition` **  
決定要求是否成功的條件，可根據已存在於 DynamoDB 的物件狀態。如果沒有指定條件，`UpdateItem` 要求會更新現有的資料項目，無論項目的目前狀態為何。您可以指定在條件檢查失敗時是否擷取現有項目。如需交易條件的詳細資訊，請參閱[交易條件表達式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-transaction-condition-expressions)。此值是選用的。
對於 `DeleteItem`，欄位定義如下：    
** `table` **  
要在其中刪除項目的 DynamoDB 資料表。此值是資料表名稱的字串。`table` 值為必填。  
** `operation` **  
要執行的 DynamoDB 操作。若要執行 `DeleteItem` DynamoDB 操作，這必須設為 `DeleteItem`。此值為必填。  
** `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)。此值為必填。  
** `condition` **  
決定要求是否成功的條件，可根據已存在於 DynamoDB 的物件狀態。如果沒有指定條件，`DeleteItem` 要求會刪除項目，無論該項目的目前狀態為何。您可以指定在條件檢查失敗時是否擷取現有項目。如需交易條件的詳細資訊，請參閱[交易條件表達式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-transaction-condition-expressions)。此值是選用的。
對於 `ConditionCheck`，欄位定義如下：    
** `table` **  
要檢查條件的 DynamoDB 資料表。此值是資料表名稱的字串。`table` 值為必填。  
** `operation` **  
要執行的 DynamoDB 操作。若要執行 `ConditionCheck` DynamoDB 操作，這必須設為 `ConditionCheck`。此值為必填。  
** `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)。此值為必填。  
** `condition` **  
決定要求是否成功的條件，可根據已存在於 DynamoDB 的物件狀態。您可以指定在條件檢查失敗時是否擷取現有項目。如需交易條件的詳細資訊，請參閱[交易條件表達式](https://docs.aws.amazon.com/appsync/latest/devguide/js-resolver-reference-dynamodb.html#js-aws-appsync-resolver-reference-dynamodb-transaction-condition-expressions)。此值為必填。

注意事項：
+ 如果成功，只會在回應中傳回請求項目的索引鍵。索引鍵的順序將與請求項目的順序相同。
+ 以全有或全無的方式執行交易。如果任何請求項目造成錯誤，將不執行整個交易，而且將傳回錯誤詳細資料。
+ 沒有兩個請求項目可以定位到相同項目。否則，它們將造成 *TransactionCanceledException* 錯誤。
+ 如果交易錯誤是 *TransactionCanceledException*，則會填入 `cancellationReasons` 區塊。如果請求項目的條件檢查失敗，**而且**您未將 `returnValuesOnConditionCheckFailure` 指定為 `false`，將擷取資料表中存在的項目，並存放在 `cancellationReasons` 區塊之對應位置的 `item` 中。
+  `TransactWriteItems` 限制為 100 個請求項目。
+ 與衝突偵測搭配使用時，**不支援**此操作。同時使用兩者可能會導致錯誤。

對於下列範例函數請求處理常式：

```
import { util } from '@aws-appsync/utils';

export function request(ctx) {
  const { authorId, postId, title, description, oldTitle, authorName } = ctx.args;
  return {
    operation: 'TransactWriteItems',
    transactItems: [
      {
        table: 'posts',
        operation: 'PutItem',
        key: util.dynamodb.toMapValues({ postId }),
        attributeValues: util.dynamodb.toMapValues({ title, description }),
        condition: util.transform.toDynamoDBConditionExpression({
          title: { eq: oldTitle },
        }),
      },
      {
        table: 'authors',
        operation: 'UpdateItem',
        key: util.dynamodb.toMapValues({ authorId }),
        update: {
          expression: 'SET authorName = :name',
          expressionValues: util.dynamodb.toMapValues({ ':name': authorName }),
        },
      },
    ],
  };
}
```

如果交易成功，`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` 中。