BatchWriteItem - Amazon DynamoDB
描述请求响应特殊错误示例

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 操作的响应。请求指定对回复和线程表执行以下操作：

  • 在回复表中放入一个项目并删除一个项目

  • 将线程表中放入一个项目

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

示例请求

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