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

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

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

Catatan: Jika aplikasi Anda sudah diautentikasi dan memberi otorisasi kepada pengguna (misalnya, menggunakan OAuth 2.0), permintaan apa pun yang Anda buat ke Metadata API menggunakan objek layanan Analytics yang diotorisasi akan otomatis mengidentifikasi aplikasi Anda. Dalam hal ini, Anda tidak perlu menetapkan Kunci API.

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:

** 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 mengenai penghapusan atribut.

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.

Catatan: Aplikasi Anda harus memeriksa dan berhenti menggunakan kolom DEPRECATED dalam pelaporan kueri 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 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).

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 mengenai penghapusan atribut.

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.

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.