Core Reporting API - Panduan Developer

Dokumen ini menjelaskan cara menggunakan Core Reporting API untuk mengakses Data Google Analytics.

Versi Google Analytics Reporting API sudah diupdate. Sebaiknya migrasikan kode Anda sekarang untuk memanfaatkan fitur utama API yang baru.

Pengantar

Core Reporting API menyediakan akses ke data tabel dalam laporan standar dan kustom Google Analytics. Untuk mengakses data, buat kueri yang menentukan: tampilan (profil), tanggal mulai dan akhir, serta dimensi dan metrik yang membentuk header kolom dalam tabel. Kueri ini dikirim ke Core Reporting API dan Core Reporting API menampilkan semua data dalam bentuk tabel.

Jika Anda baru mengenal API ini, baca Ringkasan Core Reporting API untuk mengetahui pengantar tentang Core Reporting API dan data yang disediakannya.

Sebelum Memulai

Panduan ini menunjukkan cara mengakses Google Analytics API menggunakan bahasa pemrograman Java, Python, PHP, dan JavaScript.

• Baca halaman library klien untuk melihat daftar lengkap library klien khusus bahasa pemrograman yang berfungsi dengan API.
• Baca Panduan Referensi untuk mengakses API tanpa library klien.

Setiap library klien menyediakan satu objek layanan analisis untuk mengakses semua data Core Reporting API. Untuk membuat objek layanan, Anda biasanya harus melalui langkah-langkah berikut:

1. Daftarkan aplikasi Anda di Konsol API Google.
2. Izinkan akses ke data Google Analytics.
3. Buat objek layanan Analytics.

Jika Anda belum menyelesaikan langkah-langkah ini, hentikan dan baca Tutorial Hello Google Analytics API. Tutorial ini akan memandu Anda melalui langkah-langkah awal untuk membuat aplikasi Google Analytics API. Setelah selesai, Anda akan dapat menggunakan panduan ini untuk melakukan tugas di dunia nyata.

Cuplikan kode berikut berisi variabel untuk menyimpan objek layanan yang diotorisasi.

Java

Analytics analytics = // Read Hello Analytics Tutorial for details.

Python

analytics = # Read Hello Analytics Tutorial for details.

PHP

$client = // Read Hello Analytics Tutorial for details.

// Return results as objects.
$client->setUseObjects(true);

$analytics = new apiAnalyticsService($client);

Library PHP akan menampilkan semua hasil API sebagai array terkait. Untuk menampilkan objek sebenarnya, Anda dapat memanggil metode useObject klien seperti yang ditunjukkan pada contoh di atas.

JavaScript

<script src="https://apis.google.com/js/client.js?onload=loadLib"</script>
<script>
function loadLib() {
  // Handle all the authorization work.
  // Read Hello Analytics Tutorial for details.
  gapi.client.load('analytics', 'v3', makeApiCall);
}
</script>

Tag skrip pertama memuat library JavaScript Google API. Setelah dimuat, loadLib dieksekusi untuk memuat class layanan analisis. Setelah selesai, objek gapi.client.analytics harus ada di DOM dan siap digunakan untuk mengkueri Core Reporting API.

Setelah membuat objek layanan analisis, Anda siap membuat permintaan ke Core Reporting API.

Catatan: Objek layanan analisis juga dapat digunakan untuk mengakses Management API.

Ringkasan

Aplikasi yang menggunakan Core Reporting API umumnya akan mengikuti 2 langkah:

• Mengkueri Core Reporting API
• Bekerja dengan hasil API

Mari kita lihat kedua langkah tersebut.

Mengkueri Core Reporting API

Membuat kueri Core Reporting API

Objek layanan analisis berisi metode untuk membuat kueri Core Reporting API.

Setiap kueri Core Reporting API berisi kumpulan parameter yang menentukan data yang akan ditampilkan.

Salah satu parameter kueri yang paling penting adalah parameter ids, atau ID tabel. Parameter ini menentukan dari mana tampilan (profil) Google Analytics diambil data. Nilai menggunakan format ga:xxx dengan xxx yang merupakan ID tampilan (profil).

