BatchWriteItem

重要

本节介绍已经弃用的 API 版本 2011-12-05，不应用于新应用程序。

有关当前低级别 API 的文档，请参阅 Amazon DynamoDB API 参考。

描述

此操作可以在一次调用中，放入或删除多个表中的多个项目。

要上传项目，可以使用 PutItem，要删除项目，可以使用 DeleteItem。但是，如果要上传或删除大量数据（例如从 Amazon EMR (Amazon EMR) 上传大量数据，或将数据从其他数据库迁移到 DynamoDB），BatchWriteItem 是一个高效选择。

如果使用 Java 等语言，可以利用线程并行上传项目。这增加了应用程序处理线程的复杂性。其他语言不支持线程。例如，如果使用 PHP，则必须一次上传或删除一个项目。在这两种情况下，BatchWriteItem 可以并行处理指定的放入和删除操作，具有线程池方法的优势，同时不必增加应用程序的复杂性。

请注意，BatchWriteItem 操作中指定的每个放入和删除在消耗容量单位方面的消耗相同。但是，由于 BatchWriteItem 并行执行指定操作，延迟更低。对不存在的项目执行的删除操作消耗 1 个写入容量单位。有关消耗容量单位的更多信息，请参阅使用 DynamoDB 中的表和数据。

使用 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 项目大小限制。

请求

语法


// 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，提供主键名称和值。

响应

语法

响应中返回的 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.

特殊错误

没有特定于此操作的错误。

示例

下面的示例显示 HTTP POST 请求和 BatchWriteItem 操作的响应。请求指定对回复和线程表执行以下操作：

在回复表中放入一个项目并删除一个项目
将线程表中放入一个项目

有关使用 Amazon SDK 的示例，请参阅使用项目和属性。

示例请求


// 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"
            }
          }
        }
      }
    ]
  }
}

示例响应

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

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

BatchGetItem

CreateTable