Management API - Otorisasi

Panduan ini menjelaskan cara aplikasi mengizinkan permintaan ke Management API.

Mengizinkan Permintaan

Sebelum dapat melihat informasi akun di situs Google Analytics, pengguna harus login ke Akun Google terlebih dahulu. Demikian pula, saat pengguna pertama kali mengakses aplikasi Anda, mereka perlu mengizinkan aplikasi Anda untuk mengakses data mereka.

Setiap permintaan yang dikirimkan aplikasi Anda ke Analytics API harus menyertakan token otorisasi. Token ini juga mengidentifikasi aplikasi Anda ke Google.

Tentang protokol otorisasi

Aplikasi Anda harus menggunakan OAuth 2.0 untuk mengizinkan permintaan. Tidak ada protokol otorisasi lain yang didukung. Jika aplikasi Anda menggunakan Login dengan Google, beberapa aspek otorisasi akan ditangani untuk Anda.

Mengizinkan permintaan dengan OAuth 2.0

Semua permintaan ke Analytics API harus diizinkan oleh pengguna yang diautentikasi.

Detail proses otorisasi, atau "alur", untuk OAuth 2.0 bervariasi bergantung pada jenis aplikasi yang Anda tulis. Proses umum berikut berlaku untuk semua jenis aplikasi:

  1. Saat membuat aplikasi, Anda mendaftarkannya menggunakan Konsol Google API. Selanjutnya, Google menyediakan informasi yang akan Anda perlukan nanti, seperti ID klien dan rahasia klien.
  2. Aktifkan Analytics API di Konsol API Google. (Jika API tidak tercantum di Konsol API, lewati langkah ini.)
  3. Saat memerlukan akses ke data pengguna, aplikasi Anda akan meminta cakupan akses tertentu kepada Google.
  4. Google menampilkan layar izin kepada pengguna, yang meminta mereka mengizinkan aplikasi Anda untuk meminta beberapa data.
  5. Jika pengguna menyetujui, Google akan memberikan token akses berumur singkat ke aplikasi Anda.
  6. Aplikasi Anda meminta data pengguna, dengan menambahkan token akses ke permintaan.
  7. Jika Google menentukan bahwa permintaan Anda dan token tersebut valid, data yang diminta akan ditampilkan.

Beberapa alur mencakup langkah tambahan, seperti penggunaan token refresh untuk memperoleh token akses baru. Informasi selengkapnya tentang alur untuk berbagai jenis aplikasi dapat dilihat di dokumentasi OAuth 2.0 Google.

Berikut adalah informasi cakupan OAuth 2.0 untuk Analytics API:

Cakupan Arti
https://www.googleapis.com/auth/analytics.readonly Akses hanya baca ke Analytics API.
https://www.googleapis.com/auth/analytics.edit Mengedit entitas pengelolaan Google Analytics.
https://www.googleapis.com/auth/analytics.manage.users Melihat dan mengelola izin pengguna untuk akun Analytics.
https://www.googleapis.com/auth/analytics.manage.users.readonly Lihat izin pengguna Google Analytics.

Untuk meminta akses menggunakan OAuth 2.0, aplikasi Anda memerlukan informasi cakupan, serta informasi yang disediakan oleh Google saat Anda mendaftarkan aplikasi (seperti ID klien dan rahasia klien).

Tips: Library klien Google API dapat menangani beberapa proses otorisasi secara otomatis. Library klien ini tersedia untuk berbagai bahasa pemrograman. Periksa halaman yang menjelaskan library beserta contohnya untuk mendapatkan informasi lebih mendetail.

Alur Umum OAuth 2.0

Berikut ini daftar kasus penggunaan umum untuk alur OAuth 2.0 tertentu:

Server Web

Alur ini cocok untuk akses otomatis, offline, atau terjadwal ke data Google Analytics pengguna.

Contoh:

  • Memperbarui dasbor pengguna secara otomatis dengan data Google Analytics terbaru.

Sisi klien

Alur ini ideal untuk aplikasi saat pengguna berinteraksi langsung dengan aplikasi untuk mengakses data Google Analytics mereka dalam browser. Solusi ini menghilangkan kebutuhan akan kemampuan sisi server, tetapi membuat pelaporan otomatis, offline, atau terjadwal menjadi tidak praktis.