Java

Get apiQuery = analytics.data().ga()
    .get(tableId,                  // Table Id.
        "2012-01-01",              // Start date.
        "2012-01-15",              // End date.
        "ga:sessions")               // Metrics.
    .setDimensions("ga:source,ga:keyword")
    .setSort("-ga:sessions,ga:source")
    .setFilters("ga:medium==organic")
    .setMaxResults(25);

Python

api_query = service.data().ga().get(
    ids=TABLE_ID,
    start_date='2012-01-01',
    end_date='2012-01-15',
    metrics='ga:sessions',
    dimensions='ga:source,ga:keyword',
    sort='-ga:sessions,ga:source',
    filters='ga:medium==organic',
    max_results='25')

PHP

private function queryCoreReportingApi() {
  $optParams = array(
      'dimensions' => 'ga:source,ga:keyword',
      'sort' => '-ga:sessions,ga:source',
      'filters' => 'ga:medium==organic',
      'max-results' => '25');

  return $service->data_ga->get(
      TABLE_ID,
      '2010-01-01',
      '2010-01-15',
      'ga:sessions',
      $optParams);
}

Dalam library ini, metode get tidak hanya membuat kueri Core Reporting API, tetapi juga menjalankan permintaan ke API.

JavaScript

function makeApiCall() {
  var apiQuery = gapi.client.analytics.data.ga.get({
    'ids': TABLE_ID,
    'start-date': '2010-01-01',
    'end-date': '2010-01-15',
    'metrics': 'ga:sessions',
    'dimensions': 'ga:source,ga:keyword',
    'sort': '-ga:sessions,ga:source',
    'filters': 'ga:medium==organic',
    'max-results': 25
  });
  // ...
}

Dalam contoh ini, fungsi makeApiCall dipanggil setelah library klien JavaScript dimuat. Di dalam fungsi, fungsi membuat kueri Google Analytics API baru dan menyimpan objek dalam variabel apiQuery.

Listingan lengkap dari semua parameter kueri dan fungsinya dapat ditemukan dalam panduan referensi Core Reporting API. Selain itu, parameter dimensi dan metrik memungkinkan Anda menentukan data apa yang akan diambil dari Google Analytics. Daftar lengkap dapat ditemukan di halaman referensi dimensi dan metrik.

Membuat permintaan data Core Reporting API

Setelah kueri ditentukan, Anda memanggilnya metode execute untuk mengirim kueri ke server Google Analytics.

Java

try {
  apiQuery.execute();
  // Success. Do something cool!

} catch (GoogleJsonResponseException e) {
  // Catch API specific errors.
  handleApiError(e);

} catch (IOException e) {
  // Catch general parsing network errors.
  e.printStackTrace();
}

Jika Anda memilih untuk mengakses respons API mentah, gunakan metode executeUnparsed():

HttpResponse response = apiQuery.executeUnparsed();

Python

try:
  results = get_api_query(service).execute()
  print_results(results)

except TypeError, error:
  # Handle errors in constructing a query.
  print ('There was an error in constructing your query : %s' % error)

except HttpError, error:
  # Handle API service errors.
  print ('There was an API error : %s : %s' %
         (error.resp.status, error._get_reason()))

PHP

  try {
    $results = queryCoreReportingApi();
    // Success. Do something cool!

  } catch (apiServiceException $e) {
    // Handle API service exceptions.
    $error = $e->getMessage();
  }

JavaScript

function makeApiCall() {
  // ...

  apiQuery.execute(handleCoreReportingResults);
}

function handleCoreReportingResults(results) {
  if (!results.error) {
    // Success. Do something cool!
  } else {
    alert('There was an error: ' + results.message);
  }
}

Contoh ini berasal dari langkah sebelumnya tempat kueri Core Reporting API dibuat. Pada langkah ini, kueri dieksekusi. Parameter ke metode execute adalah referensi ke fungsi callback yang akan dijalankan setelah data ditampilkan dari API.

