BatchWriteItem

Wichtig

Dieser Abschnitt bezieht sich auf die veraltete API-Version 2011-12-05, die nicht für neue Anwendungen verwendet werden sollte.

Eine Dokumentation zur aktuellen Low-Level-API finden Sie in der Amazon DynamoDB-API-Referenz.

Beschreibung

Diese Operation ermöglicht Ihnen, anhand eines einzigen Aufrufs, das Ablegen und Löschen mehrerer Elemente in mehreren Tabellen.

Für den Upload eines Elements können Sie PutItem und für das Löschen eines Elements DeleteItem verwenden. Wenn Sie allerdings große Datenmengen hochladen oder löschen möchten, wie z. B. das Hochladen großer Datenmengen von Amazon EMR (Amazon EMR) oder das Migrieren von Daten aus einer anderen Datenbank zu DynamoDB, bietet BatchWriteItem eine effiziente Alternative.

Wenn Sie Sprachen wie Java verwenden, können Sie Threads nutzen, um Elemente parallel hochzuladen. Dadurch wird Ihrer Anwendung Komplexität zum Behandeln von Threads hinzugefügt. Andere Sprachen unterstützen Threading nicht. Wenn Sie beispielsweise PHP verwenden, müssen Sie Elemente nacheinander hochladen oder löschen. In beiden Fällen bietet BatchWriteItem eine Alternative, in der die angegebenen Ablege- und Löschoperationen parallel verarbeitet werden. Somit erhalten Sie die Leistung des Thread-Pool-Ansatzes, ohne der Anwendung Komplexität hinzufügen zu müssen.

Beachten Sie, dass jeder einzelne Ablege- und Löschvorgang, der in einer BatchWriteItem-Operation angegeben wird, dasselbe in Bezug auf verbrauchte Kapazitätseinheiten kostet. Da BatchWriteItem die angegebenen Operationen jedoch parallel durchführt, erhalten Sie eine niedrigere Latenz. Delete-Operationen für nicht vorhandene Elemente verbrauchen eine Schreibkapazitätseinheit. Weitere Informationen zu verbrauchten Kapazitätseinheiten finden Sie unter Arbeiten mit Tabellen und Daten in DynamoDB.

Wenn Sie BatchWriteItem verwenden, beachten Sie die folgenden Einschränkungen:

• Maximale Operationen in einer einzigen Anforderung – Sie können insgesamt bis zu 25 Ablege- oder Löschoperationen angeben. Jedoch darf die Gesamtgröße der Anforderung 1 MB (die HTTP-Nutzlast) nicht überschreiten.

• Sie können die BatchWriteItem-Operation ausschließlich zum Ablegen und Löschen von Elemente nutzen. Sie können sie nicht verwenden, um vorhandene Elemente zu aktualisieren.

• Nicht-atomare Operation – Einzeloperationen, die in einem BatchWriteItem angegeben werden, sind atomar. Jedoch ist BatchWriteItem als Ganzes eine Operation "nach besten Kräften" und keine atomare Operation. Das bedeutet, dass einige Operationen in einer BatchWriteItem Anforderung möglicherweise erfolgreich sind und andere fehlschlagen könnten. Die fehlgeschlagenen Operationen werden in einem UnprocessedItems-Feld in der Antwort zurückgegeben. Einige dieser Ausfälle sind möglicherweise durch eine Überschreitung des für die Tabelle konfigurierten bereitgestellten Durchsatzes oder durch einen vorübergehenden Fehler, wie beispielsweise einen Netzwerkfehler, aufgetreten. Sie können die Anforderungen prüfen und optional erneut senden. In der Regel rufen Sie BatchWriteItem in einer Schleife auf. Dann prüfen Sie auf unverarbeitete Elemente in jeder Iteration und übermitteln eine neue BatchWriteItem-Anforderung mit diesen unverarbeiteten Elementen.

• Gibt keine Elemente zurück – Das BatchWriteItem ist für das effiziente Hochladen großer Datenmengen entwickelt worden. Es liefert einige Raffinessen nicht, die von PutItem und DeleteItem angeboten werden. Beispielsweise unterstützt DeleteItem das ReturnValues-Feld in Ihrem Anforderungstext, um das gelöschte Element in der Antwort anzufordern. Die BatchWriteItem-Operation gibt keine Elemente in der Antwort zurück.

