Salah satu pendekatan khusus untuk pengelompokan, endpoint Batch HTTP Global
(www.googleapis.com/batch), telah dinonaktifkan pada 12 Agustus 2020, seperti yang diumumkan di blog Google
Developer. Pendekatan lain untuk pengelompokan masih berfungsi, seperti yang didokumentasikan di bagian lain
halaman ini. Jika kode Anda menggunakan endpoint Batch HTTP Global, lihat postingan blog untuk mendapatkan petunjuk tentang
transisi menggunakan pendekatan lain, seperti endpoint batch HTTP khusus API
(www.googleapis.com/batch/API/VERSION).
Dokumen ini menunjukkan cara mengelompokkan panggilan API secara bersamaan untuk mengurangi jumlah koneksi HTTP yang harus dibuat klien.
Dokumen ini khusus tentang membuat permintaan batch dengan mengirimkan permintaan HTTP. Jika Anda menggunakan library klien Google untuk membuat permintaan batch, lihat dokumentasi library klien.
Ringkasan
Setiap koneksi HTTP yang dilakukan klien Anda menghasilkan jumlah overhead tertentu. Google Mirror API mendukung pengelompokan, untuk memungkinkan klien Anda menempatkan beberapa panggilan API dalam satu permintaan HTTP.
Contoh situasi saat Anda mungkin ingin menggunakan pengelompokan:
- Anda baru saja mulai menggunakan API dan memiliki banyak data untuk diupload.
- Seorang pengguna membuat perubahan pada data saat aplikasi offline (terputus dari Internet), sehingga aplikasi Anda perlu menyinkronkan data lokal dengan server dengan mengirimkan banyak pembaruan dan penghapusan.
Di setiap kasus, Anda dapat mengelompokkan semuanya ke dalam satu permintaan HTTP, bukan mengirim setiap panggilan secara terpisah. Semua permintaan internal harus mengarah ke Google API yang sama.
Anda dibatasi hingga 1.000 panggilan dalam satu permintaan batch. Jika perlu melakukan lebih banyak panggilan dari itu, gunakan beberapa permintaan batch.
Catatan: Sistem batch untuk Google Mirror API menggunakan sintaksis yang sama dengan sistem pemrosesan batch O, tetapi semantiknya berbeda.
Detail paket
Permintaan batch terdiri dari beberapa panggilan API yang digabungkan menjadi satu permintaan HTTP, yang dapat dikirim ke batchPath yang ditentukan dalam dokumen penemuan API. Jalur default-nya adalah /batch/api_name/api_version. Bagian ini menjelaskan sintaksis batch secara mendetail; nantinya, ada contoh.
Catatan: Kumpulan permintaan n yang dikelompokkan secara bersamaan diperhitungkan dalam batas penggunaan Anda sebagai permintaan n, bukan sebagai satu permintaan. Permintaan batch dipisah menjadi sekumpulan permintaan sebelum diproses.
Format permintaan batch
Permintaan batch adalah satu permintaan HTTP standar yang berisi beberapa panggilan Google Mirror API, menggunakan jenis konten multipart/mixed. Dalam permintaan HTTP utama tersebut, setiap bagian berisi permintaan HTTP bertingkat.
Setiap bagian dimulai dengan header HTTP Content-Type: application/http-nya sendiri. Header tersebut juga dapat memiliki header Content-ID opsional. Namun, header bagian hanya ada untuk menandai awal bagian tersebut dan terpisah dari permintaan bertingkat. Setelah server membuka permintaan batch ke dalam permintaan terpisah, header bagian akan diabaikan.
Isi setiap bagian itu sendiri merupakan permintaan HTTP lengkap, dengan kata kerja, URL, header, dan isinya sendiri. Permintaan HTTP hanya boleh berisi bagian jalur URL; URL lengkap tidak diizinkan dalam permintaan batch.
Header HTTP untuk permintaan batch luar, kecuali untuk header Content- seperti Content-Type, berlaku untuk setiap permintaan dalam batch. Jika Anda menentukan header HTTP yang diberikan dalam permintaan luar dan panggilan individual, nilai header panggilan individual akan menggantikan nilai header permintaan batch luar. Header untuk setiap panggilan hanya berlaku untuk panggilan tersebut.
Misalnya, jika Anda memberikan header Otorisasi untuk panggilan tertentu, header tersebut hanya berlaku untuk panggilan tersebut. Jika Anda memberikan header Otorisasi untuk permintaan luar, header tersebut akan berlaku untuk semua panggilan individual kecuali panggilan tersebut menggantinya dengan header Otorisasinya sendiri.
Saat menerima permintaan batch, server akan menerapkan parameter kueri dan header permintaan luar (sebagaimana yang sesuai) untuk setiap bagian, lalu memperlakukan setiap bagian seolah-olah merupakan permintaan HTTP yang terpisah.
Respons terhadap permintaan batch
Respons server adalah respons HTTP standar tunggal dengan jenis konten multipart/mixed; setiap bagian adalah respons terhadap salah satu permintaan dalam permintaan batch, dalam urutan yang sama dengan permintaan tersebut.
Seperti bagian dalam permintaan, setiap bagian respons berisi respons HTTP lengkap, termasuk kode status, header, dan isi. Dan seperti bagian dalam permintaan, setiap bagian respons didahului oleh header Content-Type yang menandai awal bagian tersebut.
Jika bagian permintaan tertentu memiliki header Content-ID, bagian respons yang sesuai akan memiliki header Content-ID yang cocok, dengan nilai asli didahului string response-, seperti yang ditunjukkan dalam contoh berikut.
Catatan: Server dapat melakukan panggilan Anda dalam urutan apa pun. Jangan mengandalkan eksekusinya dalam urutan yang Anda tentukan untuknya. Jika ingin memastikan bahwa dua panggilan terjadi dalam urutan tertentu, Anda tidak dapat mengirimkannya dalam satu permintaan; sebagai gantinya, kirim panggilan pertama sendiri, lalu tunggu respons pertama setelah mengirimkan yang kedua.
Contoh
Contoh berikut menunjukkan penggunaan pengelompokan dengan Google Mirror API.
Contoh permintaan batch
POST /batch HTTP/1.1
Content-Length: content_length
content-type: multipart/mixed; boundary="===============7330845974216740156=="
accept-encoding: gzip, deflate
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_1
POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_1_token
accept: application/json
content-length: 24
{"text": "Hello there!"}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_2
POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_2_token
accept: application/json
content-length: 24
{"text": "Hello there!"}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_3
POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_3_token
accept: application/json
content-length: 24
{"text": "Hello there!"}
--===============7330845974216740156==--
Contoh respons batch
Ini adalah respons terhadap contoh permintaan di bagian sebelumnya.
HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Date: Tue, 22 Jan 2013 18:56:00 GMT
Expires: Tue, 22 Jan 2013 18:56:00 GMT
Cache-Control: private, max-age=0
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_1
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304
{
"kind": "glass#timelineItem",
"id": "1234567890",
"selfLink": "https://www.googleapis.com/mirror/v1/timeline/1234567890",
"created": "2012-09-25T23:28:43.192Z",
"updated": "2012-09-25T23:28:43.192Z",
"etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
"text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_2
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304
{
"kind": "glass#timelineItem",
"id": "0987654321",
"selfLink": "https://www.googleapis.com/mirror/v1/timeline/0987654321",
"created": "2012-09-25T23:28:43.192Z",
"updated": "2012-09-25T23:28:43.192Z",
"etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
"text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_3
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304
{
"kind": "glass#timelineItem",
"id": "5432109876",
"selfLink": "https://www.googleapis.com/mirror/v1/timeline/5432109876",
"created": "2012-09-25T23:28:43.192Z",
"updated": "2012-09-25T23:28:43.192Z",
"etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
"text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=--