Salah satu pendekatan khusus untuk pengelompokan, endpoint Batch HTTP Global
(www.googleapis.com/batch), dinonaktifkan pada 12 Agustus 2020, seperti yang diumumkan di blog Developer
Google. Pendekatan lain untuk pengelompokan masih berfungsi, seperti yang didokumentasikan di bagian lainnya pada halaman ini. Jika kode Anda menggunakan endpoint Batch HTTP Global, lihat postingan blog guna mengetahui petunjuk tentang
transisi untuk 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 membahas cara membuat permintaan batch dengan mengirimkan permintaan HTTP. Jika sebagai gantinya, Anda menggunakan library klien Google untuk membuat permintaan batch, lihat library klien.
Ringkasan
Setiap koneksi HTTP yang dibuat klien Anda menghasilkan jumlah overhead tertentu. Google Ad Experience Report API mendukung pengelompokan, untuk memungkinkan klien Anda melakukan beberapa panggilan API ke dalam satu permintaan HTTP.
Contoh situasi ketika Anda mungkin ingin menggunakan pengelompokan:
- Anda baru saja mulai menggunakan API dan Anda memiliki banyak data untuk diunggah.
- Seorang pengguna membuat perubahan pada data saat aplikasi Anda offline (terputus dari Internet), sehingga aplikasi Anda perlu menyinkronkan data lokalnya dengan server dengan mengirimkan banyak pembaruan dan penghapusan.
Dalam setiap kasus, daripada mengirim setiap panggilan secara terpisah, Anda dapat mengelompokkannya menjadi satu permintaan HTTP. Semua permintaan dalam harus dikirim ke Google API yang sama.
Anda dibatasi hingga 1000 panggilan dalam satu permintaan batch. Jika Anda perlu melakukan lebih banyak panggilan dari itu, gunakan beberapa permintaan batch.
Catatan: Sistem batch untuk Google Ad Experience Report API menggunakan sintaksis yang sama dengan sistem OData batch processing, 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 discovery API. Jalur defaultnya adalah /batch/api_name/api_version. Bagian ini menjelaskan sintaksis batch secara mendetail; nanti, ada contoh.
Catatan: Kumpulan permintaan n yang dikelompokkan bersama akan dihitung terhadap batas penggunaan Anda sebagai n permintaan, bukan sebagai satu permintaan. Permintaan batch dipisah menjadi sekumpulan permintaan sebelum diproses.
Format permintaan batch
Permintaan batch adalah permintaan HTTP standar tunggal yang berisi beberapa panggilan Google Ad Experience Report 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. Template ini juga dapat memiliki header Content-ID opsional. Namun, header bagian ada di sana untuk menandai awal bagian tersebut; header tersebut terpisah dari permintaan bertingkat. Setelah server membuka permintaan batch ke dalam permintaan yang terpisah, header bagian akan diabaikan.
Isi setiap bagian merupakan permintaan HTTP lengkap, dengan kata kerja, URL, header, dan isinya sendiri. Permintaan HTTP hanya boleh berisi bagian jalur dari URL; URL lengkap tidak diizinkan dalam permintaan batch.
Header HTTP untuk permintaan batch luar, kecuali header Content- seperti Content-Type, berlaku untuk setiap permintaan dalam batch. Jika Anda menentukan header HTTP tertentu dalam permintaan luar dan panggilan individual, nilai header panggilan individual akan menggantikan nilai header permintaan batch luar. Header untuk masing-masing panggilan hanya berlaku untuk panggilan tersebut.
Misalnya, jika Anda memberikan header Otorisasi untuk panggilan tertentu, header tersebut hanya akan berlaku untuk panggilan tersebut. Jika Anda memberikan header Otorisasi untuk permintaan luar, header tersebut akan berlaku untuk semua panggilan individual kecuali panggilan tersebut diganti dengan header Otorisasinya sendiri.
Saat server menerima permintaan batch, server menerapkan parameter kueri dan header permintaan luar (yang sesuai) untuk setiap bagian, kemudian memperlakukan setiap bagian seolah-olah merupakan permintaan HTTP terpisah.
Respons terhadap permintaan batch
Respons server adalah satu respons HTTP standar dengan jenis konten multipart/mixed; setiap bagian adalah respons terhadap salah satu permintaan dalam permintaan batch, dalam urutan yang sama seperti permintaan.
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, maka bagian respons yang sesuai akan memiliki header Content-ID yang cocok, dengan nilai asli diawali dengan string response-, seperti yang ditunjukkan dalam contoh berikut.
Catatan: Server dapat melakukan panggilan Anda dalam urutan apa pun. Jangan bergantung pada eksekusinya sesuai urutan yang Anda tentukan. Jika ingin memastikan bahwa dua panggilan terjadi dalam urutan tertentu, Anda tidak dapat mengirim keduanya dalam satu permintaan; sebagai gantinya, kirim panggilan pertama saja, lalu tunggu respons hingga yang pertama sebelum mengirimkan yang kedua.
Contoh
Contoh berikut menunjukkan penggunaan pengelompokan dengan Google Ad Experience Report API.
Contoh permintaan batch
POST /batch/v1?key=key HTTP/1.1 Content-Type: multipart/mixed; boundary=batch_aer --batch_aer Content-Type: application/http Content-ID: id1 GET /v1/sites/http%3A%2F%2F/site1%2F HTTP/1.1 --batch_aer Content-Type: application/http Content-ID: id2 GET /v1/sites/http%3A%2F%2F/site2%2F HTTP/1.1 --batch_aer--
Contoh respons batch
Ini adalah respons terhadap contoh permintaan di bagian sebelumnya.
HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_aer
--batch_aer
Content-Type: application/http
Content-ID: response-id1
HTTP/1.1 200 OK
Content-Type: application/json
{
"reviewedSite": "site1",
"mobileSummary": {
"lastChangeTime": "2019-02-05T09:46:26.521747Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site1/",
"filterStatus": "OFF"
},
"desktopSummary": {
"lastChangeTime": "2019-02-07T23:07:29.017206Z",
"betterAdsStatus": "FAILING",
"enforcementTime": "2018-02-15T15:00:00Z",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site1/",
"filterStatus": "ON"
}
}
--batch_aer
Content-Type: application/http
Content-ID: response-id2
HTTP/1.1 200 OK
Content-Type: application/json
{
"reviewedSite": "site2",
"mobileSummary": {
"lastChangeTime": "2018-03-06T16:06:33.375851Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site2/",
"filterStatus": "OFF"
},
"desktopSummary": {
"lastChangeTime": "2018-03-06T16:06:33.375851Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site2/",
"filterStatus": "OFF"
}
}
--batch_aer--