# BatchWriteItem
**Importante**
***Esta seção refere-se à versão de API 2011-12-05, que está obsoleta e não deve ser usada para novos aplicativos.***
**Para obter a documentação da API de baixo nível atual, consulte a [Referência da API do Amazon DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/).**
## Descrição
Essa operação permite que você insira ou exclua vários itens de várias tabelas em uma única chamada.
Para fazer upload de um item, você pode usar `PutItem` e, para excluir um item, você pode usar `DeleteItem`. No entanto, quando você deseja enviar ou excluir grandes quantidades de dados, por exemplo, carregar grandes quantidades de dados do Amazon EMR (Amazon EMR) ou migrar dados de outro banco de dados para o DynamoDB, `BatchWriteItem` oferece uma alternativa eficiente.
Se você usa linguagens como o Java, pode usar threads para carregar itens em paralelo. Isso adiciona complexidade à sua aplicação para manipular os threads. Outras linguagens não oferecem suporte para threads. Por exemplo, se você estiver usando o PHP, deverá carregar ou excluir itens um de cada vez. Em ambas as situações, `BatchWriteItem` fornece uma alternativa na qual as operações de inserção e exclusão especificadas são processadas em paralelo, proporcionando a você o poder da abordagem de pools de threads sem a necessidade de introduzir complexidade no seu aplicativo.
Observe que cada operação individual de inserção e exclusão especificada em uma operação `BatchWriteItem` tem o mesmo custo em termos de unidades de capacidade consumidas. No entanto, como `BatchWriteItem` realiza as operações especificadas em paralelo, a latência é menor. Operações de exclusão em itens inexistentes consomem 1 unidade de capacidade de gravação. Para obter mais informações sobre unidades de capacidade consumidas, consulte [Trabalhar com tabelas e dados no DynamoDB](WorkingWithTables.md).
Ao usar `BatchWriteItem`, observe as seguintes limitações:
+ **Operações máximas em uma única solicitação**: é possível especificar um total de até 25 operações de inserção ou exclusão. No entanto, o tamanho total da solicitação não pode exceder 1 MB (a carga útil HTTP).
+ A operação `BatchWriteItem` só pode ser usada para inserir e excluir itens. Ela não pode ser usada para atualizar itens existentes.
+ **Não é uma operação atômica**: operações individuais especificadas em uma `BatchWriteItem` são atômicas. No entanto, `BatchWriteItem` como um todo é uma operação de "melhor esforço", e não uma operação atômica. Ou seja, em uma solicitação `BatchWriteItem`, algumas operações podem ser bem-sucedidas, enquanto outras podem falhar. As operações com falha são retornadas em um campo `UnprocessedItems` na resposta. Algumas dessas falhas podem ocorrer porque você excedeu o throughput provisionado configurado para a tabela ou devido a uma falha transitória, como um erro de rede. Você pode investigar e, opcionalmente, reenviar as solicitações. Em geral, você chama `BatchWriteItem` em um loop e em cada verificação de iteração em busca de itens não processados e envia uma nova solicitação `BatchWriteItem` com esses itens não processados.
+ **Não retorna itens**: `BatchWriteItem` foi projetada para carregar grandes quantidades de dados de forma eficiente. Ela não oferece algumas das sofisticações oferecidas por `PutItem` e `DeleteItem`. Por exemplo, `DeleteItem` oferece suporte ao campo `ReturnValues` no corpo da solicitação para solicitar o item excluído na resposta. A operação `BatchWriteItem` não retorna itens na resposta.
+ Ao contrário de `PutItem` e `DeleteItem`, `BatchWriteItem` não permite que você especifique condições em solicitações de gravação individuais na operação.
+ Valores de atributos não devem ser nulos, atributos do tipo string e binários devem ter comprimentos maiores que zero, e atributos de tipo definido não podem permanecer vazios. Solicitações que têm valores vazios serão rejeitadas com uma `ValidationException`.
O DynamoDB rejeitará a operação de gravação em lote inteira em qualquer uma das seguintes situações:
+ Se uma ou mais tabelas especificadas na solicitação `BatchWriteItem` não existir.
+ Se atributos de chaves primárias especificados em um item na solicitação não corresponderem ao esquema de chave primária da tabela correspondente.
+ Se você tentar realizar várias operações no mesmo item na mesma solicitação `BatchWriteItem`. Por exemplo, não é possível inserir e excluir o mesmo item na mesma solicitação `BatchWriteItem`.
+ Se o tamanho total da solicitação exceder o limite de 1 MB (a carga útil HTTP).
+ Se qualquer item individual em um lote exceder o limite de tamanho de item de 64 KB.
## Solicitações
### Sintaxe
```
// This header is abbreviated. For a sample of a complete header, see API de baixo nível do DynamoDB.
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", ... ]
}
```
No corpo da solicitação, o objeto JSON `RequestItems` descreve as operações que você deseja realizar. As operações são agrupadas por tabelas. É possível usar `BatchWriteItem` para atualizar ou excluir vários itens em várias tabelas. Para cada solicitação de gravação específica, você deve identificar o tipo de solicitação (`PutItem`, `DeleteItem`) seguido de informações detalhadas sobre a operação.
+ Para uma `PutRequest`, você fornece o item, ou seja, uma lista de atributos e seus valores.
+ Para uma `DeleteRequest`, você fornece o nome e o valor da chave primária.
## Respostas
### Sintaxe
Veja a seguir a sintaxe do corpo JSON retornado na resposta.
```
{
"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.
```
## Erros especiais
Não há erros específicos para esta operação.
## Exemplos
O exemplo a seguir mostra uma solicitação HTTP POST e a resposta de uma operação `BatchWriteItem`. A solicitação especifica as seguintes operações nas tabelas Reply e Thread:
+ Inserir um item e excluí-lo da tabela Reply
+ Inserir um item na tabela Thread
Para obter exemplos sobre o uso do AWS SDK, consulte [Trabalhar com itens e atributos no DynamoDB](WorkingWithItems.md).
### Exemplo de solicitação
```
// This header is abbreviated. For a sample of a complete header, see API de baixo nível do DynamoDB.
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"
}
}
}
}
]
}
}
```
### Exemplo de resposta
A seguinte resposta de exemplo mostra uma operação de inserção bem-sucedida nas tabelas Thread e Reply e uma operação de exclusão com falha na tabela Reply (por motivos como a limitação causada quando você excede o throughput provisionado na tabela). Observe o seguinte na resposta JSON:
+ O objeto `Responses` mostra que uma unidade de capacidade foi consumida em ambas as tabelas `Thread` e `Reply` como resultado da operação bem-sucedida em cada uma dessas tabelas.
+ O objeto `UnprocessedItems` mostra a operação de exclusão que falhou na tabela `Reply`. Em seguida, você pode emitir uma nova chamada `BatchWriteItem` para solucionar essas solicitações não processadas.
```
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"
}
}
}
}
]
}
}
```