BatchGetItem

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

Die BatchGetItem-Operation gibt die Attribute für mehrere Elemente aus verschiedenen Tabellen unter Verwendung ihrer Primärschlüssel zurück. Die maximale Anzahl von Elementen, die für eine einzelne Operation abgerufen werden können, ist 100. Außerdem wird die Anzahl der abgerufenen Elemente durch eine Größenbeschränkung von 1 MB begrenzt. Wenn die Größenbeschränkung der Antwort überschritten wird oder ein Teilergebnis aufgrund einer Überschreitung des bereitgestellten Durchsatzes der Tabelle oder aufgrund eines internen Verarbeitungsfehlers zurückgegeben wird, gibt DynamoDB einen UnprocessedKeys-Wert zurück, sodass Sie die Operation mit den nächsten abzurufenden Element wiederholen können. DynamoDB passt die Anzahl von Elementen, die pro Seite zurückgegeben werden, automatisch an, um diese Größenbeschränkung zu erzwingen. Beispiel: Wenn Sie 100 Elemente abrufen möchten, jedes Element aber 50 KB umfasst, gibt das System nur 20 Elemente und einen entsprechenden UnprocessedKeys-Wert zurück, damit Sie die nächste Ergebnisseite abrufen können. Wenn Sie möchten, kann Ihre Anwendung eine eigene Logik für die Zusammenstellung der Ergebnisseiten in einem Satz einbeziehen.

Wenn aufgrund eines unzureichenden, bereitgestellten Durchsatzes für die von der Anforderung betroffenen Tabellen keine Elemente verarbeitet werden konnten, gibt DynamoDB einen ProvisionedThroughputExceededException-Fehler zurück.

Anmerkung

Standardmäßig führt BatchGetItem „Eventually Consistent“-Lesevorgänge für jede von der Anforderung betroffenen Tabelle aus. Sie können den Parameter ConsistentRead für einzelne Tabellen auf true einstellen, wenn stattdessen Consistent-Lesevorgänge ausgeführt werden sollen.

BatchGetItem ruft Elemente parallel ab, um Antwortlatenzen zu minimieren.

Bedenken Sie bei der Entwicklung Ihrer Anwendung, dass DynamoDB nicht sicherstellt, in welcher Reihenfolge die Attribute in der Antwort zurückgegeben werden. Schließen Sie die Primärschlüsselwerte in AttributesToGet für die Elemente in Ihrer Anforderung ein, um die Antwort nach Element zu analysieren.

Wenn die angeforderten Elemente nicht vorhanden sind, wird in der Antwort für diese Elemente nichts zurückgegeben. Anforderungen für nicht vorhandene Elemente verbrauchen je nach Typ des Lesevorgangs die Mindestlesekapazitätseinheiten. Weitere Informationen finden Sie unter DynamoDB-Elementgrößen und -formate.

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":
    {"Table1": 
        {"Keys": 
            [{"HashKeyElement": {"S":"KeyValue1"}, "RangeKeyElement":{"N":"KeyValue2"}},
            {"HashKeyElement": {"S":"KeyValue3"}, "RangeKeyElement":{"N":"KeyValue4"}},
            {"HashKeyElement": {"S":"KeyValue5"}, "RangeKeyElement":{"N":"KeyValue6"}}],
        "AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]},
    "Table2": 
        {"Keys": 
            [{"HashKeyElement": {"S":"KeyValue4"}}, 
            {"HashKeyElement": {"S":"KeyValue5"}}],
        "AttributesToGet": ["AttributeName4", "AttributeName5", "AttributeName6"]
        }
    }
}

Name	Beschreibung	Erforderlich
RequestItems	Ein Container des Tabellennamens und die entsprechenden Elemente, die nach Primärschlüssel abgerufen werden sollen. Beim Anfordern von Elementen kann jeder Tabellenname nur einmal pro Operation aufgerufen werden. Typ: Zeichenfolge Standard: keiner	Ja
Table	Der Name der Tabelle, die die abzurufenden Elemente enthält. Der Eintrag ist einfach eine Zeichenfolge, die eine vorhandene Tabelle ohne Bezeichnung angibt. Typ: Zeichenfolge Standard: keiner	Ja
Table:Keys	Die Primärschlüsselwerte, die die Elemente in der angegebenen Tabelle definieren. Weitere Informationen zu Primärschlüsseln finden Sie unter Primärschlüssel. Typ: Schlüssel	Ja
Table:AttributesToGet	Array von Attributnamen in der angegebenen Tabelle. Wenn Attributnamen nicht angegeben sind, dann werden alle Attribute zurückgegeben. Wenn einige Attribute nicht gefunden werden, sind sie nicht im Abfrageergebnis enthalten. Typ: Array	Nein
Table:ConsistentRead	Wenn auf true festgelegt, dann wird ein Consistent-Lesevorgang ausgegeben, andernfalls wird Eventually Consistent verwendet. Typ: Boolesch	Nein

Antworten

Syntax

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

