登录控制台
Amazon DynamoDB
开发人员指南 (API 版本 2012-08-10)
AWS 文档 » Amazon DynamoDB » 开发人员指南 » DynamoDB 附录 » 上一个低级 API 版本 (2011-12-05) » BatchWriteItem
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 Amazon AWS 入门。

BatchWriteItem

重要

本节引用 API 版本 2011-12-05，此版本已被弃用且不应该用于新应用程序。

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

说明

使用此操作，通过一次 调用即可在多个表中放置或删除多个项目。

要上传一个项目，可使用 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 不允许在操作中对单个写入请求指定条件。

  • 属性值不能为 null；字符串和二进制类型属性的长度必须大于零；集类型属性不能为空。将使用 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.

特殊错误

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

示例

以下示例显示了 BatchWriteItem 操作的 HTTP POST 请求和响应。该请求对 Reply 和 Thread 表指定了以下操作：

  • 在 Reply 表中放置项目和删除项目

  • 将项目放入 Thread 表

有关使用 AWS 开发工具包的示例，请参阅 在 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"
            }
          }
        }
      }
    ]
  }
}

示例响应

以下示例响应显示了对 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"
                  }
               }
            }
         }
      ]
   }
}