BatchGetItem

penting

Bagian ini mengacu pada API versi 2011-12-05, yang sudah usang dan tidak boleh digunakan untuk aplikasi baru.

Untuk dokumentasi tentang API tingkat rendah saat ini, lihat Referensi API Amazon DynamoDB.

Deskripsi

Operasi BatchGetItem mengembalikan atribut untuk beberapa item dari sejumlah tabel menggunakan kunci primernya. Jumlah maksimum item yang dapat diambil untuk suatu operasi adalah 100. Selain itu, jumlah item yang diambil dibatasi pada ukuran 1 MB. Jika batas ukuran respons terlampaui atau hasil parsial dikembalikan karena throughput yang disediakan tabel terlampaui, atau karena kegagalan pemrosesan internal, DynamoDB mengembalikan nilai UnprocessedKeys agar Anda dapat mengulangi operasi, dimulai dengan item berikutnya untuk didapatkan. DynamoDB secara otomatis menyesuaikan jumlah item yang dikembalikan per halaman untuk memberlakukan batas ini. Misalnya, meskipun Anda meminta untuk mengambil 100 item, tetapi setiap item berukuran 50 KB, sistem akan mengembalikan 20 item dan nilai UnprocessedKeys yang sesuai agar Anda dapat memperoleh halaman hasil berikutnya. Jika diinginkan, aplikasi Anda dapat menyertakan logikanya sendiri untuk menyusun halaman hasil menjadi satu set.

Jika tidak ada item yang dapat diproses karena throughput yang disediakan tidak memadai pada setiap tabel yang terlibat dalam permintaan, DynamoDB akan mengembalikan kesalahan ProvisionedThroughputExceededException.

catatan

Secara default, BatchGetItem melakukan bacaan akhir konsisten di setiap tabel dalam permintaan. Anda dapat mengatur parameter ConsistentRead menjadi true, sesuai tiap tabelnya, jika Anda ingin pembacaan yang konsisten.

BatchGetItem mengambil item secara paralel untuk meminimalkan latensi respons.

Saat merancang aplikasi Anda, ingatlah bahwa DynamoDB tidak menjamin bahwa pengurutan atribut dilakukan sesuai respons yang dikembalikan. Sertakan nilai kunci primer di AttributesToGet untuk item dalam permintaan Anda guna membantu menguraikan respons berdasarkan item.

Jika item yang diminta tidak ada, respons untuk item tersebut tidak mengembalikan apa pun. Permintaan untuk item yang tidak ada menggunakan unit kapasitas baca minimum sesuai dengan jenis pembacaan. Untuk informasi selengkapnya, lihat Ukuran dan format item DynamoDB.

Permintaan

Sintaks

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

Nama	Deskripsi	Wajib
RequestItems	Sebuah kontainer nama tabel dan item yang sesuai untuk mendapatkan kunci primer. Saat meminta item, setiap nama tabel hanya dapat diinvokasi sekali per operasi. Jenis: String Default: Tidak Ada	Ya
Table	Nama tabel yang berisi item untuk didapatkan. Entri hanyalah string yang menentukan tabel yang sudah ada tanpa label. Jenis: String Default: Tidak Ada	Ya
Table:Keys	Nilai kunci primer yang menentukan item dalam tabel yang ditentukan. Untuk informasi selengkapnya tentang kunci primer, lihat Kunci primer. Jenis: Kunci	Ya
Table:AttributesToGet	Array Nama atribut dalam tabel yang ditentukan. Jika nama atribut tidak ditentukan, semua atribut akan dikembalikan. Jika beberapa atribut tidak ditemukan, atribut tersebut tidak akan muncul dalam hasil. Jenis: Array	Tidak
Table:ConsistentRead	Jika diatur ke true, bacaan yang konsisten akan diterbitkan. Jika tidak, bacaan akhir konsisten akan digunakan. Jenis: Boolean	Tidak

Respons

Sintaks

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

Nama	Deskripsi
Responses	Nama tabel dan setiap atribut item dari tabel. Jenis: Peta
Table	Nama tabel yang berisi item. Entri hanyalah string yang menentukan tabel tanpa label. Jenis: String
Items	Kontainer untuk nama dan nilai atribut yang memenuhi parameter operasi. Jenis: Peta nama atribut serta nilai dan jenis data.
ConsumedCapacityUnits	Jumlah unit kapasitas baca yang dikonsumsi, untuk setiap tabel. Nilai ini menunjukkan jumlah yang diterapkan pada throughput yang disediakan. Permintaan untuk item yang tidak ada yang mengonsumsi unit kapasitas baca minimum, tergantung jenis baca. Untuk informasi selengkapnya, lihat Tabel kapasitas yang disediakan. Jenis: Angka
UnprocessedKeys	Berisi array tabel dan masing-masing kuncinya yang tidak diproses dengan respons terkini, kemungkinan karena mencapai batas ukuran respons. Nilai UnprocessedKeys memiliki format yang sama dengan parameter RequestItems (sehingga nilai dapat diberikan langsung ke operasi BatchGetItem berikutnya). Untuk informasi selengkapnya, lihat parameter RequestItems di atas. Jenis: Array
UnprocessedKeys: Table: Keys	Nilai atribut kunci primer yang menentukan item dan atribut yang terkait dengan item. Untuk informasi selengkapnya tentang kunci primer, lihat Kunci primer. Jenis: Array pasangan nama-nilai atribut.
UnprocessedKeys: Table: AttributesToGet	Nama atribut dalam tabel yang ditentukan. Jika nama atribut tidak ditentukan, semua atribut akan dikembalikan. Jika beberapa atribut tidak ditemukan, atribut tersebut tidak akan muncul dalam hasil. Jenis: Array nama atribut.
UnprocessedKeys: Table: ConsistentRead	Jika diatur menjadi true, bacaan konsisten digunakan untuk tabel tertentu. Jika tidak, bacaan akhir konsisten akan digunakan. Jenis: Boolean.

Kesalahan khusus

Kesalahan	Deskripsi
ProvisionedThroughputExceededException	Throughput tersedia maksimum milik Anda telah terlampaui.

Contoh

Contoh berikut menunjukkan permintaan HTTP POST dan respon menggunakan BatchGetItem operasi. Untuk contoh menggunakan AWS SDK, lihatBekerja dengan item dan atribut.

Permintaan sampel

Contoh berikut meminta atribut dari dua tabel yang berbeda.

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

Respons sampel

Sampel berikut ini adalah responsnya.

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