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

# BatchWriteItem
<a name="API_BatchWriteItem_v20111205"></a>

**重要**  
***本節涉及不該再用於新應用程式的已棄用 API 版本 2011-12-05。***  
 **如需目前低階 API 的文件，請參閱[Amazon DynamoDB API 參考](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/)。**

## 描述
<a name="API_BatchWriteItems_Description"></a>

您可利用此操作，在單一呼叫中放入與刪除多個資料表的數個項目。

您可以使用 `PutItem` 上傳一個項目，並且使用 `DeleteItem` 刪除一個項目。不過，當您想上傳或刪除大量資料，例如從 Amazon EMR (Amazon EMR) 上傳大量資料，或將資料從另一個資料庫遷移至 DynamoDB，`BatchWriteItem` 提供了一種高效率的替代方法。

如果您使用 Java 之類的語言，則可以使用執行緒來平行上傳項目。這增加了應用程序處理執行緒的複雜性。其他語言不支持執行緒。例如，如果使用 PHP，則必須一次上傳或刪除一個項目。在這兩種情況下，`BatchWriteItem` 提供一種替代方法來平行處理指定的放入與刪除操作，讓您運用強大的執行緒集區方法，卻不會增加應用程式的複雜性。

請注意，`BatchWriteItem` 操作中指定的每一個放入和刪除會使用相同的容量單位。不過，由於 `BatchWriteItem` 平行執行指定操作，您會達到更低的延遲。刪除不存在項目上的操作會使用一個寫入容量單位。如需使用的容量單位的詳細資訊，請參閱 [在 DynamoDB 中使用資料表和資料](WorkingWithTables.md)。

使用 `BatchWriteItem` 時，請注意以下限制：
+ **單次請求中的操作上限：**最多可以指定總共 25 項放入或刪除操作，不過請求大小總計不得超過 1 MB (HTTP 承載)。
+ `BatchWriteItem` 操作僅可用於放入和刪除項目。您無法使用該操作來更新現有項目。
+ **不是非敗即成操作：**`BatchWriteItem` 當中指定的個別操作為非敗即成操作，不過 `BatchWriteItem` 整體而言是屬於最佳操作，而不是非敗即成操作。也就是說，在 `BatchWriteItem` 請求中，有些操作可能成功，有些操作可能失敗。失敗的操作會在回應中的 `UnprocessedItems` 欄位傳回。其中有些失敗可能肇因於超出為資料表所設定的佈建輸送量，或是例如網路錯誤的暫時性失敗。您可以調查並選擇性地重新傳送請求。一般而言，您會在迴圈中呼叫 `BatchWriteItem`，在每次更替中檢查未處理項目，並提交一個含有這些未處理項目的新的 `BatchWriteItem` 請求。
+ **不傳回任何項目：**`BatchWriteItem` 是設計來有效地上傳大量資料。這不會提供 `PutItem` 和 `DeleteItem` 的一些複雜性。例如，`DeleteItem` 支援要求主體文中的 `ReturnValues` 欄位請求回應中的刪除項目。`BatchWriteItem` 操作不會傳回回應中的任何項目。
+ 不同於 `PutItem` 和 `DeleteItem`，`BatchWriteItem` 不允許在操作中指定個別寫入請求的條件。
+ 屬性值不可為 Null；字串和二進位類型屬性的長度必須大於零；集合類型屬性不可為空白。具有空值的請求會遭到拒絕，並出現 `ValidationException`。

如果符合以下任一情況，DynamoDB 會拒絕整個批次寫入操作：
+ `BatchWriteItem` 請求中指定的一或多個資料表不存在。
+ 請求中的項目上指定的主索引鍵屬性不符合對應資料表的主索引鍵結構描述。
+ 嘗試在同一 `BatchWriteItem` 請求中的同一個項目上執行多項操作。例如，您不能在同一 `BatchWriteItem` 請求中放入和刪除同一個項目。
+ 請求大小總計超過 1 MB 的請求大小 (HTTP 承載) 限制。
+ 批次中任一個項目超過 64 KB 的項目大小限制。

## 請求
<a name="API_BatchWriteItems_RequestParameters"></a>

### 語法
<a name="API_BatchWriteItems_RequestParameters.syntax"></a>

```
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.BatchGetItem 
content-type: application/x-amz-json-1.0 

{
  "RequestItems" :  RequestItems
} 

RequestItems
{
     "TableName1" :  [ Request, Request, ... ],
     "TableName2" :  [ Request, Request, ... ],
     ...
}

Request ::=
  PutRequest | DeleteRequest

PutRequest ::=
{
  "PutRequest" : {
     "Item" : {
        "Attribute-Name1" : Attribute-Value,
        "Attribute-Name2" : Attribute-Value,
         ...
     }
  }
}

DeleteRequest ::=
{
   "DeleteRequest" : {
      "Key" : PrimaryKey-Value
   }
}


PrimaryKey-Value ::= HashTypePK | HashAndRangeTypePK

HashTypePK ::=
{ 
   "HashKeyElement" : Attribute-Value
}

HashAndRangeTypePK
{ 
   "HashKeyElement" : Attribute-Value,
   "RangeKeyElement" : Attribute-Value, 
}

Attribute-Value ::= String | Numeric| Binary | StringSet | NumericSet | BinarySet 

Numeric ::=
{
   "N": "Number"
}

String ::=
{
   "S": "String"
}

Binary ::=
{
    "B": "Base64 encoded binary data"
}

StringSet ::=
{
   "SS": [ "String1", "String2", ... ]
}

NumberSet ::=
{
   "NS": [ "Number1", "Number2", ... ]
}  

BinarySet ::=
{
   "BS": [ "Binary1", "Binary2", ... ]
}
```