• Im Gegensatz zu PutItem und DeleteItem, erlaubt BatchWriteItem Ihnen nicht, Bedingungen für einzelne Schreibanforderungen in der Operation anzugeben.

• Attributwerte dürfen nicht Null sein; Zeichenfolge- und Binärtypattribute müssen Längen haben, die größer als Null sind und festgelegte Typenattribute dürfen nicht leer sein. Anforderungen mit leeren Werten werden mit einem ValidationException abgelehnt.

DynamoDB lehnt den gesamten Batchschreibvorgang ab, wenn eine der folgenden Bedingungen erfüllt ist:

• Wenn eine oder mehrere Tabellen, die in der BatchWriteItem-Anforderung angegeben wurden, nicht vorhanden sind.

• Wenn Primärschlüsselattribute, die für ein Element in der Anforderung angegeben wurden, nicht mit dem entsprechenden Schlüsselschema der Tabelle übereinstimmen.

• Wenn Sie versuchen, mehrere Operationen für das gleiche Element in der gleichen BatchWriteItem-Anforderung durchzuführen. Sie können beispielsweise das gleiche Element in derselben BatchWriteItem-Anforderung nicht ablegen oder löschen.

• Wenn die Gesamtgröße der Anforderung die 1 MB Anforderungsgrößenbeschränkung (die HTTP-Nutzlast) überschreitet.

• Wenn ein einzelnes Element in einem Stapel die 64 KB Elementgrößenbeschränkung überschreitet.

Anforderungen

Syntax

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

Im Anforderungstext beschreibt das JSON-Objekt RequestItems die Operationen, die Sie durchführen möchten. Die Operationen werden nach Tabellen gruppiert. Sie können mehrere Elemente aus mehreren Tabellen mit BatchWriteItem aktualisieren oder löschen. Für jede bestimmte Schreibanforderung müssen Sie den Anforderungstyp (PutItem, DeleteItem), gefolgt von Detailinformationen über die Operation identifizieren.

• Für eine PutRequest stellen Sie das Element bereit, d. h. eine Liste der Attribute und deren Werte.

• Legen Sie für eine DeleteRequest den Primärschlüsselnamen und Wert fest.

Antworten

Syntax

Folgendes ist die Syntax des JSON-Anforderungstextes, die in der Antwort zurückgegeben wurde.

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

Spezielle Fehler

Keine nur für diese Operation spezifischen Fehler.

Beispiele

Das folgende Beispiel zeigt eine HTTP-POST-Anforderung und die Antwort einer BatchWriteItem-Operation. Die Anforderung gibt die folgenden Operationen in der Reply- und der Thread-Tabelle an:

• Einfügen und Löschen eines Elements aus der Reply-Tabelle

• Ablegen eines Element in die Thread-Tabelle

Beispiele für die Verwendung des AWS SDK finden Sie unter Arbeiten mit Elementen und Attributen in DynamoDB.

Beispielanforderung

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

Beispielantwort

Das folgende Antwortbeispiel zeigt, dass eine Ablegeoperation für die Thread- und Reply-Tabelle erfolgreich war und eine Delete-Operation für die Reply-Tabelle fehlgeschlagen ist (aus Gründen wie einer Drosselung, die verursacht wird, wenn Sie den bereitgestellten Durchsatz für die Tabelle überschreiten). In der JSON-Antwort ist Folgendes zu beachten:

• Das Responses-Objekt zeigt, dass eine Kapazitätseinheit sowohl für die Thread- als auch für die Reply-Tabelle als Ergebnis der erfolgreichen Ablegeoperation für jede dieser Tabellen verbraucht wurde.

• Das UnprocessedItems-Objekt zeigt die erfolglose Delete-Operation für die Reply-Tabelle. Sie können dann einen neuen BatchWriteItem-Aufruf ausführen, um diese unverarbeiteten Anforderungen anzugehen.

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