BatchWriteItem

penting

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

Untuk dokumentasi tentang API tingkat rendah saat ini, lihatReferensi API Amazon DynamoDB Dynamo.

Deskripsi

Operasi ini memungkinkan Anda untuk menempatkan atau menghapus beberapa item di beberapa tabel dalam satu panggilan.

Untuk mengunggah satu item, Anda dapat menggunakan PutItem, dan untuk menghapus satu item, Anda dapat menggunakan DeleteItem. Namun, jika Anda ingin mengunggah atau menghapus sejumlah besar data, seperti mengunggah sejumlah besar data dari Amazon EMR (Amazon EMR) atau memigrasi data dari database lain ke DynamoDB, BatchWriteItem menawarkan alternatif yang efisien.

Jika Anda menggunakan bahasa seperti Java, Anda dapat menggunakan thread untuk mengunggah item secara paralel. Hal ini menambah kompleksitas dalam aplikasi Anda untuk menangani thread. Bahasa lain tidak mendukung threading. Misalnya, jika Anda menggunakan PHP, Anda harus mengunggah atau menghapus item satu per satu. Dalam kedua situasi, BatchWriteItem menyediakan alternatif di mana operasi menempatkan dan menghapus yang ditentukan diproses secara paralel, memberikan Anda kekuatan pendekatan thread pool tanpa harus memasukkan kompleksitas dalam aplikasi Anda.

Perhatikan bahwa setiap operasi menempatkan dan menghapus individual yang ditentukan dalam operasi BatchWriteItem berbiaya sama dalam hal unit kapasitas yang digunakan. Namun, karena BatchWriteItem melakukan operasi yang ditentukan secara paralel, Anda mendapatkan latensi yang lebih rendah. Operasi hapus pada item yang tidak ada mengonsumsi 1 unit kapasitas tulis. Untuk informasi lebih lanjut tentang unit kapasitas yang digunakan, lihat Bekerja dengan tabel dan data di DynamoDB.

Saat menggunakan BatchWriteItem, perhatikan batasan berikut:

• Operasi maksimum dalam satu permintaan – Anda dapat menentukan hingga total 25 operasi menempatkan atau menghapus; namun, total permintaan ukuran tidak dapat melampaui 1 MB (payload HTTP).

• Anda dapat menggunakan operasi BatchWriteItem hanya untuk menempatkan dan menghapus item. Anda tidak dapat menggunakannya untuk memperbarui item yang ada.

• Bukan operasi atom – Operasi individu yang ditentukan dalam BatchWriteItem adalah atomik; namun BatchWriteItem secara keseluruhan adalah operasi "upaya terbaik" dan bukan operasi atomik. Artinya, dalam permintaan BatchWriteItem, beberapa operasi mungkin berhasil dan yang lainnya mungkin gagal. Operasi yang gagal dikembalikan ke bidang UnprocessedItems dalam respons. Sejumlah kegagalan ini mungkin karena Anda melampaui throughput yang disediakan dan dikonfigurasi untuk tabel atau kegagalan sementara seperti kesalahan jaringan. Anda dapat menyelidiki dan secara opsional mengirim ulang permintaan. Biasanya, Anda memanggil BatchWriteItem dalam satu putaran dan di setiap pemeriksaan pengulangan untuk item yang belum diproses, dan mengirimkan permintaan BatchWriteItem baru dengan item yang belum diproses tersebut.

• Tidak mengembalikan item apa pun – BatchWriteItem dirancang untuk mengunggah data dalam jumlah besar secara efisien. Hal itu tidak menyediakan sejumlah kecanggihan yang ditawarkan oleh PutItem dan DeleteItem. Sebagai contoh, DeleteItem mendukung bidang ReturnValues di isi permintaan Anda untuk meminta item yang dihapus dalam respons. Operasi BatchWriteItem tidak mengembalikan item apa pun dalam respons.

• Tidak seperti PutItem dan DeleteItem, BatchWriteItem tidak memungkinkan Anda untuk menentukan syarat pada permintaan tulis individu dalam operasi.

• Nilai atribut tidak boleh null; atribut jenis string dan biner harus memiliki panjang lebih dari nol; dan atribut jenis set tidak boleh kosong. Permintaan yang memiliki nilai kosong akan ditolak dengan ValidationException.

DynamoDB menolak keseluruhan batch operasi penulisan jika salah satu dari yang berikut ini benar:

• Jika satu atau beberapa tabel yang ditentukan dalam permintaan BatchWriteItem tidak ada.

• Jika atribut kunci primer yang ditentukan pada item dalam permintaan tidak cocok dengan skema kunci primer dalam tabel yang sesuai.

• Jika Anda mencoba untuk melakukan beberapa operasi pada item yang sama dalam permintaan BatchWriteItem yang sama. Sebagai contoh, Anda tidak dapat menempatkan dan menghapus item yang sama dalam permintaan BatchWriteItem yang sama.

• Jika ukuran permintaan total melampaui batas ukuran permintaan 1 MB (payload HTTP).

• Jika setiap item individu dalam suatu batch melampaui batas ukuran item 64 KB.

Permintaan

Sintaksis

// 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" :  RequestItems
} 

RequestItems
{
     "TableName1" :  [ Request, Request, ... ],
     "TableName2" :  [ Request, Request, ... ],
     ...
}

