Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
Important
This section refers to API version 2011-12-05,
which is deprecated and should not be used for new
applications.
Pour obtenir de la documentation sur le bas niveau actuelAPI, consultez le manuel Amazon DynamoDB Reference API.
Description
L'opération BatchGetItem
renvoie les attributs de plusieurs éléments de tables multiples en utilisant leurs clés primaires. Le nombre maximum d'éléments pouvant être extraits pour une seule opération est de 100. En outre, le nombre d'éléments récupérés est limité par une limite de taille de 1 Mo. Si la limite de taille de réponse est dépassée ou si un résultat partiel est renvoyé parce que le débit approvisionné de la table est dépassé ou en raison d'un échec de traitement interne, DynamoDB renvoie une valeur UnprocessedKeys
afin de vous permettre de réessayer l'opération en commençant par l'élément suivant à obtenir. DynamoDB ajuste automatiquement le nombre d'éléments renvoyés par page pour appliquer cette limite. Par exemple, même si vous demandez à récupérer 100 éléments ayant chacun une taille de 50 Ko, le système renvoie 20 éléments et une valeur UnprocessedKeys
appropriée pour vous permettre d'obtenir la page de résultats suivante. Si vous le souhaitez, votre application peut inclure sa propre logique pour assembler les pages de résultats en un seul ensemble.
Si aucun élément n'a pu être traité en raison d'un débit approvisionné insuffisant sur chacune des tables impliquées dans la demande, DynamoDB renvoie une erreur ProvisionedThroughputExceededException
.
Note
Par défaut, la commande BatchGetItem
effectue des lectures éventuellement cohérentes sur chaque table dans la demande. Vous pouvez définir le paramètre ConsistentRead
sur true
pour chaque table si vous voulez plutôt des lectures cohérentes.
L'opération BatchGetItem
récupère des éléments en parallèle afin de réduire les latences de réponse.
Lors de la conception de votre application, gardez à l'esprit que DynamoDB ne garantit pas l'ordre des attributs dans la réponse renvoyée. Incluez les valeurs de clé primaire dans le paramètre AttributesToGet
pour les éléments dans votre demande afin de vous aider à analyser la réponse par élément.
Si les éléments demandés n'existent pas, rien n'est renvoyé dans la réponse pour ces éléments. Les demandes d'éléments inexistants consomment les unités de capacité de lecture minimum en fonction du type de lecture. Pour de plus amples informations, veuillez consulter Tailles et formats des éléments DynamoDB.
Requêtes
Syntaxe
// This header is abbreviated. For a sample of a complete header, see DynamoDB de bas niveau 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 (Nom) | Description | Obligatoire |
---|---|---|
RequestItems
|
Conteneur du nom de table et éléments correspondants à obtenir par la clé primaire. Lors de la demande d'éléments, chaque nom de table ne peut être appelé qu'une seule fois par opération. Type : String Par défaut : aucun |
Oui |
Table |
Nom de la table contenant les éléments à obtenir. L'entrée est simplement une chaîne spécifiant une table existante sans libellé. Type : String Par défaut : aucun |
Oui |
Table :Keys
|
Valeurs de clé primaire définissant les éléments dans la table spécifiée. Pour plus d'informations sur les clés primaires, consultez Clé primaire. Type : clés |
Oui |
Table :AttributesToGet
|
Tableau de noms d'attribut dans la table spécifiée. Si des noms d'attribut ne sont pas spécifiés, tous les attributs sont renvoyés. Si certains attributs ne sont pas trouvés, ils n'apparaissent pas dans le résultat. Type : Array |
Non |
Table :ConsistentRead
|
Si la valeur est définie sur Type : booléen |
Non |
Réponses
Syntaxe
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 (Nom) | Description |
---|---|
Responses
|
Noms de table et attributs d'élément respectifs des tables. Type : carte |
Table |
Nom de la table contenant les éléments. L'entrée est simplement une chaîne spécifiant la table sans libellé. Type : String |
Items
|
Conteneur pour les noms d'attribut et les valeurs correspondant aux paramètres d'opération. Type : mappage de noms d'attribut à leurs types de données et valeurs. |
ConsumedCapacityUnits |
Nombre d'unités de capacité de lecture consommées pour chaque table. Cette valeur indique le nombre appliqué à votre débit approvisionné. Les demandes d'éléments inexistants consomment les unités de capacité de lecture minimum, selon le type de lecture. Pour plus d'informations, voir Mode de capacité provisionnée DynamoDB. Type : nombre |
UnprocessedKeys |
Contient un tableau de tables et leurs clés respectives qui n'ont pas été traités avec la réponse actuelle, probablement en raison de l'atteinte d'une limite de taille de réponse. La valeur Type : Array |
UnprocessedKeys :
Table : Keys
|
Valeurs d'attribut de clé primaire qui définissent les éléments et les attributs associés aux éléments. Pour plus d'informations sur les clés primaires, consultez Clé primaire. Type : tableau de paires nom-valeur d'attribut. |
UnprocessedKeys :
Table :
AttributesToGet
|
Noms d'attribut dans la table spécifiée. Si des noms d'attribut ne sont pas spécifiés, tous les attributs sont renvoyés. Si certains attributs ne sont pas trouvés, ils n'apparaissent pas dans le résultat. Type : tableau de noms d'attribut. |
UnprocessedKeys :
Table :
ConsistentRead
|
Si la valeur est définie sur Type : booléen. |
Erreurs spéciales
Erreur | Description |
---|---|
ProvisionedThroughputExceededException
|
Votre débit approvisionné autorisé maximum a été dépassé. |
Exemples
Les exemples suivants montrent une HTTP POST demande et une réponse utilisant l' BatchGetItemopération. Pour des exemples d'utilisation du AWS SDK, voirUtilisation d'éléments et d'attributs dans DynamoDB.
Exemple de demande
L'exemple suivant demande des attributs de deux tables différentes.
// This header is abbreviated. // For a sample of a complete header, see DynamoDB de bas niveau 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"]} } }
Exemple de réponse
L'exemple suivant est la réponse.
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":{}
}