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 diekspos di Reporting API Google Analytics dan atributnya. Jika Anda baru mengenal API ini, baca Ringkasan Metadata API untuk mengetahui pengantar tentang Metadata API.
Sebelum Memulai
Semua API Google Analytics diakses dengan cara yang sama. Sebelum memulai dengan 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, Anda biasanya harus melalui langkah-langkah berikut:
- Daftarkan aplikasi Anda di Konsol API Google.
- Buat objek layanan Analytics dan tetapkan Kunci API.
Pendaftaran & amp; Kunci API
Aplikasi Anda perlu mengidentifikasi dirinya sendiri setiap kali mengirim permintaan ke API Analytics, dengan menyertakan kunci API dengan 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 apa pun yang sesuai untuk project Anda:
-
OAuth 2.0: Setiap kali aplikasi meminta data pengguna pribadi, aplikasi harus mengirimkan token OAuth 2.0 beserta permintaannya. Aplikasi Anda mengirim client ID terlebih dahulu 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 yang memerlukan otorisasi OAuth 2.0, Anda mungkin hanya perlu mendapatkan kunci API, yang dijelaskan di bawah ini. 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 memberikan token OAuth 2.0 harus mengirim kunci API. Kunci tersebut mengidentifikasi project Anda dan memberikan akses, kuota, dan laporan API.
API ini mendukung beberapa jenis pembatasan pada kunci API. Jika kunci API yang Anda butuhkan belum ada, buat kunci API di Console dengan mengklik Create credentials > API key. Anda dapat membatasi kunci sebelum menggunakannya dalam produksi dengan mengklik Restrict key dan memilih salah satu Restrictions.
-
Untuk menjaga keamanan kunci API Anda, ikuti praktik terbaik untuk menggunakan kunci API secara 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.
Cuplikan kode berikut mengilustrasikan cara menyetel 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?onload=handleClientLoad"></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 menyertakan properti attributeNames
yang mencantumkan semua atribut kolom yang valid. Setiap kolom memiliki
properti attributes
yang menyertakan subkumpulan 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 Template
- Kolom kalkulasi
- Kolom dan Segmen
- Versi API
- Etag
Kolom yang Tidak Digunakan Lagi
Jika 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 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 atribut replacedBy
mungkin 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 dalam antarmuka pengguna Google Analytics (misalnya, antarmuka web).
Cuplikan berikut menunjukkan cara mengambil nama UI kolom:
function getColumnName(column) { return column.attributes.uiName; }
Kolom Template
Kolom ber-template mencakup dimensi atau metrik dengan indeks numerik.
Misalnya, ga:goalXXStarts
, ga:dimensionXX
, ga:metricXX
, dll. Kolom bertemplate akan memiliki atribut minTemplateIndex
dan maxTemplateIndex
yang menentukan rentang indeks.
Cuplikan berikut menunjukkan cara memeriksa apakah kolom tersebut diberi template:
function isTemplatized(column) { return !!column.attributes.minTemplateIndex || !!column.attributes.maxTemplateIndex; }
Cuplikan berikut menunjukkan cara mengambil daftar ID yang valid untuk kolom ber-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 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 di Reporting API dari versi yang ditentukan. Misalnya, panggil fungsi berikut untuk memverifikasi bahwa kolom dapat digunakan di 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 untuk jangka waktu yang lama dan tidak efisien untuk membuat permintaan dan pembaruan yang tidak perlu saat data yang di-cache dapat digunakan.
Jika Anda menyimpan ETag dari pengumpulan kolom, kolom ini terutama dapat digunakan dalam 2 cara: untuk memeriksa apakah respons Metadata API yang di-cache sudah terbaru dan menyertakannya sebagai bagian dari permintaan Metadata API.
Memeriksa Respons yang Disimpan dalam Cache
Jika Anda membandingkan nilai ETag yang ditampilkan dari respons Metadata API dengan nilai ETag yang setara untuk ETag yang di-cache, maka versi yang di-cache adalah versi saat ini. 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 contoh.
Menggunakan ETag dengan Permintaan API
Jika Anda 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 telah diupdate dan status HTTP 200 OK
atau respons kosong dengan status 304 Not
Modified
jika versi yang Anda simpan dalam cache adalah versi terbaru.