Request ::=
  PutRequest | DeleteRequest

PutRequest ::=
{
  "PutRequest" : {
     "Item" : {
        "Attribute-Name1" : Attribute-Value,
        "Attribute-Name2" : Attribute-Value,
         ...
     }
  }
}

DeleteRequest ::=
{
   "DeleteRequest" : {
      "Key" : PrimaryKey-Value
   }
}


PrimaryKey-Value ::= HashTypePK | HashAndRangeTypePK

HashTypePK ::=
{ 
   "HashKeyElement" : Attribute-Value
}

HashAndRangeTypePK
{ 
   "HashKeyElement" : Attribute-Value,
   "RangeKeyElement" : Attribute-Value, 
}

Attribute-Value ::= String | Numeric| Binary | StringSet | NumericSet | BinarySet 

Numeric ::=
{
   "N": "Number"
}

String ::=
{
   "S": "String"
}

Binary ::=
{
    "B": "Base64 encoded binary data"
}

StringSet ::=
{
   "SS": [ "String1", "String2", ... ]
}

NumberSet ::=
{
   "NS": [ "Number1", "Number2", ... ]
}  

BinarySet ::=
{
   "BS": [ "Binary1", "Binary2", ... ]
}

Dalam isi permintaan, objek JSON RequestItems menggambarkan operasi yang ingin Anda lakukan. Operasi dikelompokkan berdasarkan tabel. Anda dapat menggunakan BatchWriteItem untuk memperbarui atau menghapus beberapa item di beberapa tabel. Untuk setiap permintaan penulisan khusus, Anda harus mengidentifikasi jenis permintaan (PutItem, DeleteItem) diikuti dengan informasi terperinci tentang operasi.

• Untuk PutRequest, Anda memberikan item, yaitu daftar atribut dan nilai-nilainya.

• Untuk DeleteRequest, Anda memberikan nama dan nilai kunci utama.

Respons

Sintaksis

Berikut ini adalah sintaks dari isi JSON yang dikembalikan dalam respons.

{
  "Responses" :         ConsumedCapacityUnitsByTable
  "UnprocessedItems" :  RequestItems
} 

ConsumedCapacityUnitsByTable
{
    "TableName1" : { "ConsumedCapacityUnits", : NumericValue },
    "TableName2" : { "ConsumedCapacityUnits", : NumericValue },
     ...
}

RequestItems
This syntax is identical to the one described in the JSON syntax in the request.

Kesalahan Khusus

Tidak ada kesalahan khusus untuk operasi ini.

Contoh

Contoh berikut menunjukkan permintaan HTTP POST dan respons menggunakan dari operasi BatchWriteItem. Permintaan menentukan operasi berikut pada tabel Balas dan Thread:

• Menempatkan item dan menghapus item dari tabel Balas

• Menempatkan item ke dalam tabel Thread

Untuk contoh menggunakan SDK AWS, lihat Bekerja dengan item dan atribut.

Permintaan sampel

// 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":{
    "Reply":[
      {
        "PutRequest":{
          "Item":{
            "ReplyDateTime":{
              "S":"2012-04-03T11:04:47.034Z"
            },
            "Id":{
              "S":"DynamoDB#DynamoDB Thread 5"
            }
          }
        }
      },
      {
        "DeleteRequest":{
          "Key":{
            "HashKeyElement":{
              "S":"DynamoDB#DynamoDB Thread 4"
            },
            "RangeKeyElement":{
              "S":"oops - accidental row"
            }
          }
        }
      }
    ],
    "Thread":[
      {
        "PutRequest":{
          "Item":{
            "ForumName":{
              "S":"DynamoDB"
            },
            "Subject":{
              "S":"DynamoDB Thread 5"
            }
          }
        }
      }
    ]
  }
}

Contoh respons

Respons contoh berikut menunjukkan operasi put pada tabel Thread dan Balas yang berhasil dan operasi hapus pada tabel Balas yang gagal (karena alasan seperti throttling yang disebabkan saat Anda melampaui throughput yang disediakan di tabel). Perhatikan hal berikut dalam respons JSON:

• Objek Responses menunjukkan satu unit kapasitas yang digunakan pada tabel Thread dan Reply sebagai hasil dari kesuksesan operasi put pada setiap tabel ini.

• Objek UnprocessedItems menunjukkan kegagalan operasi hapus pada tabel Reply. Anda kemudian dapat mengeluarkan panggilan BatchWriteItem baru untuk mengatasi permintaan yang belum diproses ini.

HTTP/1.1 200 OK
x-amzn-RequestId: G8M9ANLOE5QA26AEUHJKJE0ASBVV4KQNSO5AEMVJF66Q9ASUAAJG
Content-Type: application/x-amz-json-1.0
Content-Length: 536
Date: Thu, 05 Apr 2012 18:22:09 GMT

{
   "Responses":{
      "Thread":{
         "ConsumedCapacityUnits":1.0
      },
      "Reply":{
         "ConsumedCapacityUnits":1.0
      }
   },
   "UnprocessedItems":{
      "Reply":[
         {
            "DeleteRequest":{
               "Key":{
                  "HashKeyElement":{
                     "S":"DynamoDB#DynamoDB Thread 4"
                  },
                  "RangeKeyElement":{
                     "S":"oops - accidental row"
                  }
               }
            }
         }
      ]
   }
}