Dokumen ini menunjukkan cara mengelompokkan panggilan API secara bersamaan untuk mengurangi jumlah koneksi yang harus dibuat klien Anda. Pengelompokan dapat meningkatkan efisiensi aplikasi dengan mengurangi round-trip jaringan dan meningkatkan throughput.
Ringkasan
Setiap koneksi yang dibuat klien akan menghasilkan sejumlah {i>overhead<i} tertentu. Google Slides API mendukung batch 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, yang akan mengambil kembali satu respons.
Kami mendorong pengguna untuk selalu mengelompokkan beberapa permintaan bersama-sama. Berikut adalah beberapa contoh situasi saat Anda dapat menggunakan pengelompokan:
- Anda baru saja mulai menggunakan API dan memiliki banyak data untuk diupload.
- Anda perlu mengupdate metadata atau properti, seperti pemformatan, pada beberapa objek.
- Anda perlu menghapus banyak objek.
Pertimbangan batasan, otorisasi & dependensi
Berikut daftar item lain yang perlu dipertimbangkan saat menggunakan update 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 kemunculannya 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 batch
Permintaan batch terdiri dari satu panggilan metode batchUpdate
dengan beberapa subpermintaan untuk, misalnya, menambahkan lalu memformat presentasi.
Setiap permintaan divalidasi sebelum diterapkan. Semua subpermintaan dalam batch update diterapkan secara atomik. Artinya, jika ada permintaan yang tidak valid, maka seluruh update akan gagal dan tidak ada perubahan (yang mungkin 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 disusun dalam array permintaan individual. Setiap permintaan menggunakan JSON untuk mewakili objek permintaan dan untuk menampung propertinya.
Format respons batch
Format response untuk permintaan batch mirip dengan format permintaan. Respons server berisi balasan lengkap dari satu objek respons.
Properti objek JSON utama diberi nama replies
. Respons
ditampilkan dalam array, dengan setiap respons terhadap salah satu permintaan menempati
urutan indeks yang sama seperti permintaan yang terkait. Beberapa permintaan tidak memiliki
respons dan respons pada indeks array tersebut kosong.
Contoh
Contoh kode berikut menunjukkan penggunaan pengelompokan dengan Slides API.
Permintaan
Contoh permintaan batch ini menunjukkan cara:
Tambahkan resource
presentations.pages
ke presentasi yang sudah ada, denganinsertionIndex
dari1
, menggunakan metodeCreateSlideRequest
.Tambahkan
shapeType
dari jenisTEXT_BOX
ke slide baru menggunakan metodeCreateShapeRequest
.Masukkan teks "Hello World" ke dalam kolom baru menggunakan metode
InsertTextRequest
.
{ "requests":[ { "createSlide":{ "insertionIndex":1, "objectId":"newSlide" } }, { "createShape":{ "elementProperties":{ "pageObjectId":"newSlide", "size":{ "height":{ "magnitude":50, "unit":"PT" }, "width":{ "magnitude":200, "unit":"PT" } } }, "shapeType":"TEXT_BOX", "objectId":"newTextBox" } }, { "insertText":{ "objectId":"newTextBox", "text":"Hello World" } } ] }
Respons
Contoh respons batch ini menampilkan informasi tentang cara penerapan setiap subpermintaan dalam permintaan batch. Perhatikan bahwa metode
InsertTextRequest
tidak berisi respons sehingga nilai indeks array pada [2]
terdiri dari tanda kurung kurawal kosong. Permintaan batch menampilkan properti WriteControl
, yang menunjukkan cara permintaan tulis dieksekusi.
{ "requiredRevisionId": ID "presentationId": "", "replies":[ { "createSlide":{ "objectId":"newSlide" } }, { "createShape":{ "objectId":"newTextBox" } }, { } ], "writeControl":{ "requiredRevisionId": REVISION_ID } }