Mengelompokkan Permintaan Google Analytics API

Dokumen ini menunjukkan cara mengelompokkan panggilan API sekaligus untuk mengurangi jumlah koneksi HTTP yang harus dibuat oleh klien Anda.

Dokumen ini secara khusus membahas pembuatan permintaan batch dengan mengirim permintaan HTTP. Jika Anda menggunakan library klien Google untuk membuat permintaan batch, lihat dokumentasi library klien.

Ringkasan

Setiap koneksi HTTP yang dibuat klien Anda menghasilkan sejumlah {i>overhead<i} tertentu. Google Analytics API mendukung pengelompokan, sehingga klien Anda dapat menempatkan beberapa panggilan API ke dalam satu permintaan HTTP.

Contoh situasi saat Anda mungkin ingin menggunakan pengelompokan:

• Memperbarui Izin pengguna. Ada peningkatan performa dan insentif kuota tertentu yang Anda dapatkan saat membuat permintaan batch yang memperbarui izin pengguna. Lihat Panduan developer Izin Pengguna untuk mengetahui detailnya.
• Aplikasi pelaporan seluler Anda mungkin offline, dan Anda perlu membuat grup permintaan data saat aplikasi kembali online.
• Anda memiliki aplikasi akun layanan yang harus membuat beberapa laporan secara rutin.
• Anda perlu membuat kumpulan dimensi kustom atau metrik kustom, dan memilih untuk hanya membuat satu permintaan HTTP.

Dalam setiap kasus, daripada mengirim setiap panggilan secara terpisah, Anda dapat mengelompokkannya ke dalam satu permintaan HTTP. Semua permintaan internal harus mengarah ke Google API yang sama.

Anda dibatasi hingga 1.000 panggilan dalam satu permintaan batch. Jika Anda harus melakukan panggilan lebih dari itu, gunakan beberapa permintaan batch.

Catatan: Sistem batch untuk Google Analytics API menggunakan sintaksis yang sama dengan sistem pemrosesan batch OData, tetapi semantiknya berbeda.

Detail batch

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 default-nya adalah /batch/api_name/api_version. Bagian ini menjelaskan sintaksis batch secara mendetail; kemudian, akan muncul contoh.

Catatan: Kumpulan permintaan n yang dikelompokkan bersama-sama dihitung dalam batas penggunaan Anda sebagai permintaan n, bukan sebagai satu permintaan. Permintaan batch dipisahkan menjadi serangkaian permintaan sebelum diproses.

Format permintaan batch

Permintaan batch adalah permintaan HTTP standar tunggal yang berisi beberapa panggilan Google Analytics API, yang menggunakan jenis konten multipart/mixed. Dalam permintaan HTTP utama tersebut, masing-masing bagian berisi permintaan HTTP bertingkat.

Setiap bagian dimulai dengan header HTTP Content-Type: application/http-nya sendiri. Class ini juga dapat memiliki header Content-ID opsional. Namun, header bagian hanya ada untuk menandai awal bagian; terpisah dari permintaan bertingkat. Setelah server membuka permintaan batch menjadi permintaan terpisah, header bagian akan diabaikan.

Isi setiap bagian adalah permintaan HTTP lengkap, dengan kata kerja, URL, header, dan isi. 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 ke setiap permintaan dalam batch. Jika Anda menentukan header HTTP tertentu dalam permintaan outer dan panggilan individual, nilai header panggilan individual akan menggantikan nilai header permintaan batch luar. Header untuk setiap satu panggilan hanya berlaku untuk panggilan tersebut.

Misalnya, jika Anda memberikan header Otorisasi untuk suatu panggilan, 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 jika header tersebut menggantinya dengan header Otorisasi sendiri.

Saat menerima permintaan batch, server menerapkan parameter kueri dan header permintaan outer (yang sesuai) ke setiap bagian, lalu 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 batch permintaan, 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.

Jika bagian tertentu dari permintaan memiliki header Content-ID, maka bagian respons yang sesuai memiliki header Content-ID yang cocok, dengan nilai asli yang diawali dengan string response-, seperti yang ditunjukkan dalam contoh berikut singkat ini.

Catatan: Server dapat melakukan panggilan Anda dalam urutan apa pun. Jangan menganggap eksekusinya dilakukan sesuai urutan yang Anda tentukan. Jika Anda ingin memastikan bahwa dua panggilan terjadi dalam urutan tertentu, Anda tidak dapat mengirimkannya dalam satu permintaan; sebagai gantinya, kirim pesan pertama saja, lalu tunggu respons terhadap pesan pertama sebelum mengirim yang kedua.

Contoh

Contoh berikut menunjukkan penggunaan pengelompokan dengan Google Analytics API.

Contoh permintaan batch

POST /batch/analytics/v3 HTTP/1.1
Host: www.googleapis.com
Content-length: 731
Content-type: multipart/mixed; boundary=batch_0123456789
Authorization: Bearer ya29.5gFZooleNoSpGqYOOF0eFciUGz1x26k9GagZoW7HJCogWlCoNOotxlZPo7bDbwo1ykDq
--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 68


{
 "name": "Campaign Group",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 67


{
 "name": "Campaign Type",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789--

Contoh respons batch

Ini adalah respons terhadap contoh permintaan di bagian sebelumnya.

HTTP/1.1 200 OK
Content-length: 1876
X-xss-protection: 1; mode=block
X-content-type-options: nosniff
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Vary: Origin,X-Origin
Server: GSE
Cache-control: private, max-age=0
Date: Wed, 02 Sep 2015 21:36:35 GMT
X-frame-options: SAMEORIGIN
Content-type: multipart/mixed; boundary=batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/L-Y_3uM9BpST8Sea-SJDRQ7N7vE"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 548

{"kind":"analytics#customDimension","id":"ga:dimension18","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Group","index":18,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:34.143Z","updated":"2015-09-02T21:36:34.143Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension18","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/VN-21fLS1T0Qko3pHEB5fi8vYJ8"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 547

{"kind":"analytics#customDimension","id":"ga:dimension19","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Type","index":19,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:35.099Z","updated":"2015-09-02T21:36:35.099Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension19","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q--

Catatan: Anda tidak dapat menggunakan objek upload media dalam permintaan batch, misalnya Anda tidak dapat memanggil metode uploadData impor data dalam permintaan batch.

Library klien

Gunakan panduan library klien berikut untuk melihat cara menerapkan Pengelompokan dalam bahasa Anda:

• Python
• Java
• JavaScript
• PHP
• .NET

Pengelompokan dan kuota Google Analytics

Meskipun pengelompokan dapat menghemat biaya pembuatan banyak permintaan HTTP, setiap permintaan Google Analytics API dalam satu permintaan batch akan mengurangi kuota project harian Anda. Secara default,project dapat membuat hingga 50.000 permintaan per hari; batch tidak akan membantu Anda tetap di bawah kuota ini.

Kecuali untuk permintaan Izin Pengguna tulis (hapus, sisipkan, perbarui), semua batas kapasitas tetap berlaku. Misalnya, Core Reporting API dibatasi hingga 10 permintaan serentak per tampilan (profil); pengelompokan tidak akan membantu Anda tetap berada di bawah batas ini.

Batas 1,5 kueri per detik (QPS) per ID Akun berlaku untuk Permintaan Tulis Management API dan Permintaan Tulis API Penyediaan. Oleh karena itu, mengelompokkan permintaan tulis ini mungkin tidak meningkatkan performa.