Setelah API menampilkan hasil, fungsi callback akan dieksekusi dan data akan diteruskan dari API. Jika terjadi error, hasilnya akan berisi properti bernama error.

Dalam contoh ini, pemeriksaan dilakukan untuk melihat apakah error ada atau apakah API berhasil ditampilkan.

Jika kueri berhasil, API akan menampilkan data yang diminta. Jika terjadi error, API akan menampilkan kode status spesifik dan pesan yang menjelaskan error tersebut. Semua aplikasi harus dapat mendeteksi dan menangani error dengan benar.

Bekerja dengan hasil API

Jika kueri Core Reporting API berhasil, API akan ditampilkan dengan data pelaporan Analytics serta informasi terkait lainnya terkait data tersebut.

Data pelaporan Analytics

Data utama yang ditampilkan dari API ini dapat dianggap sebagai tabel dengan 2 jenis data utama:

• Header yang menjelaskan jenis nilai di setiap kolom
• Baris data dalam tabel

Data header kolom

Setiap respons API berisi kolom header kolom yang merepresentasikan informasi header tabel. Kolom ini merupakan daftar (atau array) objek yang masing-masingnya mendeskripsikan jenis data dalam kolom. Urutan kolom adalah kolom dimensi yang diikuti oleh kolom metrik dalam urutan yang sama seperti yang ditentukan dalam kueri asli.

Java

private void printColumnHeaders(GaData gaData) {
 System.out.println("Column Headers:");

 for (GaDataColumnHeaders header : gaData.getColumnHeaders()) {
   System.out.println("Column Name: " + header.getName());
   System.out.println("Column Type: " + header.getColumnType());
   System.out.println("Column Data Type: " + header.getDataType());
 }
}

Python

def print_column_headers():
  headers = results.get('columnHeaders')

  for header in headers:
    # Print Dimension or Metric name.
    print 'Column name = %s' % header.get('name'))
    print 'Column Type = %s' % header.get('columnType')
    print 'Column Data Type = %s' % header.get('dataType')

PHP

