Bu belgede, Google Analytics Verilerine erişmek için Temel Raporlama API'sının nasıl kullanılacağı açıklanmaktadır.
Giriş
Core Reporting API, Google Analytics standart ve özel raporlarındaki tablo verilerine erişim sağlar. Verilere erişmek için görünüm (profil), başlangıç ve bitiş tarihlerinin yanı sıra tablodaki sütun başlıklarını oluşturan boyutlar ve metrikler belirten bir sorgu oluşturursunuz. Bu sorgu, Core Reporting API'ye gönderilir ve Core Reporting API tüm verileri tablo biçiminde döndürür.
API'yi kullanmaya yeni başladıysanız Temel Raporlama API'sinin amacı ve sağladığı veriler hakkında bilgi edinmek için Temel Raporlama API'sine Genel Bakış'ı okuyun.
Başlamadan Önce
Bu kılavuzda Java, Python, PHP ve JavaScript programlama dillerini kullanarak Google Analytics API'ye nasıl erişileceği gösterilmektedir.
- API ile çalışan programlama diline özgü istemci kitaplıklarının tam listesi için istemci kitaplıkları sayfasını okuyun.
- API'ye istemci kitaplığı olmadan erişmek için Referans Kılavuzu'nu okuyun.
Her istemci kitaplığı, tüm Core Reporting API verilerine erişmek için tek bir analiz hizmeti nesnesi sağlar. Hizmet nesnesini oluşturmak için genellikle aşağıdaki adımları uygulamanız gerekir:
- Uygulamanızı Google API Konsolu'na kaydedin.
- Google Analytics verilerine erişim yetkisi verin.
- Bir Analytics hizmet nesnesi oluşturun.
Bu adımları tamamlamadıysanız lütfen durup Merhaba Google Analytics API Eğiticisi'ni okuyun. Bu eğitim, Google Analytics API uygulaması oluşturmanın ilk adımlarında size yol gösterecektir. Tamamlandıktan sonra, gerçek dünyadaki görevleri gerçekleştirmek için bu kılavuzu kullanabilirsiniz.
Aşağıdaki kod snippet'i, yetkilendirilmiş bir hizmet nesnesini depolayacak bir değişken içeriyor.
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);
PHP kitaplığı, tüm API sonuçlarını ilişkilendirici bir dizi olarak döndürür. Bunun yerine gerçek nesneler döndürmek için yukarıdaki örnekte gösterildiği gibi istemci useObject yöntemini çağırabilirsiniz.
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>
İlk komut dosyası etiketi, Google API JavaScript kitaplığını yükler. Yüklendikten sonra, analiz hizmet sınıfını yüklemek için loadLib yürütülür.
İşlem tamamlandığında, gapi.client.analytics nesnesi DOM'da mevcut olmalı ve Core Reporting API'yi sorgulamak için kullanıma hazır olmalıdır.
Bir analiz hizmet nesnesi oluşturduktan sonra, Core Reporting API'ye istek göndermeye hazır olursunuz.
Not: Analiz hizmet nesnesi, Management API'ye erişmek için de kullanılabilir.
Genel bakış
Temel Raporlama API'sını kullanan bir uygulama genellikle 2 adımı izler:
- Core Reporting API'yi sorgulama
- API sonuçlarıyla çalışma
Her iki adıma da bakalım.
Core Reporting API'yi sorgulama
Core Reporting API sorgusu oluşturma
Analiz hizmet nesnesi, Core Reporting API sorgusu oluşturmaya yönelik bir yöntem içerir.
Her Core Reporting API sorgusu, hangi verilerin döndürüleceğini belirten bir parametre grubu içerir.En önemli sorgu parametrelerinden biri ids parametresi veya tablo kimliğidir. Bu parametre, verilerin hangi Google Analytics görünümünden (profilden) alınacağını belirtir. Değer ga:xxx biçimindedir; burada xxx, görünüm (profil) kimliğidir.
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);
}
Bu kitaplıkta, get yöntemi yalnızca Core Reporting API sorgusu oluşturmakla kalmaz, aynı zamanda isteği API'ye de yürütür.
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
});
// ...
}
Bu örnekte, makeApiCall işlevi JavaScript istemci kitaplığı yüklendikten sonra çağrılır. İşlev, içinde yeni bir Google Analytics API sorgusu oluşturur ve nesneyi apiQuery değişkeninde depolar.
Tüm sorgu parametrelerinin tam bir listesini ve ne yaptıklarını Temel Raporlama API'si başvuru kılavuzunda bulabilirsiniz. Ayrıca boyut ve metrik parametreleri, Google Analytics'ten hangi verilerin alınacağını belirtmenize olanak tanır. Tam listeyi boyutlar ve metrikler referans sayfasında bulabilirsiniz.
Core Reporting API veri isteğinde bulunma
Bir sorgu tanımlandıktan sonra, sorguyu Google Analytics sunucularına göndermek için execute yöntemini kullanırsınız.
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();
}
Bunun yerine ham API yanıtına erişmeyi tercih ederseniz executeUnparsed() yöntemini kullanın:
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);
}
}
Bu örnek, Core Reporting API sorgusunun oluşturulduğu önceki adımdan devam eder. Bu adımda sorgu yürütülür.
execute yönteminin parametresi, API'den veri döndürüldüğünde yürütülecek bir geri çağırma işlevine referanstır.
API sonuçlar döndürdüğünde, geri çağırma işlevi yürütülür ve API'den veriler aktarılır. Bir hata oluşursa sonuçlar error adlı bir özellik içerir.
Bu örnekte, error değerinin mevcut olup olmadığını veya API'nin başarıyla döndürülüp döndürülmediğini görmek için bir kontrol yapılmıştır.
Sorgu başarılı olduysa API, istenen verileri döndürür. Herhangi bir hata oluşursa API belirli bir durum kodu ve hatayı açıklayan bir mesaj döndürür. Tüm uygulamalar hataları düzgün bir şekilde yakalayıp işlemelidir.
API sonuçlarıyla çalışma
Core Reporting API sorgusu başarılıysa API, Analytics raporlama verilerinin yanı sıra verilerle ilgili diğer bilgileri de döndürür.
Analytics raporlama verileri
API'den döndürülen ana veriler, 2 ana veri türünü içeren bir tablo olarak düşünülebilir:
- Her bir sütundaki değerlerin türlerini açıklayan başlık
- Tablodaki veri satırları
Sütun başlığı verileri
Her API yanıtı, tablonun başlık bilgilerini temsil eden bir sütun başlığı alanı içerir. Alan, her nesnenin sütundaki veri türünü açıkladığı bir nesneler listesidir (veya bir dizidir). Sütun sıralaması, orijinal sorguda belirtilen sırayla boyut sütunları ve ardından metrik sütunlarıdır.
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(''));
}
Satır verileri
API'den döndürülen ana veriler, dizelerin 2 boyutlu List'si olarak döndürülür. En dıştaki liste tüm veri satırlarını temsil eder.
Her iç liste tek bir satırı temsil eder. Bu satırdaki hücrelerin sırası, yukarıda açıklanan sütun başlığı nesnesindeki alanlarla aynıdır.
Her bir hücredeki veriler dize olarak döndürüldüğünden, dize değerlerini uygun bir türe ayrıştırmak için kullanılabileceğinden, her bir sütun başlığı nesnesindeki DataType alanı özellikle yararlıdır. Tüm olası veri türleri için
Metadata API yanıtına bakın.
Aşağıdaki örneklerde tablonun hem başlıkları hem de satırları yazdırılır.
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(''));
}
Rapor bilgileri
Ana tablo verilerinin yanı sıra, API'den döndürülen veriler yanıt hakkında bazı üst düzey bilgiler içerir. Şunu kullanarak yazdırabilirsiniz:
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(''));
}
containsSampledData alanı, API yanıtının örneklenip örneklenmediğini açıkladığı için önemlidir.
Örnekleme, verilerinizin sonuçlarını etkileyebilir ve API'den döndürülen değerlerin web arayüzüyle eşleşmemesinin yaygın bir nedeni olabilir. Daha fazla ayrıntı için Örnekleme kavram kılavuzuna bakın.
(Profil) bilgilerini görüntüleyin
Her yanıt, bu verilerin ait olduğu Hesabı, Web Mülkü'nü ve Görünümü (Profil) belirten bir parametre grubu içerir.
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(''));
}
Bu kimliklerin her biri, Management API hiyerarşisindeki çeşitli varlıklara karşılık gelir. Görünüm (profil) hakkında ek yapılandırma bilgileri almak amacıyla Management API sorguları oluşturmak için bu kimlikleri kullanabilirsiniz. Örneğin, Management API Hedefleri Koleksiyonu'nu sorgulayarak hangi Hedeflerin etkin olduğunu ve yapılandırılmış hedef adlarını öğrenebilirsiniz.
Sorgu bilgileri
Her Core Reporting API yanıtı, yanıtı oluşturmak için kullanılan tüm sorgu parametresi değerlerini içeren bir nesne içerir.
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(''));
}
metrics ve sort parametreleri bir listede değer olarak döndürülürken diğer parametreler dize olarak döndürülür.
Sayfalara ayırma bilgileri
Herhangi bir Core Reporting API isteği, yüz binlerce Google Analytics veri satırıyla eşleşebilir. Temel Raporlama API'si, belirli bir zamanda yalnızca bir alt küme döndürür. Bu alt küme, tek bir veri sayfası olarak ifade edilebilir. Sayfalara ayırma alanlarını, tüm veri sayfalarını almak için kullanırsınız.
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(''));
}
totalResults alanı, sorgunuzun Google Analytics'te eşleştiği veri satırlarının toplam sayısını temsil eder. Bu sayı, yanıtın tek bir sayfasında döndürülen gerçek satır sayısından büyük olabilir.
itemsPerPage alanı, bu sayfada döndürülen satır sayısını temsil eder.
previousLink ve nextLink parametreleri yalnızca önceki veya sonraki bir sayfa varsa kullanılabilir. Core Reporting API'den daha fazla veri sayfası alınıp alınamayacağını görmek için bu bağlantıları kontrol edin.
Tüm sonuçlar için toplamlar
Yukarıdaki sayfalara ayırma bilgileri bölümünde bahsedildiği gibi, Core Reporting API'ye yapılan bir sorgu Google Analytics'teki çok sayıda veri satırıyla eşleşse de yalnızca bir veri alt kümesi döndürür.
Eşleşen tüm satırların toplam metrik değerleri, totalsForAllResults nesnesinde döndürülür.
Bu veriler, ortalamaların hesaplanmasında yararlıdır.
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(''));
}
Çalışma Örnekler
Çalışan örneklerin tamamını görmek için her istemci kitaplığının örnek dizinindeki Core Reporting API Örneği'ne göz atın.
Java
Google API Java istemci kitaplığı Core Reporting API Örneği
Python
Google API Python istemci kitaplığı Core Reporting API Örneği
PHP
Google API PHP istemci kitaplığı Core Reporting API Örneği
JavaScript
Google API JavaScript istemci kitaplığı Core Reporting API Örneği