BatchGetItem - Amazon DynamoDB

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

BatchGetItem

Importante

In questa sezione si fa riferimento alla versione API 2011-12-05, che è obsoleta e non deve essere utilizzata per le nuove applicazioni.

Per informazioni sull'API di basso livello corrente, consulta la Amazon DynamoDB API Reference.

Descrizione

L'operazione BatchGetItem restituisce gli attributi per più elementi da più tabelle utilizzando le loro chiavi primarie. Il numero massimo di elementi che possono essere recuperati per una singola operazione è 100. Inoltre, il numero di elementi recuperati è vincolato da un limite di 1 MB. Se il limite delle dimensioni della risposta viene superato o viene restituito un risultato parziale perché viene superata la velocità effettiva assegnata della tabella oppure a causa di un errore di elaborazione interno, DynamoDB restituisce un valore UnprocessedKeys in modo da poter riprovare l'operazione iniziando con l'elemento successivo da ottenere. per applicare questo limite DynamoDB regola automaticamente il numero di elementi restituiti per pagina. Ad esempio, anche se si chiede di recuperare 100 elementi, ma ogni singolo elemento ha una dimensione di 50 KB, il sistema restituisce 20 elementi e un valore UnprocessedKeys appropriato in modo da visualizzare la pagina di risultati successiva. Se lo desidera, l'applicazione può includere la propria logica per assemblare le pagine dei risultati in un unico set.

Se non è possibile elaborare gli elementi a causa della velocità effettiva assegnata insufficiente su ciascuna delle tabelle coinvolte nella richiesta, DynamoDB restituisce un errore ProvisionedThroughputExceededException.

Nota

Per impostazione predefinita,BatchGetItem esegue letture a consistenza finale su ogni tabella nella richiesta. È possibile impostare il parametro ConsistentRead su true, su base per tabella, se desideri invece avere letture consistenti.

BatchGetItem recupera gli elementi in parallelo per ridurre al minimo la latenza delle risposte.

Durante la progettazione dell'applicazione, tenere presente che DynamoDB non garantisce come gli attributi vengono ordinati nella risposta restituita. Includere i valori delle chiavi primarie in AttributesToGet per gli elementi nella richiesta per analizzare la risposta in base all'elemento.

Se gli elementi richiesti non esistono, non viene restituito nulla nella risposta per tali elementi. Le richieste di elementi inesistenti consumano le unità di capacità di lettura minima in base al tipo di lettura. Per ulteriori informazioni, consulta Dimensioni e formati degli elementi DynamoDB.

Richieste

Sintassi

// This header is abbreviated. For a sample of a complete header, see DynamoDB di basso livello 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"] } } }
Nome Descrizione Richiesto
RequestItems

Un container del nome della tabella e degli elementi corrispondenti da ottenere in base alla chiave primaria. Durante la richiesta di elementi, ogni nome di tabella può essere richiamato una sola volta per operazione.

▬Tipo: stringa

Impostazione predefinita: nessuna

Table

Il nome della tabella che contiene gli elementi da ricevere. La voce è semplicemente una stringa che specifica una tabella esistente senza etichetta.

▬Tipo: stringa

Impostazione predefinita: nessuna

Table:Keys

I valori della chiave primaria che definiscono gli elementi nella tabella specificata. Per ulteriori informazioni sulle chiavi primarie, vedere Chiave primaria.

Tipo: chiavi

Table:AttributesToGet

Matrice di nomi di attributi all'interno della tabella specificata. Se i nomi degli attributi non sono specificati, verranno restituiti tutti gli attributi. Se alcuni attributi non vengono trovati, non verranno visualizzati nel risultato.

Tipo: Array

No
Table:ConsistentRead

Se impostato su true, viene emessa una lettura consistente, altrimenti viene utilizzata la consistenza finale.

Tipo: Booleano

No

Risposte

Sintassi

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"]} } }
Nome Descrizione
Responses

I nomi delle tabelle e i rispettivi attributi degli elementi delle tabelle.

Tipo: Map

Table

Il nome della tabella che contiene gli elementi. La voce è semplicemente una stringa che specifica la tabella senza etichetta.

▬Tipo: stringa

Items

Container per i nomi e i valori degli attributi che soddisfano i parametri dell'operazione.

Tipo: mappa di nomi degli attributi e dei relativi tipi di dati e valori.

ConsumedCapacityUnits

Il numero di unità di capacità di lettura utilizzate per ogni tabella. Questo valore mostra il numero applicato alla velocità effettiva assegnata. Le richieste di elementi inesistenti consumano le unità di capacità di lettura minima in base al tipo di lettura. Per ulteriori informazioni, consulta Modalità di capacità fornita da DynamoDB.

Tipo: numero

UnprocessedKeys

Contiene una matrice di tabelle e le rispettive chiavi che non sono state elaborate con la risposta corrente, probabilmente a causa del raggiungimento di un limite sulla dimensione della risposta. Il valore UnprocessedKeys è nella stessa forma di un parametro RequestItems (quindi il valore può essere fornito direttamente a un'operazione BatchGetItem successiva). Per ulteriori informazioni, consulta la sezione precedente sul parametro RequestItems.

Tipo: Array

UnprocessedKeys: Table: Keys

I valori degli attributi della chiave primaria che definiscono gli elementi e gli attributi associati agli elementi. Per ulteriori informazioni sulle chiavi primarie, vedere Chiave primaria.

Tipo: matrice di coppie nome-valore.

UnprocessedKeys: Table: AttributesToGet

I nomi degli attributi all'interno della tabella specificata. Se i nomi degli attributi non sono specificati, verranno restituiti tutti gli attributi. Se alcuni attributi non vengono trovati, non verranno visualizzati nel risultato.

Tipo: matrice di nomi di attributi.

UnprocessedKeys: Table: ConsistentRead

Se impostato sutrue, viene utilizzata una lettura consistente per la tabella specificata, altrimenti viene utilizzata una lettura a consistenza finale.

Tipo: Boolean

Errori speciali

Errore Descrizione
ProvisionedThroughputExceededException

È stata superata la velocità effettiva assegnata massima consentita.

Esempi

Gli esempi seguenti mostrano una richiesta e una risposta HTTP POST utilizzando l' BatchGetItemoperazione. Per esempi di utilizzo dell' AWS SDK, consultaUtilizzo di elementi e attributi in DynamoDB.

Richiesta di esempio

L'esempio seguente richiede gli attributi da due tabelle differenti.

// This header is abbreviated. // For a sample of a complete header, see DynamoDB di basso livello 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"]} } }

Risposta di esempio

Il seguente esempio è la risposta.

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