private function printColumnHeaders(&results) {
  $html = '';
  $headers = $results->getColumnHeaders();

  foreach ($headers as $header) {
    $html .= <<<HTML
Column Name = {$header->getName()}
Column Type = {$header->getColumnType()}
Column Data Type = {$header->getDataType()}
HTML;

  print $html;
}

JavaScript

function printColumnHeaders(results) {
  var output = [];

  for (var i = 0, header; header = results.columnHeaders[i]; ++i) {
    output.push(
        'Name        = ', header.name, '\n',
        'Column Type = ', header.columnType, '\n',
        'Data Type   = ', header.dataType, '\n'
    );
  }

  alert(output.join(''));
}

Data baris

Data utama yang ditampilkan dari API ditampilkan sebagai List string 2 dimensi. Daftar luar mewakili semua baris data. Setiap daftar dalam mewakili satu baris, dengan urutan sel dalam satu baris sama dengan kolom dalam objek header kolom yang dijelaskan di atas.

Karena data di setiap sel ditampilkan sebagai string, kolom DataType di setiap objek header kolom sangat berguna karena dapat digunakan untuk mengurai nilai string menjadi jenis yang sesuai. Lihat respons API metadata untuk semua jenis data yang memungkinkan.

Contoh berikut mencetak header dan baris tabel.

Java

private void printDataTable(GaData gaData) {
 if (gaData.getTotalResults() > 0) {
   System.out.println("Data Table:");

   // Print the column names.
   for (GaDataColumnHeaders header : gaData.getColumnHeaders()) {
     System.out.format("%-32s", header.getName() + '(' + header.getDataType() + ')');
   }
   System.out.println();

   // Print the rows of data.
   for (List<String> rowValues : gaData.getRows()) {
     for (String value : rowValues) {
       System.out.format("%-32s", value);
     }
     System.out.println();
   }
 } else {
   System.out.println("No Results Found");
 }

Python

def print_data_table(results):
  # Print headers.
  output = []
  for header in results.get('columnHeaders'):
    output.append('%30s' % header.get('name'))
  print ''.join(output)

  # Print rows.
  if results.get('rows', []):
    for row in results.get('rows'):
      output = []
      for cell in row:
        output.append('%30s' % cell)
      print ''.join(output)
  else:
    print 'No Results Found'

PHP

private function printDataTable(&$results) {
  if (count($results->getRows()) > 0) {
    $table .= '<table>';

    // Print headers.
    $table .= '<tr>';

    foreach ($results->getColumnHeaders() as $header) {
      $table .= '<th>' . $header->name . '</th>';
    }
    $table .= '</tr>';

    // Print table rows.
    foreach ($results->getRows() as $row) {
      $table .= '<tr>';
        foreach ($row as $cell) {
          $table .= '<td>'
                 . htmlspecialchars($cell, ENT_NOQUOTES)
                 . '</td>';
        }
      $table .= '</tr>';
    }
    $table .= '</table>';

  } else {
    $table .= '<p>No Results Found.</p>';
  }
  print $table;
}

JavaScript

function printRows(results) {
  output = [];

  if (results.rows && results.rows.length) {
    var table = ['<table>'];

    // Put headers in table.
    table.push('<tr>');
    for (var i = 0, header; header = results.columnHeaders[i]; ++i) {
      table.push('<th>', header.name, '</th>');
    }
    table.push('</tr>');

    // Put cells in table.
    for (var i = 0, row; row = results.rows[i]; ++i) {
      table.push('<tr><td>', row.join('</td><td>'), '</td></tr>');
    }
    table.push('</table>');

    output.push(table.join(''));
  } else {
    output.push('<p>No Results Found</p>');
  }

  alert(output.join(''));
}

Laporkan informasi

Bersama dengan data tabel utama, data yang ditampilkan dari API berisi beberapa informasi tingkat tinggi tentang respons. Anda dapat mencetaknya menggunakan:

Java

private void printResponseInfo(GaData gaData) {
  System.out.println("Contains Sampled Data: " + gaData.getContainsSampledData());
  System.out.println("Kind: " + gaData.getKind());
  System.out.println("ID:" + gaData.getId());
  System.out.println("Self link: " + gaData.getSelfLink());
}

Python

def print_response_info(results):
  print 'Contains Sampled Data = %s' % results.get('containsSampledData')
  print 'Kind                  = %s' % results.get('kind')
  print 'ID                    = %s' % results.get('id')
  print 'Self Link             = %s' % results.get('selfLink')

PHP

private function printReportInfo(&$results) {
  $html = <<<HTML
  <pre>
Contains Sampled Data = {$results->getContainsSampledData()}
Kind                  = {$results->getKind()}
ID                    = {$results->getId()}
Self Link             = {$results->getSelfLink()}
</pre>
HTML;

  print $html;
}

JavaScript

function printReportInfo(results) {
  var output = [];

  output.push(
      'Contains Sampled Data  = ', results.containsSampledData, '\n',
      'Kind                   = ', results.kind, '\n',
      'ID                     = ', results.id, '\n',
      'Self Link              = ', results.selfLink, '\n');

  alert(output.join(''));
}

Kolom containsSampledData penting karena mendeskripsikan apakah respons API telah diambil sampelnya. Pengambilan sampel dapat memengaruhi hasil data Anda dan alasan umum mengapa nilai yang ditampilkan dari API tidak sesuai dengan antarmuka web. Lihat panduan konsep Pengambilan sampel untuk mengetahui detail selengkapnya.

Melihat informasi (Profil)

Setiap respons berisi grup parameter yang menunjukkan Akun, Properti Web, dan Tampilan (Profil) tempat data ini berada.

Java

private void printProfileInfo(GaData gaData) {
  GaDataProfileInfo profileInfo = gaData.getProfileInfo();

  System.out.println("Account ID: " + profileInfo.getAccountId());
  System.out.println("Web Property ID: " + profileInfo.getWebPropertyId());
  System.out.println("Internal Web Property ID: " + profileInfo.getInternalWebPropertyId());
  System.out.println("View (Profile) ID: " + profileInfo.getProfileId());
  System.out.println("View (Profile) Name: " + profileInfo.getProfileName());
  System.out.println("Table ID: " + profileInfo.getTableId());
}

Python

def print_profile_info(result):

  info = results.get('profileInfo')
  print 'Account Id          = %s' % info.get('accountId')
  print 'Web Property Id     = %s' % info.get('webPropertyId')
  print 'Web Property Id     = %s' % info.get('internalWebPropertyId')
  print 'View (Profile) Id   = %s' % info.get('profileId')
  print 'Table Id            = %s' % info.get('tableId')
  print 'View (Profile) Name = %s' % info.get('profileName')

PHP

private function printProfileInformation(&$results) {
  $profileInfo = $results->getProfileInfo();

  $html = <<<HTML
<pre>
Account ID               = {$profileInfo->getAccountId()}
Web Property ID          = {$profileInfo->getWebPropertyId()}
Internal Web Property ID = {$profileInfo->getInternalWebPropertyId()}
Profile ID               = {$profileInfo->getProfileId()}
Table ID                 = {$profileInfo->getTableId()}
Profile Name             = {$profileInfo->getProfileName()}
</pre>
HTML;

  print $html;
}

JavaScript

function printProfileInfo(results) {
  var output = [];

  var info = results.profileInfo;
  output.push(

      'Account Id          = ', info.accountId, '\n',
      'Web Property Id     = ', info.webPropertyId, '\n',
      'View (Profile) Id   = ', info.profileId, '\n',
      'Table Id            = ', info.tableId, '\n',
      'View (Profile) Name = ', info.profileName);

  alert(output.join(''));
}

Masing-masing ID ini sesuai dengan berbagai entitas dalam hierarki Management API. Anda dapat menggunakan ID ini untuk membuat kueri Management API guna mendapatkan informasi konfigurasi tambahan tentang tampilan (profil). Misalnya, Anda dapat membuat kueri Pengumpulan Sasaran Pengelolaan API untuk melihat Sasaran mana yang aktif beserta nama sasaran yang dikonfigurasi.

Informasi kueri

Setiap respons Core Reporting API berisi objek yang berisi semua parameter value kueri yang digunakan untuk membuat respons.

Java

private void printQueryInfo(GaData gaData) {
  GaDataQuery query = gaData.getQuery();

  System.out.println("Ids: " + query.getIds());
  System.out.println("Start Date: " + query.getStartDate());
  System.out.println("End Date: " + query.getEndDate());
  System.out.println("Metrics: " + query.getMetrics()); // List
  System.out.println("Dimensions: " + query.getDimensions());
  System.out.println("Sort: " + query.getSort()); // List
  System.out.println("Segment: " + query.getSegment());
  System.out.println("Filters: " + query.getFilters());
  System.out.println("Start Index: " + query.getStartIndex());
  System.out.println("Max Results: " + query.getMaxResults());
}

Python

def print_query_info(results):
  query = results.get('query')
  for key, value in query.iteritems():
    print '%s = %s' % (key, value)

PHP

private function printQueryParameters(&$results) {
  $query = $results->getQuery();

  $html = '<pre>';
  foreach ($query as $paramName => $value) {
    $html .= "$paramName = $value\n";
  }
  $html .= '</pre>';

  print $html;
}

JavaScript

function printQuery(results) {
  output = [];

  for (var key in results.query) {
    output.push(key, ' = ', results.query[key], '\n');
  }

  alert(output.join(''));
}

Parameter metrics dan sort ditampilkan sebagai nilai dalam daftar, sedangkan parameter lainnya ditampilkan sebagai string.

Informasi penomoran halaman

Setiap permintaan Core Reporting API mungkin cocok dengan ratusan ribu baris data Google Analytics. Core Reporting API hanya akan menampilkan subset pada waktu tertentu, yang dapat disebut sebagai satu halaman data. Anda menggunakan kolom penomoran halaman untuk mengambil semua halaman data.

Java

private void printPaginationInfo(GaData gaData) {
  System.out.println("Items Per Page: " + gaData.getItemsPerPage());
  System.out.println("Total Results: " + gaData.getTotalResults());
  System.out.println("Previous Link: " + gaData.getPreviousLink());
  System.out.println("Next Link: " + gaData.getNextLink());
}

Python

def print_pagination_info(results):
  print 'Items per page = %s' % results.get('itemsPerPage')
  print 'Total Results  = %s' % results.get('totalResults')
  print 'Previous Link  = %s' % results.get('previousLink')
  print 'Next Link      = %s' % results.get('nextLink')

PHP

private function getPaginationInfo(&$results) {
  $html = <<<HTML
<pre>
Items per page = {$results->getItemsPerPage()}
Total results  = {$results->getTotalResults()}
Previous Link  = {$results->getPreviousLink()}
Next Link      = {$results->getNextLink()}
</pre>
HTML;

  print $html;
}

JavaScript

function printPaginationInfo(results) {
  var output = [];

  output.push(
      'Items Per Page = ', results.itemsPerPage, '\n',
      'Total Results  = ', results.totalResults, '\n',
      'Previous Link  = ', results.previousLink, '\n',
      'Next Link      = ', results.nextLink, '\n');

  alert(output.join(''));
}

Kolom totalResults menunjukkan jumlah total baris data yang cocok dengan kueri Anda di Google Analytics. Jumlah ini bisa lebih besar dari jumlah baris sebenarnya yang ditampilkan dalam satu halaman respons. Kolom itemsPerPage menunjukkan jumlah baris yang ditampilkan di halaman ini.

Parameter previousLink dan nextLink hanya ada jika ada halaman sebelumnya atau berikutnya. Periksa link ini untuk melihat apakah ada lebih banyak halaman data yang dapat diambil dari Core Reporting API.

Total untuk semua hasil

Seperti yang disebutkan di bagian informasi penomoran halaman di atas, kueri ke Core Reporting API dapat mencocokkan banyak baris data di Google Analytics, tetapi hanya menampilkan subkumpulan data. Nilai metrik total untuk semua baris yang cocok ditampilkan dalam objek totalsForAllResults. Data ini berguna untuk menghitung rata-rata.

Java

private void printTotalsForAllResults(GaData gaData) {
  Map totalsMap = gaData.getTotalsForAllResults();

  for (Map.Entry entry : totalsMap.entrySet()) {
    System.out.println(entry.getKey() + " : " + entry.getValue());
  }
}

Python

def print_totals_for_all_results(results):
  totals = results.get('totalsForAllResults')

  for metric_name, metric_total in totals.iteritems():
    print 'Metric Name  = %s' % metric_name
    print 'Metric Total = %s' % metric_total

PHP

private function printTotalsForAllResults(&$results) {
  $totals = $results->getTotalsForAllResults();

  foreach ($totals as $metricName => $metricTotal) {
    $html .= "Metric Name  = $metricName\n";
    $html .= "Metric Total = $metricTotal";
  }

  print $html;
}

JavaScript

function printTotalsForAllResults(results) {
  var output = [];

  var totals = results.totalsForAllResults;
  for (metricName in totals) {
    output.push(
        'Metric Name  = ', metricName, '\n',
        'Metric Total = ', totals[metricName], '\n');
  }

  alert(output.join(''));
}

Sampel yang Bekerja

Untuk melihat contoh lengkap yang berfungsi, lihat Contoh Core Reporting API di setiap direktori sampel library klien.

Java

Library klien Java Google API Sampel Core Reporting API

Python

Library klien Google API Python Sampel Core Reporting API

PHP

Library klien PHP Google API Sampel Core Reporting API

JavaScript

Library klien JavaScript Google API Sampel Core Reporting API

Sumber JavaScript