{"Responses":
    {"Table1":
        {"Items":
        [{"AttributeName1": {"S":"AttributeValue"},
        "AttributeName2": {"N":"AttributeValue"},
        "AttributeName3": {"SS":["AttributeValue", "AttributeValue", "AttributeValue"]}
        },
        {"AttributeName1": {"S": "AttributeValue"},
        "AttributeName2": {"S": "AttributeValue"},
        "AttributeName3": {"NS": ["AttributeValue", "AttributeValue", "AttributeValue"]}
        }],
    "ConsumedCapacityUnits":1},
    "Table2": 
        {"Items":
        [{"AttributeName1": {"S":"AttributeValue"},
        "AttributeName2": {"N":"AttributeValue"},
        "AttributeName3": {"SS":["AttributeValue", "AttributeValue", "AttributeValue"]}
        },
        {"AttributeName1": {"S": "AttributeValue"},
        "AttributeName2": {"S": "AttributeValue"},
        "AttributeName3": {"NS": ["AttributeValue", "AttributeValue","AttributeValue"]}
        }],
    "ConsumedCapacityUnits":1}
    },
    "UnprocessedKeys":
        {"Table3": 
        {"Keys": 
            [{"HashKeyElement": {"S":"KeyValue1"}, "RangeKeyElement":{"N":"KeyValue2"}},
            {"HashKeyElement": {"S":"KeyValue3"}, "RangeKeyElement":{"N":"KeyValue4"}},
            {"HashKeyElement": {"S":"KeyValue5"}, "RangeKeyElement":{"N":"KeyValue6"}}],
        "AttributesToGet":["AttributeName1", "AttributeName2", "AttributeName3"]}
        }
}

Name	Beschreibung
Responses	Tabellennamen und die entsprechenden Elementattribute aus den Tabellen. Typ: Zuordnung
Table	Der Name der Tabelle, die die Elemente enthält. Der Eintrag ist einfach eine Zeichenfolge, die die Tabelle ohne Bezeichnung angibt. Typ: Zeichenfolge
Items	Container für die Attributnamen und Werte, die mit den Operationsparametern übereinstimmen. Typ: Zuordnung der Attributnamen und ihrer Datentypen und Werte.
ConsumedCapacityUnits	Die Anzahl der Lesekapazitätseinheiten, die für jede Tabelle verbraucht werden. Dieser Wert zeigt die Anzahl, die für Ihren bereitgestellten Durchsatz gültig ist. Anforderungen für nicht vorhandene Elemente verbrauchen je nach Typ des Lesevorgangs die Mindestlesekapazitätseinheiten. Weitere Informationen finden Sie unter Bereitgestellter Kapazitätsmodus von DynamoDB. Typ: Zahl
UnprocessedKeys	Enthält ein Array von Tabellen mit den entsprechenden Schlüsseln, die mit der aktuellen Antwort nicht verarbeitet wurden, da das Limit der Antwortgröße möglicherweise erreicht wurde. Der UnprocessedKeys-Wert hat das gleiche Format wie ein RequestItems-Parameter (sodass der Wert einer folgenden BatchGetItem-Operation direkt bereitgestellt werden kann). Weitere Informationen finden Sie unter dem obigen RequestItems-Parameter. Typ: Array
UnprocessedKeys: Table: Keys	Die Attributwerte des Primärschlüssels, die die Elemente und die den Elementen zugeordneten Attributen definieren. Weitere Informationen zu Primärschlüsseln finden Sie unter Primärschlüssel. Typ: Array von Attribut-Namen-Wert-Paare.
UnprocessedKeys: Table: AttributesToGet	Attributnamen in der angegebenen Tabelle. Wenn Attributnamen nicht angegeben sind, dann werden alle Attribute zurückgegeben. Wenn einige Attribute nicht gefunden werden, sind sie nicht im Abfrageergebnis enthalten. Typ: Array von Attributnamen.
UnprocessedKeys: Table: ConsistentRead	Wenn dieser Wert auf true festgelegt ist, wird ein Consistent-Lesevorgang für die angegebene Tabelle verwendet, andernfalls ein Eventually Consistent-Lesevorgang. Typ: boolescher Wert.

Spezielle Fehler

Fehler	Beschreibung
ProvisionedThroughputExceededException	Der maximal zulässige bereitgestellte Durchsatz wurde überschritten.

Beispiele

Die folgenden Beispiele zeigen eine HTTP-POST-Anforderung und -Antwort unter Verwendung der BatchGetItem Operation. Beispiele für die Verwendung des AWS SDK finden Sie unterArbeiten mit Elementen und Attributen in DynamoDB.

Beispielanforderung

Mit dem folgenden Beispiel werden Attribute aus zwei verschiedenen Tabellen angefordert.

// 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 
content-length: 409

{"RequestItems":
    {"comp1":
        {"Keys":
            [{"HashKeyElement":{"S":"Casey"},"RangeKeyElement":{"N":"1319509152"}},
            {"HashKeyElement":{"S":"Dave"},"RangeKeyElement":{"N":"1319509155"}},
            {"HashKeyElement":{"S":"Riley"},"RangeKeyElement":{"N":"1319509158"}}],
        "AttributesToGet":["user","status"]},
    "comp2":
        {"Keys":
            [{"HashKeyElement":{"S":"Julie"}},{"HashKeyElement":{"S":"Mingus"}}],
        "AttributesToGet":["user","friends"]}
    }
}

Beispielantwort

Das folgende Beispiel zeigt die Antwort.

HTTP/1.1 200 OK
x-amzn-RequestId: GTPQVRM4VJS792J1UFJTKUBVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0 
content-length: 373
Date: Fri, 02 Sep 2011 23:07:39 GMT

{"Responses":
    {"comp1":
        {"Items":
            [{"status":{"S":"online"},"user":{"S":"Casey"}},
            {"status":{"S":"working"},"user":{"S":"Riley"}},
            {"status":{"S":"running"},"user":{"S":"Dave"}}],
        "ConsumedCapacityUnits":1.5},
    "comp2":
        {"Items":
            [{"friends":{"SS":["Elisabeth", "Peter"]},"user":{"S":"Mingus"}},
            {"friends":{"SS":["Dave", "Peter"]},"user":{"S":"Julie"}}],
        "ConsumedCapacityUnits":1}
    },
    "UnprocessedKeys":{}
}