UpdateItem - Amazon-DynamoDB
BeschreibungAnforderungenAntwortenSpezielle FehlerBeispieleZugehörige Aktionen

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

UpdateItem

Wichtig

This section refers to API version 2011-12-05, which is deprecated and should not be used for new applications.

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

Beschreibung

Bearbeitet Attribute eines existierenden Elements. Sie können eine bedingte Aktualisierung durchführen (fügen Sie ein neues Attributnamen-Wert-Paar ein, wenn es noch nicht vorhanden ist, oder ersetzen Sie ein vorhandenes Namen-Wert-Paar, wenn es über bestimmte zu erwartende Attributwerte verfügt).

Anmerkung

Sie können die Primärschlüsselattribute nicht mit aktualisieren UpdateItem. Löschen Sie stattdessen das Element und verwenden Sie PutItem es, um ein neues Element mit neuen Attributen zu erstellen.

Der UpdateItem Vorgang umfasst einen Action Parameter, der definiert, wie das Update durchgeführt werden soll. Sie können Attributwerte hinzufügen, löschen oder setzen.

Attributwerte dürfen nicht Null sein, Zeichenketten- und Binärtypattribute müssen Längen haben, die größer als Null sind, und festgelegte Typattribute dürfen nicht leer sein. Anfragen mit leeren Werten werden mit einer ValidationException abgelehnt.

Wenn ein vorhandenes Element über den angegebenen Primärschlüssel verfügt:

  • PUT – Fügt das angegebene Attribut hinzu. Wenn das Attribut vorhanden ist, wird es durch den neuen Wert ersetzt.

  • DELETE – Ist kein Wert angegeben, wird dadurch das Attribut und sein Wert entfernt. Wenn eine Menge von Werten angegeben wird, werden die Werte in dem angegebenen Satz aus dem alten Satz entfernt. Wenn also der Attributwert [a,b,c] und die Löschaktion [a,c] enthält, dann ist der tatsächliche Attributwert [b]. Der Typ des angegebenen Werts muss dem vorhandenen Werttyp entsprechen. Einen leeren Satz anzugeben ist nicht gültig.

  • ADD – Verwendung der Add-Aktion nur für Zahlen oder wenn das Zielattribut ein Satz ist (einschließlich Zeichenkettensätze). ADD funktioniert nicht, falls das Zielattribut ein einzelner Zeichenkettenwert oder ein skalarer Binärwert ist. Der angegebene Wert wird einem numerischen Wert hinzugefügt (Erhöhen oder Verringern des vorhandenen numerischen Werts) oder als zusätzlichen Wert in einem Zeichenkettensatz hinzugefügt. Wenn ein Menge von Werten angegeben wird, werden die Werte dem vorhandenen Satz hinzugefügt. Zum Beispiel, wenn der ursprüngliche Satz [1,2] ist und der bereitgestellte Wert [3] ist, dann ist der Satz nach dem Add-Vorgang [1,2,3] und nicht [4,5]. Ein Fehler tritt auf, wenn eine Add-Aktion für ein festgelegtes Attribut angegeben wird und der angegebene Attributtyp nicht mit dem vorhandenen festgelegten Typ übereinstimmt.

    Wenn Sie ADD für ein Attribut verwenden, das nicht existiert, wird das Attribut und seine Werte dem Element hinzugefügt.

Wenn kein Element mit dem angegebenen Primärschlüssel übereinstimmt:

  • PUT – Erstellt ein neues Element mit dem angegebenen Primärschlüssel. Fügt dann das angegebene Attribut hinzu.

  • DELETE – Nichts passiert.

  • ADD – Erstellt ein Element mit einem bereitgestellten Primärschlüssel und einer Zahl (oder eine Menge von Zahlen) für den Attributwert. Nicht gültig für einen Zeichenkette- oder Binärtyp.

Anmerkung

