Dokumen ini menjelaskan konsep penting tentang penggunaan Metadata API untuk mengakses daftar dan atribut kolom Google Analytics.
Pengantar
Metadata API menampilkan daftar kolom (yaitu, dimensi dan metrik) yang ditampilkan dalam Reporting API Google Analytics dan atributnya. Jika Anda baru mengenal API ini, baca Ringkasan Metadata API untuk mengetahui pengantar Metadata API.
Sebelum Memulai
Semua Google Analytics API diakses dengan cara yang sama. Sebelum mulai menggunakan Metadata API, Anda harus:
- Baca halaman library klien untuk melihat daftar lengkap library klien khusus bahasa pemrograman yang berfungsi dengan API.
- Baca Panduan Referensi untuk mempelajari antarmuka API dan mengakses data tanpa library klien.
Setiap library klien menyediakan satu objek layanan analisis untuk mengakses semua data Metadata API. Untuk membuat objek layanan yang akan digunakan dengan Metadata API, biasanya Anda harus melakukan langkah-langkah berikut:
- Daftarkan aplikasi Anda di Konsol API Google.
- Buat objek layanan Analytics dan tetapkan Kunci API.
Pendaftaran & Kunci API
Aplikasi Anda harus mengidentifikasi dirinya sendiri setiap kali mengirim permintaan ke Analytics API, dengan menyertakan kunci API bersama setiap permintaan.
Mendapatkan dan menggunakan kunci API
Untuk mendapatkan kunci API:
- Buka halaman Credentials di Konsol API.
-
API ini mendukung dua jenis kredensial.
Buat kredensial yang sesuai untuk project Anda:
-
OAuth 2.0: Setiap kali aplikasi Anda meminta data pengguna pribadi, aplikasi harus mengirimkan token OAuth 2.0 beserta permintaannya. Aplikasi Anda terlebih dahulu mengirim client ID dan, mungkin, rahasia klien untuk mendapatkan token. Anda dapat membuat kredensial OAuth 2.0 untuk aplikasi web, akun layanan, atau aplikasi terinstal.
Catatan: Karena API ini tidak memiliki metode apa pun yang memerlukan otorisasi OAuth 2.0, Anda mungkin hanya perlu mendapatkan kunci API, yang dijelaskan di bawah. Namun, jika aplikasi Anda memanggil API lain yang memerlukan otorisasi pengguna, Anda masih memerlukan kredensial OAuth 2.0.
Untuk informasi selengkapnya, lihat dokumentasi OAuth 2.0.
-
Kunci API: Permintaan yang tidak menyediakan token OAuth 2.0 harus mengirim kunci API. Kunci ini mengidentifikasi project Anda dan memberikan akses, kuota, serta laporan API.
API ini mendukung beberapa jenis pembatasan pada kunci API. Jika kunci API yang Anda perlukan belum ada, buat kunci API di Konsol dengan mengklik Create credentials > API key. Anda dapat membatasi kunci tersebut sebelum menggunakannya dalam produksi dengan mengklik Restrict key dan memilih salah satu Pembatasan.
-
Agar kunci API Anda tetap aman, ikuti praktik terbaik untuk menggunakan kunci API dengan aman.
Setelah Anda memiliki kunci API, aplikasi Anda dapat menambahkan parameter kueri key=yourAPIKey
ke semua URL permintaan.
Kunci API aman untuk disematkan dalam URL; tidak memerlukan encoding apa pun.
Cuplikan kode berikut mengilustrasikan cara menetapkan Kunci API untuk berbagai library klien:
Java
import com.google.api.client.json.jackson2.JacksonFactory; import com.google.api.client.http.javanet.NetHttpTransport; import com.google.api.services.analytics.Analytics; import com.google.api.services.analytics.AnalyticsRequestInitializer; public class ApiKeySample { private static final String API_KEY = "YOUR API KEY"; public static void main(String[] args) { NetHttpTransport netHttpTransport = new NetHttpTransport(); JacksonFactory jacksonFactory = new JacksonFactory(); // Set the API Key AnalyticsRequestInitializer analyticsInitializer = new AnalyticsRequestInitializer(API_KEY); // Build the Analytics Service object Analytics analytics = new Analytics.Builder(netHttpTransport, jacksonFactory, null) .setAnalyticsRequestInitializer(analyticsInitializer) .setApplicationName("ApiKeySample") .build(); // Start coding cool things. } }
Python
from apiclient.discovery import build API_KEY = 'YOUR API KEY' def main(argv): # Set the API Key and build the Analytics service object. service = build('analytics', 'v3', developerKey=API_KEY) # Start coding cool things.
PHP
require_once 'google-api-php-client/src/Google_Client.php'; require_once 'google-api-php-client/src/contrib/Google_AnalyticsService.php'; const API_KEY = 'YOUR API KEY' $client = new Google_Client(); // Set the API Key $client->setDeveloperKey($API_KEY); // Build the Analytics Service object. $analytics = new google_AnalyticsService($client); // Start coding cool things.
JavaScript
<!-- Method 1: Using the Google APIs Client Library for JavaScript --> <script> var apiKey = 'YOUR API KEY'; function handleClientLoad() { gapi.client.setApiKey(apiKey); gapi.client.load('analytics', 'v3', makeRequest); } function makeRequest() { // Start coding cool things. } </script> <script src="//apis.google.com/js/client.js?"></script> <!-- Method 2: Using REST and callback parameter --> <script> function render() { // Place your awesome code here. } </script> <!-- Replace RESOURCE with the path to the Google Analytics resource you're querying. --> <script src="https://www.googleapis.com/analytics/v3/RESOURCE/?key=YOUR_API_KEY&callback=render"></script>
Atribut Kolom
Respons Metadata API mencakup properti attributeNames
yang mencantumkan semua atribut kolom yang valid. Setiap kolom memiliki
properti attributes
yang menyertakan subset atribut yang
berlaku untuk kolom tersebut.
Tabel berikut adalah daftar lengkap atribut yang valid:
Kasus Penggunaan
Metadata API dapat digunakan untuk menyelesaikan kasus penggunaan berikut:
- Kolom yang Tidak Digunakan Lagi
- Nama Kolom
- Kolom dengan Templat
- Kolom Kalkulasi
- Kolom dan Segmen
- Versi API
- Etag
Kolom yang Tidak Digunakan Lagi
Jika sebuah kolom (yaitu dimensi atau metrik) tidak digunakan lagi, atribut
status
-nya akan ditetapkan ke DEPRECATED
.
Cuplikan berikut menunjukkan cara menggunakan atribut status
untuk memeriksa apakah sebuah kolom sudah tidak digunakan lagi:
function isDeprecated(column) { return column.attributes.status == 'DEPRECATED'; }
Jika kolom diganti namanya/dihapus, atribut status
-nya akan
ditetapkan ke DEPRECATED
dan dapat memiliki atribut replacedBy
yang ditetapkan ke Id
kolom pengganti.
Cuplikan berikut menunjukkan cara menggunakan atribut replacedBy
untuk mendapatkan ID kolom pengganti:
function getReplacementId(column) { return column.attributes.replacedBy; }
Nama Kolom
Atribut uiName
adalah nama dimensi atau metrik yang digunakan di antarmuka pengguna Google Analytics (misalnya, antarmuka web).
Cuplikan berikut menunjukkan cara mengambil nama UI kolom:
function getColumnName(column) { return column.attributes.uiName; }
Kolom Dengan Templat
Kolom bertemplate mencakup dimensi atau metrik dengan indeks numerik.
Misalnya, ga:goalXXStarts
, ga:dimensionXX
,
ga:metricXX
, dll. Kolom template akan memiliki atribut
minTemplateIndex
dan maxTemplateIndex
yang menentukan rentang indeks.
Cuplikan berikut menunjukkan cara memeriksa apakah kolom menggunakan template:
function isTemplatized(column) { return !!column.attributes.minTemplateIndex || !!column.attributes.maxTemplateIndex; }
Cuplikan berikut menunjukkan cara mengambil daftar ID yang valid untuk kolom template:
function getTemplatizedIdList(column) { var columnIdList = []; var columnId = column.id; if (isTemplatized(column)) { minIndex = parseInt(column.attributes.minTemplateIndex); maxIndex = parseInt(column.attributes.maxTemplateIndex); for (var i = minIndex; i <= maxIndex; i++) { columnIdList.push(columnId.replace('XX', i)); } } return columnIdList; }
Kolom Kalkulasi
Kolom yang berasal dari penghitungan kolom lain akan memiliki
atribut calculation
. Misalnya, penghitungan untuk ga:percentNewSessions
adalah ga:newSessions / ga:sessions
.
Contoh berikut menunjukkan cara memeriksa apakah kolom dihitung dan cara mengambil penghitungan untuk sebuah kolom:
function isCalculated(column) { return !!column.attributes.calculation; } function getCalculation(column) { return column.attributes.calculation; }
Kolom dan Segmen
Atribut allowedInSegments
memungkinkan Anda memeriksa apakah
kolom dapat digunakan dalam parameter kueri segmen.
Contoh berikut menunjukkan cara menentukan apakah kolom dapat digunakan dalam segmen:
function isAllowedInSegments(column) { return !!column.attributes.allowedInSegments; }
Ditambahkan di Versi API
Gunakan atribut addedInApiVersion
untuk memeriksa apakah kolom
dapat digunakan dalam Reporting API versi yang ditentukan. Misalnya, panggil fungsi berikut untuk memverifikasi bahwa kolom dapat digunakan dalam Core Reporting API V3:
function isAllowedInV3(column) { return column.attributes.addedInApiVersion < 4; }
ETag
ETag disertakan dalam setiap respons Metadata API. ETag adalah ID yang dapat digunakan untuk meng-cache dan memperbarui respons Metadata API. Hal ini penting karena data kolom (yaitu dimensi dan metrik) dapat tetap tidak berubah dalam jangka waktu yang lama, dan membuat permintaan serta pembaruan yang tidak perlu saat data yang di-cache dapat digunakan akan menjadi tidak efisien.
Jika Anda menyimpan ETag dari koleksi kolom, ETag dapat digunakan terutama dengan 2 cara: untuk memeriksa apakah respons Metadata API yang di-cache adalah yang terbaru, dan untuk menyertakannya sebagai bagian dari permintaan Metadata API.
Memeriksa Respons yang Di-Cache
Jika Anda membandingkan nilai ETag yang ditampilkan dari respons Metadata API dan nilai tersebut setara dengan ETag untuk resource yang di-cache, berarti versi yang di-cache adalah versi yang terbaru. Jika ETag tidak setara, update aplikasi Anda dan refresh cache dengan respons terbaru.
Jika Anda hanya ingin mengambil nilai ETag dari Metadata API, tetapkan parameter kueri fields
ke etag
saat membuat permintaan.
Lihat contohnya.
Menggunakan ETag dengan Permintaan API
Jika memiliki versi koleksi kolom yang di-cache, Anda dapat menyertakan nilai ETag-nya dalam permintaan Metadata API dengan menetapkan kolom header HTTP If-None-Match
. Metadata API akan memeriksa nilai ETag dan merespons dengan versi resource yang diperbarui serta status HTTP 200 OK
atau respons kosong dengan status 304 Not
Modified
jika versi yang di-cache Anda adalah versi terbaru.