BatchGetItem

Important

Cette section fait référence à l'API version 2011-12-05 qui est obsolète et ne doit pas être utilisée pour de nouvelles applications.

Pour une documentation sur l'API de bas niveau actuelle, consultez la Référence d'API Amazon DynamoDB.

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 plus d’informations, consultez Tailles et formats d'élément DynamoDB.

Requêtes

Syntaxe

// This header is abbreviated. For a sample of a complete header, see API de bas niveau de DynamoDB.
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 : chaîne 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 : chaîne 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 true, une lecture cohérente est effectuée. Sinon une cohérence éventuelle est utilisée. 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 : chaîne
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, consultez Mode de capacité provisionnée. 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 UnprocessedKeys se présente sous la même forme qu'un paramètre RequestItems (de sorte que la valeur peut être fournie directement à une opération BatchGetItem subséquente). Pour plus d'informations, consultez le paramètre RequestItems ci-dessus. 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 true, une lecture cohérente est utilisée pour la table spécifiée. Sinon, une lecture éventuellement cohérente est utilisée. 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 requête et une réponse HTTP POST utilisant l' BatchGetItemopération. Pour des exemples d'utilisation du AWS SDK, consultezUtilisation des éléments et des attributs.

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 API de bas niveau de DynamoDB.
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":{}
}