Descrizione Richieste Risposte Errori speciali Esempi

BatchWriteItem

Importante

In questa sezione si fa riferimento alla versione API 2011-12-05, che è obsoleta e non deve essere utilizzata per le nuove applicazioni.

Per informazioni sull'API di basso livello corrente, consulta la Amazon DynamoDB API Reference.

Descrizione

Questa operazione consente di inserire ed eliminare più elementi da una o più tabelle con un'unica chiamata.

Per caricare un elemento è possibile utilizzare PutItem mentre per eliminare un elemento è possibile utilizzare DeleteItem. Tuttavia, se desideri caricare o eliminare grandi quantità di dati, ad esempio caricare grandi quantità di dati da Amazon EMR (Amazon EMR) o migrare dati da un altro database in DynamoDB, BatchWriteItem rappresenta un'alternativa efficiente.

Se si utilizzano linguaggi come Java, è possibile utilizzare i thread per caricare gli elementi in parallelo. Ciò aggiunge complessità all'applicazione per gestire i thread. Altri linguaggi non supportano il threading. Ad esempio, se si utilizza PHP, è necessario caricare o eliminare gli elementi uno alla volta. In entrambe le situazioni, BatchWriteItem fornisce un'alternativa in cui le operazioni put ed delete specificate vengono elaborate in parallelo, offrendo così la potenza dell'approccio del pool di thread senza dover introdurre complessità nell'applicazione.

Si noti che ogni singola operazione put ed delete specificata in un'operazione BatchWriteItem costa uguale in termini di unità di capacità consumate. Tuttavia, perché BatchWriteItem esegue le operazioni specificate in parallelo, si ottiene una latenza inferiore. Le operazioni di eliminazione su elementi inesistenti consumano 1 unità di capacità di scrittura. Per ulteriori informazioni sulle unità di capacità consumate, consulta Utilizzo di tabelle e dati in DynamoDB.

Quando si utilizza BatchWriteItem, tenere presente le limitazioni seguenti:

Operazioni massime in una singola richiesta: è possibile specificare un totale massimo di 25 operazioni put o delete; tuttavia, la dimensione totale della richiesta non può superare 1 MB (il payload HTTP).
È possibile utilizzare l'operazione BatchWriteItem solo per inserire ed eliminare elementi. Non è possibile utilizzarla per aggiornare gli elementi esistenti.
Non è un'operazione atomica: le singole operazioni specificate in BatchWriteItem sono atomiche; tuttavia BatchWriteItemnel suo complesso è un'operazione "migliore sforzo" e non un'operazione atomica. In altre parole, in una richiesta BatchWriteItem alcune operazioni potrebbero avere esito positivo e altre potrebbero non riuscire. Le operazioni non riuscite vengono restituite in un campo UnprocessedItems nella risposta. Alcuni di questi errori potrebbero essere dovuti al superamento della velocità effettiva assegnata configurata per la tabella o a un errore temporaneo, ad esempio un errore di rete. È possibile esaminare e inviare nuovamente le richieste. In genere BatchWriteItem viene richiamato in un loop e in ogni iterazione vengono controllati gli elementi non elaborati, quindi si invia una nuova richiesta BatchWriteItem con gli elementi non elaborati.
Non restituisce alcun elemento: BatchWriteItem è progettato per caricare grandi quantità di dati in modo efficiente. Non fornisce alcune delle sofisticazioni offerte da PutItem e DeleteItem. Ad esempio, DeleteItem supporta il campo ReturnValues nel corpo della richiesta per richiedere l'elemento eliminato nella risposta. L'operazione BatchWriteItem non restituisce alcun elemento nella risposta.
A differenza di PutItem e DeleteItem, BatchWriteItem non consente di specificare le condizioni sulle singole richieste di scrittura nell'operazione.
I valori degli attributi non devono essere nulli; gli attributi di tipo stringa e binario devono avere lunghezze maggiori di zero e gli attributi di tipo set non devono essere vuoti. Le richieste con valori vuoti verranno rifiutate con unaValidationException.

DynamoDB rifiuta l'intera operazione di scrittura in batch se si verifica una delle seguenti condizioni:

Se una o più tabelle specificate nella richiesta BatchWriteItem non esiste.
Se gli attributi della chiave primaria specificati su un elemento nella richiesta non corrispondono allo schema di chiave primaria della tabella corrispondente.
Se si prova a eseguire più operazioni sullo stesso elemento nella stessa richiesta BatchWriteItem. Ad esempio, non è possibile inserire ed eliminare lo stesso elemento nella stessa richiesta BatchWriteItem.
Se la dimensione totale della richiesta supera il limite di 1 MB (il payload HTTP).
Se un singolo elemento in un batch supera il limite di dimensioni degli elementi di 64 KB.

Richieste

Sintassi


// This header is abbreviated. For a sample of a complete header, see DynamoDB di basso livello 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", ... ]
}

Nel corpo della richiesta, l'oggetto JSON RequestItems descrive le operazioni che desideri eseguire. Le operazioni sono raggruppate per tabelle. È possibile utilizzare BatchWriteItem per aggiornare o eliminare più elementi in più tabelle. Per ogni richiesta di scrittura specifica, è necessario identificare il tipo di richiesta (PutItem, DeleteItem) seguito da informazioni dettagliate sull'operazione.

Per un PutRequest, si fornisce l'elemento, ovvero un elenco di attributi e i relativi valori.
Per un DeleteRequest, si forniscono il nome e il valore della chiave primaria.

Risposte

Sintassi

Di seguito è riportata la sintassi del corpo JSON restituito nella risposta.


{
  "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.

Errori speciali

Nessun errore specifico per questa operazione.

Esempi

Il seguente esempio mostra una richiesta HTTP POST e la risposta di un'operazione BatchWriteItem. La richiesta specifica le seguenti operazioni nelle tabelle Reply e Thread:

Inserimento ed eliminazione di un elemento dalla tabella Reply.
Inserisci un elemento nella tabella Thread

Per gli esempi di utilizzo dell'SDK AWS, consulta Utilizzo di elementi e attributi in DynamoDB.

Richiesta di esempio


// This header is abbreviated. For a sample of a complete header, see DynamoDB di basso livello 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"
            }
          }
        }
      }
    ]
  }
}

Risposta di esempio

La risposta di esempio seguente mostra un'operazione put nelle tabelle Thread e Reply completata e un'operazione di eliminazione nella tabella Reply non riuscita (per motivi quali la limitazione causata quando si supera la velocità effettiva assegnata nella tabella). Nella risposta JSON, tenere presente quanto segue:

L'oggetto Responses mostra che un'unità di capacità è stata utilizzata su entrambe le tabelle Thread e Reply come risultato dell'operazione put riuscita su ciascuna di queste tabelle.
L'oggetto UnprocessedItems mostra l'operazione di eliminazione non riuscita sulla tabella Reply. È quindi possibile emettere una nuova chiamata BatchWriteItem per rispondere a queste richieste non elaborate.


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

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

BatchGetItem

CreateTable