Permintaan batch

Dokumen ini menunjukkan cara mengelompokkan panggilan API sekaligus untuk mengurangi jumlah koneksi yang harus dibuat klien Anda. Pengelompokan dapat meningkatkan efisiensi aplikasi dengan mengurangi perjalanan bolak-balik jaringan dan meningkatkan throughput.

Ringkasan

Setiap koneksi yang dibuat klien Anda akan menghasilkan sejumlah overhead tertentu. Google Spreadsheet API mendukung pengelompokan untuk memungkinkan klien Anda menempatkan beberapa objek permintaan, masing-masing menentukan satu jenis permintaan yang akan dilakukan, ke dalam satu permintaan batch. Permintaan batch dapat meningkatkan performa dengan menggabungkan beberapa subpermintaan menjadi satu panggilan ke server, yang mengambil kembali satu respons.

Sebaiknya pengguna selalu menggabungkan beberapa permintaan. Berikut beberapa contoh situasi saat Anda dapat menggunakan pengelompokan:

  • Anda baru saja mulai menggunakan API dan memiliki banyak data untuk diupload.
  • Anda perlu memperbarui metadata atau properti, seperti pemformatan, di beberapa objek.
  • Anda perlu menghapus banyak objek.

Pertimbangan batas, otorisasi, & dependensi

Berikut adalah daftar item lain yang perlu dipertimbangkan saat menggunakan pembaruan batch:

  • Setiap permintaan batch, termasuk semua subpermintaan, dihitung sebagai satu permintaan API terhadap batas penggunaan Anda.
  • Permintaan batch diautentikasi satu kali. Autentikasi tunggal ini berlaku untuk semua objek update batch dalam permintaan.
  • Server memproses subpermintaan dalam urutan yang sama seperti yang muncul dalam permintaan batch. Subpermintaan berikutnya dapat bergantung pada tindakan yang dilakukan selama subpermintaan sebelumnya. Misalnya, dalam permintaan batch yang sama, pengguna dapat menyisipkan teks ke dalam dokumen yang ada, lalu menata gayanya.

Detail batch

Permintaan batch terdiri dari satu panggilan metode batchUpdate dengan beberapa subpermintaan untuk, misalnya, menambahkan, lalu memformat spreadsheet.

Setiap permintaan divalidasi sebelum diterapkan. Semua subpermintaan dalam update batch diterapkan secara atomik. Artinya, jika ada permintaan yang tidak valid, seluruh update tidak akan berhasil dan tidak ada perubahan (yang berpotensi bergantung) yang akan diterapkan.

Beberapa permintaan memberikan respons dengan informasi tentang permintaan yang diterapkan. Misalnya, semua permintaan pembaruan batch untuk menambahkan objek akan menampilkan respons sehingga Anda dapat mengakses metadata objek yang baru ditambahkan, seperti ID atau judul.

Dengan pendekatan ini, Anda dapat membuat seluruh dokumen Google menggunakan satu permintaan update batch API dengan beberapa subpermintaan.

Format permintaan batch

Permintaan adalah satu permintaan JSON yang berisi beberapa subpermintaan bertingkat dengan satu properti yang diperlukan: requests. Permintaan dibuat dalam array permintaan individual. Setiap permintaan menggunakan JSON untuk mewakili objek permintaan dan untuk memuat propertinya.

Format respons batch

Format respons untuk permintaan batch mirip dengan format permintaan. Respons server berisi balasan lengkap dari satu objek respons.

Properti objek JSON utama bernama replies. Respons ditampilkan dalam array, dengan setiap respons untuk salah satu permintaan menempati urutan indeks yang sama dengan permintaan yang sesuai. Beberapa permintaan tidak memiliki respons dan respons pada indeks array tersebut kosong.

Contoh

Contoh berikut menunjukkan penggunaan batch dengan Sheets API.

Permintaan

Contoh permintaan batch ini menunjukkan cara:

Dengan menambahkan ID sheet dalam permintaan, pengguna dapat menggunakan ID sheet untuk subpermintaan lain dalam panggilan API yang sama. Hal ini meningkatkan performa dengan menghindari siklus tulis-baca-tulis.

Untuk daftar jenis permintaan pembaruan batch, yang dikelompokkan ke dalam berbagai kategori, lihat tabel di bagian Operasi pembaruan batch.

{
   "requests":[
      {
         "addSheet":{
            "properties":{
               "sheetId":123456
            }
         }
      },
      {
         "updateCells":{
            "start":{
               "sheetId":123456
            },
            "rows":[
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"hello"
                        }
                     }
                  ]
               },
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"world"
                        }
                     }
                  ]
               }
            ],
            "fields":"userEnteredValue"
         }
      },
      {
         "addNamedRange":{
            "namedRange":{
               "name":"newRange",
               "range":{
                  "sheetId":123456,
                  "endRowIndex":2
               }
            }
         }
      }
   ]
}

Respons

Contoh respons batch ini menampilkan informasi tentang cara setiap subpermintaan dalam permintaan batch diterapkan. Perhatikan bahwa UpdateCellsRequest tidak berisi respons sehingga nilai indeks array di [1] terdiri dari kurung kurawal kosong.

"replies":[
   {
      "addSheet":{
         "properties":{
            "sheetId":123456,
            "title":"Sheet3",
            "index":2,
            "sheetType":"GRID",
            "gridProperties":{
               "rowCount":1000,
               "columnCount":26
            }
         }
      }
   },
   {
      
   },
   {
      "addNamedRange":{
         "namedRange":{
            "namedRangeId":"2104325079",
            "name":"newRange",
            "range":{
               "sheetId":123456,
               "startRowIndex":0,
               "endRowIndex":2,
               "startColumnIndex":0,
               "endColumnIndex":26
            }
         }
      }
   }
]