Permintaan batch

Dokumen ini menunjukkan cara mengelompokkan panggilan API secara bersamaan untuk mengurangi jumlah koneksi yang harus dibuat klien Anda. Pengelompokan dapat meningkatkan dengan mengurangi perjalanan dua arah jaringan dan meningkatkan throughput.

Ringkasan

Setiap koneksi yang dibuat klien Anda menghasilkan jumlah {i>overhead<i} tertentu. Google Docs API mendukung pengelompokan agar klien Anda dapat menempatkan objek permintaan, masing-masing menentukan satu jenis permintaan untuk dilakukan, menjadi satu permintaan batch. Permintaan batch dapat meningkatkan performa dengan menggabungkan beberapa subpermintaan menjadi satu panggilan ke server, mengambil respons tunggal.

Sebaiknya pengguna selalu mengelompokkan beberapa permintaan secara bersamaan. Berikut beberapa contoh situasi saat Anda dapat menggunakan pengelompokan:

  • Anda baru saja mulai menggunakan API dan memiliki banyak data yang perlu diupload.
  • Anda perlu memperbarui metadata atau properti, seperti pemformatan, pada beberapa objek terstruktur dalam jumlah besar.
  • Anda harus menghapus banyak objek.

Batas, otorisasi & pertimbangan dependensi

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

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

Detail batch

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

Setiap permintaan divalidasi sebelum diterapkan. Semua subpermintaan dalam batch pembaruan diterapkan secara atomik. Artinya, jika permintaan tidak valid, seluruh pembaruan gagal dan tidak ada satu pun pembaruan (kemungkinan bergantung) perubahan akan diterapkan.

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

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

Format permintaan batch

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

Format respons batch

Format response untuk permintaan batch mirip dengan format permintaan. Respons server berisi balasan lengkap dari respons yang benar.

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

Contoh

Contoh kode berikut menunjukkan penggunaan pengelompokan dengan Docs API.

Permintaan

Contoh permintaan batch ini menunjukkan cara:

  • Sisipkan "Halo Dunia" teks ke awal dokumen yang ada, dengan indeks location dari 1, menggunakan InsertTextRequest

  • Memperbarui kata "Hello" menggunakan UpdateTextStyleRequest startIndex dan endIndex menentukan range dari teks yang diformat di dalam segmen data.

  • Dengan menggunakan textStyle, setel gaya font menjadi tebal dan warna ke biru hanya kata "Hello".

  • Menggunakan WriteControl , Anda dapat mengontrol cara permintaan tulis dieksekusi. Untuk selengkapnya informasi, lihat Menetapkan konsistensi status dengan WriteControl.

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1,
               "tabId":TAB_ID
            },
            "text":"Hello World"
         }
      },
      {
         "updateTextStyle":{
            "range":{
               "startIndex":1,
               "endIndex":6
            },
            "textStyle":{
               "bold":true,
               "foregroundColor":{
                  "color":{
                     "rgbColor":{
                        "blue":1
                     }
                  }
               }
            },
            "fields":"bold,foreground_color"
         }
      }
   ],
   "writeControl": {
      "requiredRevisionId": "REQUIRED_REVISION_ID"
  }
}

Ganti TAB_ID dan REQUIRED_REVISION_ID dengan masing-masing ID tab dan ID revisi dari dokumen permintaan tulis diterapkan.

Respons

Contoh respons batch ini menampilkan informasi tentang bagaimana setiap subpermintaan dalam permintaan batch diterapkan. Baik InsertTextRequest atau UpdateTextStyleRequest berisi respons, sehingga nilai indeks array pada [0] dan [1] terdiri tanda kurung kurawal kosong. Permintaan batch menampilkan objek WriteControl, yang menunjukkan cara permintaan dijalankan.

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}