要求主體中的 `RequestItems` JSON 物件會描述您要執行的操作。這些操作依資料表分組。您可以使用 `BatchWriteItem` 來更新或刪除多個資料表的數個項目。對於每個特定寫入請求，您必須確定請求類型 (`PutItem`、`DeleteItem`)，後面附上操作詳細資訊。
+ 對於 `PutRequest`，您要提供項目，也就是屬性及其值的清單。
+ 對於 `DeleteRequest`，您要提供主索引鍵名稱和值。

## 回應
<a name="API_BatchWriteItems_ResponseElements"></a>

### 語法
<a name="API_BatchWriteItems_ResponseElements.syntax"></a>

以下是回應中傳回的 JSON 內文語法。

```
{
  "Responses" :         ConsumedCapacityUnitsByTable
  "UnprocessedItems" :  RequestItems
} 

ConsumedCapacityUnitsByTable
{
    "TableName1" : { "ConsumedCapacityUnits", : NumericValue },
    "TableName2" : { "ConsumedCapacityUnits", : NumericValue },
     ...
}

RequestItems
This syntax is identical to the one described in the JSON syntax in the request.
```

## 特殊錯誤
<a name="API_BatchWriteItems_SpecialErrors"></a>

沒有此操作特定的錯誤。

## 範例
<a name="API_BatchWriteItems_Examples"></a>

以下範例顯示 `BatchWriteItem` 操作的 HTTP POST 請求和回應。該請求指定在 Reply (回覆) 和 Thread (主題) 資料表上執行下列操作：
+ 在 Reply (回覆) 資料表中放入一個項目並刪除一個項目
+ 將一個項目放入 Thread (主題) 資料表

如需使用 AWS 開發套件的範例，請參閱 [在 DynamoDB 使用項目和屬性](WorkingWithItems.md)。

### 請求範例
<a name="API_BatchWriteItems_Examples_Request"></a>

```
// This header is abbreviated. For a sample of a complete header, see DynamoDB 低階 API.
POST / HTTP/1.1
x-amz-target: DynamoDB_20111205.BatchGetItem 
content-type: application/x-amz-json-1.0 

{
  "RequestItems":{
    "Reply":[
      {
        "PutRequest":{
          "Item":{
            "ReplyDateTime":{
              "S":"2012-04-03T11:04:47.034Z"
            },
            "Id":{
              "S":"DynamoDB#DynamoDB Thread 5"
            }
          }
        }
      },
      {
        "DeleteRequest":{
          "Key":{
            "HashKeyElement":{
              "S":"DynamoDB#DynamoDB Thread 4"
            },
            "RangeKeyElement":{
              "S":"oops - accidental row"
            }
          }
        }
      }
    ],
    "Thread":[
      {
        "PutRequest":{
          "Item":{
            "ForumName":{
              "S":"DynamoDB"
            },
            "Subject":{
              "S":"DynamoDB Thread 5"
            }
          }
        }
      }
    ]
  }
}
```

### 回應範例
<a name="API_BatchWriteItems_Examples_Response"></a>

下列範例回應顯示 Thread (主題) 和 Reply (回覆) 資料表上的放入操作成功，以及 Reply (回覆) 資料表上的刪除操作失敗 (例如因超出資料表上的佈建輸送量而導致調節等原因)。在 JSON 回應中，請注意下列事項：
+ `Responses` 物件會顯示 `Thread` 和 `Reply` 資料表兩者都成功執行放入操作而使用一個容量單位。
+ `UnprocessedItems` 物件則會顯示 `Reply` 資料表失敗的刪除操作。然後，您可以發出新的 `BatchWriteItem` 呼叫來解決這些未處理的請求。

```
HTTP/1.1 200 OK
x-amzn-RequestId: G8M9ANLOE5QA26AEUHJKJE0ASBVV4KQNSO5AEMVJF66Q9ASUAAJG
Content-Type: application/x-amz-json-1.0
Content-Length: 536
Date: Thu, 05 Apr 2012 18:22:09 GMT

{
   "Responses":{
      "Thread":{
         "ConsumedCapacityUnits":1.0
      },
      "Reply":{
         "ConsumedCapacityUnits":1.0
      }
   },
   "UnprocessedItems":{
      "Reply":[
         {
            "DeleteRequest":{
               "Key":{
                  "HashKeyElement":{
                     "S":"DynamoDB#DynamoDB Thread 4"
                  },
                  "RangeKeyElement":{
                     "S":"oops - accidental row"
                  }
               }
            }
         }
      ]
   }
}
```