# 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` 并行执行指定操作，延迟更低。对不存在的项目执行的删除操作消耗 1 个写入容量单位。有关消耗容量单位的更多信息，请参阅 [使用 DynamoDB 中的表和数据](WorkingWithTables.md)。

使用 `BatchWriteItem` 时请注意以下限制：
+ **单个请求中的最大操作数 —** 您最多可以指定 25 个放入或删除操作；但是，请求总大小不能超过 1 MB（HTTP 负载）。
+ 您只能使用 `BatchWriteItem` 操作放入和删除项目，不能用来更新现有项目。
+ **不是原子操作 - **`BatchWriteItem` 中指定的每个操作是原子操作；但是 `BatchWriteItem` 整体是“尽最大努力”的操作，而不是原子操作。也就是说，在 `BatchWriteItem` 请求中，有些操作可能成功，有些操作可能失败。失败的操作将在响应的 `UnprocessedItems` 字段返回。其中一些失败可能是因为超过为表配置的预置吞吐量，或者出现暂时故障，如网络错误。您可以分析，选择重新发送请求。通常，在循环中调用 `BatchWriteItem`，在每个迭代中检查未处理的项目，对没有处理的项目提交新的 `BatchWriteItem` 请求。
+ **不返回任何项目 —** `BatchWriteItem` 设计用于高效上传大量数据，不具备 `PutItem` 和 `DeleteItem` 的一些精密性。例如，`DeleteItem` 支持在请求体中用 `ReturnValues` 字段请求响应中的已删除项目。`BatchWriteItem` 操作在响应中不返回任何项目。
+ 不像 `PutItem` 和 `DeleteItem`，`BatchWriteItem` 不允许为操作中的单个写入请求指定条件。
+ 属性值不得为空；字符串和二进制类型属性的长度必须大于零；设置类型属性不得为空。具有空值的请求将被拒绝，并显示 `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>

下面的示例显示 HTTP POST 请求和 `BatchWriteItem` 操作的响应。请求指定对回复和线程表执行以下操作：
+ 在回复表中放入一个项目并删除一个项目
+ 将线程表中放入一个项目

有关使用 AWS SDK 的示例，请参阅 [使用 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>

下面的示例响应显示对线程和回复表执行的放入操作成功，对回复表执行的删除操作失败（原因是超出表的预置吞吐量，导致节流）。注意 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"
                  }
               }
            }
         }
      ]
   }
}
```