Permintaan batch

Dokumen ini menunjukkan cara mengelompokkan panggilan API secara bersamaan untuk mengurangi jumlah koneksi yang harus dibuat klien Anda. Batching dapat meningkatkan efisiensi aplikasi 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 beberapa objek permintaan, yang 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, sehingga mengambil kembali satu respons.

Sebaiknya pengguna selalu mengelompokkan beberapa permintaan secara bersamaan. Berikut adalah beberapa contoh situasi yang memungkinkan Anda 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.
  • Anda harus menghapus banyak objek.

Pertimbangan batasan, otorisasi & dependensi

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

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

Detail batch

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

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

Beberapa permintaan memberikan respons dengan informasi tentang permintaan yang diterapkan. Misalnya, semua permintaan update batch untuk menambahkan objek 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 wajib: requests. Permintaan 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 untuk objek respons tunggal.

Properti objek JSON utama diberi nama replies. Respons ditampilkan dalam array, dengan setiap respons terhadap salah satu permintaan menempati urutan indeks yang sama dengan permintaan terkait. 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 teks "Halo Dunia" ke awal dokumen yang sudah ada, dengan indeks location sebesar 1, menggunakan InsertTextRequest.

  • Perbarui kata "Hello" menggunakan UpdateTextStyleRequest. startIndex dan endIndex menentukan range teks berformat dalam segmen.

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

  • Dengan menggunakan kolom WriteControl, Anda dapat mengontrol cara permintaan tulis dijalankan. Untuk mengetahui informasi selengkapnya, lihat Menetapkan konsistensi status dengan WriteControl.

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1
            },
            "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 REQUIRED_REVISION_ID dengan ID revisi dokumen tempat permintaan tulis diterapkan.

Respons

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

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