BatchGetItem - Amazon DynamoDB
DeskripsiPermintaanResponsKesalahan khususContoh

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

BatchGetItem

penting

This section refers to API version 2011-12-05, which is deprecated and should not be used for new applications.

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 API tingkat rendah 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"]
        }
    }
}
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 Mode kapasitas yang disediakan DynamoDB.

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 di DynamoDB.

Permintaan sampel

Contoh berikut meminta atribut dari dua tabel yang berbeda.

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

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