Contoh:

Aplikasi Terinstal

Alur ini ditujukan untuk aplikasi yang didistribusikan sebagai paket dan diinstal oleh pengguna. Alur ini mengharuskan aplikasi atau pengguna memiliki akses ke browser untuk menyelesaikan alur autentikasi.

Contoh:

  • Widget desktop di PC atau Mac.
  • Plugin untuk sistem pengelolaan konten — Manfaat alur ini dibandingkan dengan server web atau sisi klien adalah bahwa satu project Konsol API dapat digunakan untuk aplikasi Anda. Hal ini memungkinkan pelaporan gabungan dan penginstalan yang lebih sederhana bagi pengguna.

Akun Layanan

Akun layanan berguna untuk akses otomatis, offline, atau terjadwal ke data Google Analytics untuk akun Anda sendiri. Misalnya, untuk membuat dasbor langsung dari data Google Analytics Anda sendiri dan membagikannya dengan pengguna lain.

Untuk mulai menggunakan Analytics API, Anda harus menggunakan alat penyiapan terlebih dahulu, yang memandu Anda menyelesaikan pembuatan project di Konsol API Google, mengaktifkan API, dan membuat kredensial.

Untuk menyiapkan akun layanan baru, lakukan hal berikut:

  1. Klik Create credentials > Service account key.
  2. Pilih apakah akan mendownload kunci publik/pribadi akun layanan sebagai file P12 standar, atau sebagai file JSON yang dapat dimuat oleh library klien Google API.

Pasangan kunci umum/pribadi baru Anda dibuat atau didownload ke komputer Anda, dan berfungsi sebagai satu-satunya salinan untuk kunci ini. Anda bertanggung jawab untuk menyimpannya dengan aman.

Pemecahan masalah

Otorisasi Anda gagal dalam situasi berikut:

  • Anda akan mendapatkan kode status 401 jika masa berlaku access_token telah berakhir atau jika Anda menggunakan cakupan yang salah untuk API.

  • Anda akan mendapatkan kode status 403 jika pengguna yang diberi otorisasi tidak memiliki akses ke tampilan (profil). Pastikan Anda diberi otorisasi oleh pengguna yang benar dan bahwa mereka memang memiliki tampilan (profil) yang Anda pilih.

Playground OAuth 2.0

Alat ini memungkinkan Anda menjalani seluruh alur otorisasi melalui antarmuka web. Alat ini juga menampilkan semua header permintaan HTTP yang diperlukan untuk membuat kueri yang diotorisasi. Jika Anda tidak mendapatkan otorisasi untuk berfungsi di aplikasi Anda sendiri, Anda harus mencoba membuatnya berfungsi melalui playground OAuth 2.0. Kemudian, Anda dapat membandingkan header HTTP dan permintaan dari playground dengan yang dikirim aplikasi Anda ke Google Analytics. Pemeriksaan ini merupakan cara sederhana untuk memastikan Anda memformat permintaan dengan benar.

Pemberian tidak valid

Saat Anda mencoba menggunakan token refresh, hal berikut akan menampilkan error invalid_grant:

Aplikasi dapat meminta beberapa token refresh untuk mengakses satu akun Google Analytics.

Misalnya, jika pengguna ingin menginstal aplikasi pada beberapa komputer dan mengakses akun Google Analytics yang sama, token terpisah akan diperlukan untuk setiap komputer. Jika jumlah token refresh melebihi batas, token yang lebih lama akan menjadi tidak valid. Jika aplikasi mencoba menggunakan token refresh yang tidak valid, respons error invalid_grant akan ditampilkan.

Batas untuk setiap pasangan unik klien OAuth 2.0 dan akun Google Analytics adalah 25 token refresh. Jika aplikasi terus meminta token refresh untuk pasangan Klien/Akun yang sama, setelah token ke-26 dikeluarkan, token refresh pertama yang sebelumnya dikeluarkan akan menjadi tidak valid. Token refresh yang diminta ke-27 akan membatalkan token ke-2 yang dikeluarkan sebelumnya dan seterusnya.