BatchGetItem

importante

Esta sección se refiere a la versión 2011-12-05 del API, que está obsoleta y no debe utilizarse para nuevas aplicaciones.

Para consultar la documentación sobre la API de bajo nivel actual, consulte la Referencia de la API de Amazon DynamoDB.

Descripción

La operación BatchGetItem devuelve los atributos de varios elementos de varias tablas mediante sus claves primarias. El número máximo de elementos que pueden recuperarse en una única operación es de 100. Además, el número de elementos recuperados está restringido por un límite de tamaño de 1 MB. Si se supera el límite de tamaño de respuesta o se devuelve un resultado parcial por haberse excedido el rendimiento aprovisionado de la tabla o debido a un error de procesamiento interno, DynamoDB devuelve un valor UnprocessedKeys para que pueda reintentar la operación comenzando por el siguiente elemento que desea obtener. DynamoDB ajusta automáticamente el número de elementos que se devuelven por página para aplicar este límite. Por ejemplo, aunque solicite que se recuperen 100 elementos con un tamaño individual de 50 KB cada uno, el sistema devolverá 20 elementos y un valor de UnprocessedKeys correspondiente para que pueda obtener la siguiente página de resultados. Si lo desea, la aplicación puede incluir su propia lógica para ensamblar las páginas de resultados en un único conjunto.

Si no se puede procesar ningún elemento porque no hay rendimiento aprovisionado suficiente en cada una de las tablas objeto de la solicitud, DynamoDB devuelve un error ProvisionedThroughputExceededException.

nota

De forma predeterminada, BatchGetItem realiza lecturas consistentes finales en cada tabla incluida en la solicitud. Si desea realizar en su lugar lecturas consistentes, puede establecer el parámetro ConsistentRead en true para cada tabla.

BatchGetItem recupera los elementos en paralelo para minimizar las latencias de respuesta.

Al diseñar la aplicación, tenga en cuenta que DynamoDB no garantiza cómo se ordenarán los atributos en la respuesta devuelta. Incluya en AttributesToGet los valores de clave principal de los elementos de la solicitud para ayudar a analizar la respuesta por elementos.

Si los elementos solicitados no existen, no se devuelve nada en la respuesta para esos elementos. Las solicitudes de elementos inexistentes consumen las unidades de capacidad de lectura mínimas, según el tipo de lectura. Para obtener más información, consulte Tamaños y formatos de elementos de DynamoDB.

Solicitudes

Sintaxis

// This header is abbreviated. For a sample of a complete header, see API de bajo nivel 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"]
        }
    }
}

Nombre	Descripción	Obligatorio
RequestItems	Un contenedor del nombre de la tabla y los elementos correspondientes que se deben obtener según su clave principal. Mientras se solicitan elementos, cada nombre de tabla puede invocarse solo una vez por operación. Tipo: cadena Valor predeterminado: None	Sí
Table	El nombre de la tabla que contiene los elementos que hay que obtener. La entrada es simplemente una cadena que especifica una tabla existente sin ninguna etiqueta. Tipo: cadena Valor predeterminado: None	Sí
Table:Keys	Los valores de clave principal que definen los elementos de la tabla especificada. Para obtener más información sobre claves principales, consulte Clave principal. Tipo: Keys	Sí
Table:AttributesToGet	Matriz de nombres de atributos contenidos en la tabla especificada. Si no se especifican sus nombres, se devuelven todos los atributos. Si algún atributo no se encuentra, no aparecerá en los resultados. Tipo: matriz	No
Table:ConsistentRead	Si se establece en true, se emite una lectura consistente; en caso contrario, se utiliza una lectura consistente final. Tipo: Booleano	No

Respuestas

Sintaxis

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

Nombre	Descripción
Responses	Nombres de tablas y los atributos de los elementos respectivos de las tablas. Tipo: mapa
Table	El nombre de la tabla que contiene los elementos. La entrada es simplemente una cadena que especifica la tabla existente sin ninguna etiqueta. Tipo: cadena
Items	Contenedor de los nombres y valores de los atributos que coinciden con los parámetros de la operación. Tipo: Map, mapa de los nombres de atributos y sus tipos de datos y valores.
ConsumedCapacityUnits	La cantidad de unidades de capacidad de lectura consumidas para cada tabla. Este valor muestra el número aplicado al rendimiento aprovisionado. Las solicitudes de elementos inexistentes consumen las unidades de capacidad de lectura mínimas, según el tipo de lectura. Para obtener más información, consulte Modo de capacidad aprovisionada. Tipo: Number
UnprocessedKeys	Contiene una matriz de tablas y sus respectivas claves que no se han procesado en la respuesta actual, posiblemente debido a que se ha alcanzado un límite de tamaño de respuesta. El valor de UnprocessedKeys tiene el mismo formato que el parámetro RequestItems (por lo que se puede proporcionar directamente a una operación BatchGetItem posterior). Para obtener más información, consulte el parámetro RequestItems anterior. Tipo: matriz
UnprocessedKeys: Table: Keys	Los valores de los atributos de clave principal que definen los elementos y los atributos asociados con los elementos. Para obtener más información sobre claves principales, consulte Clave principal. Tipo: Array; matriz de pares de nombre-valor del atributo.
UnprocessedKeys: Table: AttributesToGet	Nombres de los atributos contenidos en la tabla especificada. Si no se especifican sus nombres, se devuelven todos los atributos. Si algún atributo no se encuentra, no aparecerá en los resultados. Tipo: Array, matriz de nombres de atributos.
UnprocessedKeys: Table: ConsistentRead	Si se establece en true, se utiliza una lectura consistente para la tabla especificada; en caso contrario, se utiliza una lectura consistente final. Tipo: booleano.

Errores especiales

Error	Descripción
ProvisionedThroughputExceededException	Se ha superado el desempeño provisionado máximo permitido.

Ejemplos

En los siguientes ejemplos se muestra una solicitud HTTP POST y su respuesta utilizando la operación BatchGetItem. Para obtener ejemplos sobre cómo usar el SDK de AWS, consulte Uso de elementos y atributos.

Solicitud de ejemplo

En el ejemplo siguiente se solicitan atributos de dos tablas diferentes.

// This header is abbreviated. 
// For a sample of a complete header, see API de bajo nivel 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"]}
    }
}

Respuesta de ejemplo

El ejemplo siguiente es la respuesta.

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":{}
}