Wenn Sie ADD einsetzen, um einen Zahlenwert für ein Element, das vor der Aktualisierung nicht vorhanden ist, zu erhöhen oder zu verringern, verwendet DynamoDB 0 als Anfangswert. Wenn Sie außerdem ein Element aktualisieren, indem Sie ADD verwenden, um einen Zahlenwert für ein Attribut zu erhöhen oder zu verringern, das vor der Aktualisierung nicht vorhanden ist (das Element ist jedoch vorhanden), verwendet DynamoDB die 0 als Anfangswert. Beispiel: Sie verwenden ADD, um +3 einem Attribut hinzuzufügen, das vor der Aktualisierung nicht vorhanden war. DynamoDB verwendet 0 für den ersten Wert und der Wert nach der Aktualisierung ist 3.

Weitere Informationen zur Verwendung dieser Operation finden Sie unter Arbeiten mit Elementen und Attributen in DynamoDB.

Anforderungen

Syntax

// This header is abbreviated.
// For a sample of a complete header, see DynamoDB Low-Level-API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.UpdateItem
content-type: application/x-amz-json-1.0

{"TableName":"Table1",
    "Key":
        {"HashKeyElement":{"S":"AttributeValue1"},
        "RangeKeyElement":{"N":"AttributeValue2"}},
    "AttributeUpdates":{"AttributeName3":{"Value":{"S":"AttributeValue3_New"},"Action":"PUT"}},
    "Expected":{"AttributeName3":{"Value":{"S":"AttributeValue3_Current"}}},
    "ReturnValues":"ReturnValuesConstant"
}
Name Beschreibung Erforderlich
TableName

Der Name der Tabelle, die das zu aktualisierende Element enthält.

Typ: Zeichenfolge

 Ja
Key

Der Primärschlüssel, der das Element definiert. Weitere Informationen zu Primärschlüsseln finden Sie unter Primärschlüssel.

Typ: Zuordnung von HashKeyElement zu seinem Wert und von RangeKeyElement zu seinem Wert.

 Ja
AttributeUpdates

Zuordnung des Attributnamens zu dem neuen Wert und der neuen Aktion für die Aktualisierung. Die Attributnamen legen die zu ändernden Attribute fest und können keine Primärschlüsselattribute enthalten.

Typ: Zuordnung eines Attributnamens, eines Werts und einer Aktion für die Aktualisierung des Attributs.
AttributeUpdates:Action

Gibt an, wie die Aktualisierung durchzuführen ist. Mögliche Werte: PUT (Standard) ADD oder DELETE. Die Semantik wird in der UpdateItem Beschreibung erklärt.

Typ: Zeichenfolge

Standard: PUT

 Nein
Expected

Gibt ein Attribut für eine bedingte Aktualisierung an. Der Parameter Expected erlaubt es Ihnen, einen Attributnamen anzugeben und festzulegen, ob DynamoDB überprüfen soll, ob der Attributwert bereits vorhanden ist bzw. ob der Attributwert vorhanden ist und über einen bestimmten Wert verfügt, bevor er geändert wird.

Typ: Zuordnung von Attributnamen.

 Nein
Expected:AttributeName Der Name des Attributs für die bedingte Put-Operation.

Typ: Zeichenfolge

 Nein
Expected:AttributeName: ExpectedAttributeValue Verwenden Sie diesen Parameter, um anzugeben, ob ein Wert für das Attributname-Wert-Paar bereits vorhanden ist oder nicht.

Die folgende JSON-Notation aktualisiert das Element, wenn das Attribut "Farbe" für dieses Element noch nicht vorhanden ist:

"Expected" :
	{"Color":{"Exists":false}}

Die folgende JSON-Notation prüft, ob das Attribut mit dem Namen "Farbe" über einen vorhandenen Wert für "Gelb" verfügt, bevor sie das Element aktualisiert: 

"Expected" : 
	{"Color":{"Exists":true},{"Value":{"S":"Yellow"}}}

Wenn Sie den Parameter Expected verwenden und einen Value angeben, geht DynamoDB standardmäßig davon aus, dass das Attribut vorhanden ist und einen zu ersetzenden aktuellen Wert hat. Sie müssen {"Exists":true} demnach nicht angeben, weil er enthalten ist. Sie können die Anforderung verkürzen, um:

