Permintaan batch

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

Ringkasan

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

Kami mendorong pengguna untuk selalu mengelompokkan beberapa permintaan bersama-sama. Berikut beberapa contoh situasi saat Anda dapat menggunakan pengelompokan:

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

Pertimbangan batas, otorisasi & dependensi

Berikut daftar item lain yang perlu dipertimbangkan ketika menggunakan pembaruan batch:

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

Detail paket

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 akan gagal dan tidak ada satu pun perubahan (yang berpotensi bergantung) yang diterapkan.

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

Dengan pendekatan ini, Anda dapat mem-build 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 masing-masing permintaan. Setiap permintaan menggunakan JSON untuk mewakili objek permintaan dan memuat propertinya.

Format respons batch

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

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

Contoh

Contoh berikut menunjukkan penggunaan pengelompokan dengan Docs API.

Permintaan

Contoh permintaan batch ini menunjukkan cara:

  • Sisipkan teks "Hello World" (Halo Dunia) ke awal dokumen yang sudah ada, dengan indeks Location 1, menggunakan InsertTextRequest.
  • Perbarui kata "Halo" menggunakan UpdateTextStyleRequest. startIndex dan endIndex menentukan range teks berformat dalam segmen.`
  • Dengan menggunakan textStyle, setel gaya font menjadi tebal dan warna menjadi biru.
{
   "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"
         }
      }
   ]
}

Respons

Contoh respons batch ini menampilkan informasi tentang cara setiap subpermintaan dalam permintaan batch diterapkan. Perhatikan InsertTextRequest dan UpdateTextStyleRequest tidak berisi respons, sehingga nilai indeks array di [0] dan [1] terdiri dari tanda kurung kurawal kosong. Permintaan batch menampilkan WriteControl yang menunjukkan cara permintaan tulis dieksekusi.

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