Core Reporting API - Panduan Developer

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

Pengantar

Core Reporting API memberikan akses ke data tabel di laporan standar dan kustom Google Analytics. Untuk mengakses data, Anda membuat 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 menggunakan API, baca Ringkasan Core Reporting API untuk mengetahui pengantar tujuan 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, biasanya Anda harus melakukan 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, berhentilah dan baca Tutorial Halo Google Analytics API. Tutorial ini akan memandu Anda melalui langkah-langkah awal pembuatan aplikasi Google Analytics API. Setelah selesai, Anda akan dapat menggunakan panduan ini untuk melakukan tugas-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 asosiatif. Untuk menampilkan objek sungguhan, Anda dapat memanggil metode useObject klien seperti yang ditunjukkan dalam 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 dijalankan untuk memuat class layanan analisis. Setelah selesai, objek gapi.client.analytics akan 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:

  • Membuat kueri Core Reporting API
  • Menggunakan hasil API

Mari kita lihat kedua langkah tersebut.

Membuat kueri 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 asal tampilan (profil) Google Analytics yang akan mengambil data. Nilainya dalam 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 mengeksekusi 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 dalamnya, fungsi ini membuat kueri Google Analytics API baru dan menyimpan objek dalam variabel apiQuery.

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

Membuat permintaan data Core Reporting API

Setelah kueri ditentukan, panggil 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 mengikuti dari langkah sebelumnya tempat kueri Core Reporting API dibuat. Pada langkah ini, kueri dieksekusi. Parameter untuk metode execute adalah referensi ke fungsi callback yang akan dijalankan setelah data ditampilkan dari API.

Setelah API ditampilkan dengan hasil, fungsi callback dijalankan dan data 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 tertentu dan pesan yang menjelaskan error tersebut. Semua aplikasi harus dapat menangkap dan menangani error dengan benar.

Menangani hasil API

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

Data pelaporan Analytics

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

  • {i>Header<i} yang menjelaskan jenis-jenis nilai di setiap kolom
  • Baris data dalam tabel

Data header kolom

Setiap respons API berisi kolom header kolom yang mewakili informasi header tabel. Kolom ini adalah daftar (atau array) objek dengan setiap objek menjelaskan jenis data di 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 bagian dalam mewakili satu baris, dengan urutan sel dalam baris sama dengan kolom di 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(''));
}

Informasi laporan

Bersama dengan data tabel utama, data yang ditampilkan dari API berisi beberapa informasi umum 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 menjelaskan apakah respons API telah diambil sampelnya. Pengambilan sampel dapat memengaruhi hasil data Anda dan alasan umum mengapa nilai yang ditampilkan dari API tidak cocok dengan antarmuka web. Lihat panduan konsep Pengambilan sampel untuk detail selengkapnya.

Melihat informasi (Profil)

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

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(''));
}

Setiap ID ini sesuai dengan berbagai entitas di hierarki Management API. Anda dapat menggunakan ID ini untuk membentuk kueri Management API guna mendapatkan informasi konfigurasi tambahan tentang tampilan (profil). Misalnya, Anda dapat mengkueri Pengumpulan Sasaran Management API untuk melihat Sasaran mana yang aktif bersama dengan 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

Permintaan Core Reporting API mungkin cocok dengan ratusan ribu baris data Google Analytics. Core Reporting API hanya akan menampilkan subkumpulan pada waktu tertentu, yang dapat disebut sebagai halaman data tunggal. Anda dapat 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 di satu halaman respons. Kolom itemsPerPage menunjukkan jumlah baris yang ditampilkan pada 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. Total nilai metrik 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 Kerja

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

Java

Library klien Java Google API Contoh Core Reporting API

Python

Library klien Python Google API Contoh Core Reporting API

PHP

Library klien PHP Google API Contoh Core Reporting API

JavaScript

Library klien JavaScript Google API Contoh Core Reporting API

Sumber JavaScript