"Expected" : 
	{"Color":{"Value":{"S":"Yellow"}}}
Anmerkung

Wenn Sie {"Exists":true} ohne einen zu prüfenden Attributwert angeben, gibt DynamoDB einen Fehler zurück.

 Nein
ReturnValues

Verwenden Sie diesen Parameter, wenn Sie die Attribut-Namen-Wert-Paare erhalten möchten, bevor sie mit der UpdateItem-Anforderung aktualisiert wurden. Mögliche Parameterwerte sind NONE (Standard) oder ALL_OLD, UPDATED_OLD, ALL_NEW oder UPDATED_NEW. Wenn ALL_OLD angegeben ist und ein Attribut-Namen-Wert-Paar durch UpdateItem überschrieben wurde, wird der Inhalt des alten Elements zurückgegeben. Wenn dieser Parameter nicht angegeben wird oder NONE ist, wird nichts zurückgegeben. Wenn ALL_NEW angegeben wird, werden alle Attribute der neuen Version des Elements zurückgegeben. Wenn UPDATED_NEW angegeben wird, werden ausschließlich die neuen Versionen der aktualisierten Attribute zurückgegeben.

Typ: Zeichenfolge

 Nein

Antworten

Syntax

In dem folgenden Syntax-Beispiel wird davon ausgegangen, dass die Anforderung für den Parameter ReturnValues ALL_OLD angegeben hat; andernfalls beinhaltet die Antwort nur das ConsumedCapacityUnits-Element.

HTTP/1.1 200 
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375 
content-type: application/x-amz-json-1.0
content-length: 140

{"Attributes":{
	"AttributeName1":{"S":"AttributeValue1"},
	"AttributeName2":{"S":"AttributeValue2"},
	"AttributeName3":{"S":"AttributeValue3"},
	"AttributeName5":{"B":"dmFsdWU="}
	},
"ConsumedCapacityUnits":1
}
Name Beschreibung
Attributes

Eine Zuordnung von Attribut-Namen-Wert-Paaren, aber nur, wenn der Parameter ReturnValues in der Anforderung anders angegeben wird als NONE.

Typ: Zuordnung von Attribut-Namen-Wert-Paare.
ConsumedCapacityUnits

Die Anzahl der Schreibkapazitätseinheiten, die von dem Vorgang verbraucht werden. Dieser Wert zeigt die Anzahl, die für Ihren bereitgestellten Durchsatz gültig ist. Weitere Informationen finden Sie unter Bereitgestellter Kapazitätsmodus von DynamoDB.

Typ: Zahl

Spezielle Fehler

Fehler Beschreibung
ConditionalCheckFailedException Bedingte Prüfung fehlgeschlagen. Der Attributwert ("+ name +") ist ("+ value +"), aber ("+ expValue +") wurde erwartet
ResourceNotFoundExceptions Das angegebene Element oder Attribut wurde nicht gefunden.

Beispiele

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

Beispielanforderung

// This header is abbreviated. For a sample of a complete header, see DynamoDB Low-Level-API.
POST / HTTP/1.1 
x-amz-target: DynamoDB_20111205.UpdateItem
content-type: application/x-amz-json-1.0 

{"TableName":"comp5",
    "Key":
        {"HashKeyElement":{"S":"Julie"},"RangeKeyElement":{"N":"1307654350"}},
    "AttributeUpdates":
        {"status":{"Value":{"S":"online"},
        "Action":"PUT"}},
    "Expected":{"status":{"Value":{"S":"offline"}}},
    "ReturnValues":"ALL_NEW"
}

Beispielantwort

HTTP/1.1 200 OK
x-amzn-RequestId: 5IMHO7F01Q9P7Q6QMKMMI3R3QRVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 121
Date: Fri, 26 Aug 2011 21:05:00 GMT

{"Attributes":
    {"friends":{"SS":["Lynda, Aaron"]},
    "status":{"S":"online"},
    "time":{"N":"1307654350"},
    "user":{"S":"Julie"}},
"ConsumedCapacityUnits":1
}