Metadata API - Panduan Developer

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:

1. Daftarkan aplikasi Anda di Konsol API Google.
2. 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:

1. Buka halaman Credentials di Konsol API.
2. 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.

Catatan: Jika aplikasi Anda telah mengautentikasi dan memberikan otorisasi kepada pengguna (misalnya, menggunakan OAuth 2.0), setiap permintaan yang Anda buat ke Metadata API menggunakan objek layanan Analytics yang diberi otorisasi akan otomatis mengidentifikasi aplikasi Anda. Dalam hal ini, Anda tidak perlu menetapkan Kunci API.

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?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 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:

** Atribut appUiName tidak digunakan lagi. Anda harus menghapus kode apa pun yang menggunakan atribut appUiName dan hanya menggunakan atribut uiName. Tinjau Kebijakan Penghentian Layanan Data untuk mengetahui detail tentang penghapusan atribut.

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.

Catatan: Aplikasi Anda harus memeriksa dan berhenti menggunakan kolom DEPRECATED dalam kueri Reporting API. Jika kolom pengganti tersedia, kolom tersebut harus digunakan. DEPRECATED kolom akan dihapus dari Reporting and Metadata API setelah periode penghentian penggunaan berakhir, dan kueri untuk kolom tersebut akan menampilkan error.

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).

Atribut appUiName tidak digunakan lagi. Anda harus menghapus kode apa pun yang menggunakan atribut appUiName dan hanya menggunakan atribut uiName. Tinjau Kebijakan Penghentian Layanan Data untuk mengetahui detail tentang penghapusan atribut.

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.

Catatan: Library klien yang Anda gunakan untuk membuat permintaan Metadata API dapat mengenali dan menggunakan ETag atau memberikan dukungan untuk melakukannya. Anda harus meninjau dokumentasi library untuk mengonfirmasi apakah dukungan ETag tersedia.