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.

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.

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.

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