本文說明如何使用 Core Reporting API 存取 Google Analytics (分析) 資料。
簡介
Core Reporting API 可讓您存取 Google Analytics (分析) 標準和自訂報表中的表格資料。如要存取資料，您可以建立查詢指定下列項目：資料檢視 (設定檔)、開始與結束日期，以及構成資料表中欄標題的維度和指標。這項查詢會傳送至 Core Reporting API，而 Core Reporting API 會以表格的形式傳回所有資料。
如果您是第一次使用 API，請參閱 Core Reporting API 總覽，瞭解 Core Reporting API 的用途及該 API 提供的資料。
事前準備
本指南說明如何使用 Java、Python、PHP 和 JavaScript 程式設計語言存取 Google Analytics (分析) API。
每個用戶端程式庫都提供單一數據分析服務物件，方便您存取所有 Core Reporting API 資料。一般來說，您必須完成下列步驟，才能建立服務物件：
- 在 Google API 控制台中註冊應用程式。
- 授權存取 Google Analytics (分析) 資料。
- 建立 Analytics (分析) 服務物件。
如果您尚未完成這些步驟，請停止並參閱 Hello Google Analytics API 教學課程。本教學課程將逐步引導您建構 Google Analytics (分析) API 應用程式的初始步驟。完成後，您就能使用這份指南執行實際工作。
下列程式碼片段包含用於儲存授權服務物件的變數。
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 程式庫會以關聯陣列傳回所有 API 結果。如要傳回真實的物件，可以呼叫用戶端的 useObject 方法，如上方範例所示。
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>
第一個指令碼標記會載入 Google API JavaScript 程式庫。載入後，系統會執行 loadLib 以載入數據分析服務類別。完成後，物件 gapi.client.analytics 應存在於 DOM 中，並可用於查詢 Core Reporting API。
建立數據分析服務物件後，您就可以向 Core Reporting API 發出要求。
注意：數據分析服務物件也可用於存取 Management API。
總覽
使用 Core Reporting API 的應用程式通常只要按照 2 個步驟進行：
- 查詢 Core Reporting API
- 使用 API 結果
以下說明這兩個步驟。
查詢 Core Reporting API
建立 Core Reporting API 查詢
數據分析服務物件包含建立 Core Reporting API 查詢的方法。
每個 Core Reporting API 查詢都包含一組參數，用於指定要傳回的資料。其中一個最重要的查詢參數是 ids 參數，或是資料表 ID。這個參數會指定要從哪個 Google Analytics (分析) 資料檢視 (設定檔) 擷取資料。這個值會採用 ga:xxx 格式，其中 xxx 是資料檢視 (設定檔) ID。
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);
}
在這個程式庫中，get 方法不僅會建立 Core Reporting API 查詢，還會執行傳送至 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
});
// ...
}
在本範例中，系統會在載入 JavaScript 用戶端程式庫後呼叫 makeApiCall 函式。在當中，函式會建立新的 Google Analytics (分析) API 查詢，並將物件儲存在 apiQuery 變數中。
如需所有查詢參數及其功能的完整清單，請參閱 Core Reporting API 參考指南。此外， 您還可以使用維度和指標參數，指定要從 Google Analytics (分析) 擷取的資料。完整清單請見「 維度和指標」參考資料頁面。
提出 Core Reporting API 資料要求
定義查詢後，請呼叫該查詢的 execute 方法，將查詢傳送至 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();
}
如果您想改為存取原始 API 回應，請使用 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);
}
}
這個範例延續先前步驟，也就是建立 Core Reporting API 查詢的步驟。在這個步驟中，會執行查詢。
execute 方法的參數是回呼函式的參照，該函式會在 API 傳回資料後執行。
API 傳回結果後，系統會執行回呼函式，並從 API 傳遞資料。如果發生錯誤，結果會包含名為 error 的屬性。
在這個範例中，系統會檢查 error 是否存在，或 API 是否成功傳回。
如果查詢成功，API 會傳回要求的資料。如果發生任何錯誤，API 會傳回特定狀態碼和說明該錯誤的訊息。所有應用程式都應該正確擷取並處理錯誤。
使用 API 結果
如果 Core Reporting API 查詢成功，API 會傳回 Analytics (分析) 報表資料和其他相關資訊。
Analytics (分析) 報表資料
API 傳回的主要資料可視為包含 2 種主要資料類型的資料表：
- 此標頭說明每個資料欄中的值類型
- 資料表中的資料列
欄標題資料
每個 API 回應都包含一個代表資料表標頭資訊的欄標題欄位。欄位是物件清單 (或陣列)，每個物件都會說明資料欄中的資料類型。資料欄順序是維度欄，其後接指標欄的順序與原始查詢中指定的順序相同。
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(''));
}
資料列資料
API 傳回的主要資料會以 2 維的字串 List 傳回。外部清單代表所有資料列。每個內部清單都代表單一資料列，資料列中的儲存格順序與上述欄標題物件中的欄位順序相同。
由於每個儲存格中的資料都是以字串的形式傳回，因此每個資料欄標頭物件中的 DataType 欄位可用來將字串值剖析為合適的類型，因此格外有用。如需所有可能的資料類型，請參閱
Metadata API 回應。
以下範例會列印表格的標題和列。
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(''));
}
報表資訊
除了主要資料表資料外，API 傳回的資料還包含一些有關回應的高階資訊。你可以使用以下方式列印：
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 欄位非常重要，因為這個欄位會說明是否已取樣 API 回應。取樣會影響資料結果，以及 API 傳回值與網頁介面不符的常見原因。詳情請參閱取樣概念指南。
查看 (個人資料) 資訊
每則回應都包含一組參數，用來指出這項資料所屬的帳戶、網站資源和資料檢視 (設定檔)。
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(''));
}
每個 ID 都會對應到 Management API 階層中的不同實體。 您可以使用這些 ID 建立 Management API 查詢，取得有關資料檢視 (設定檔) 的其他設定資訊。舉例來說，您可以查詢 Management API 目標集合，瞭解哪些目標有效，以及其設定的目標名稱。
查詢資訊
每個 Core Reporting API 回應都包含一個物件，其中包含用於建立回應的所有查詢參數值。
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 和 sort 參數會以清單中的值傳回，其他參數則會以字串的形式傳回。
分頁資訊
任何 Core Reporting API 要求都可能會比對數十萬列的 Google Analytics (分析) 資料。Core Reporting API 會在指定時間內傳回子集，這稱為單一頁面的資料。您可以使用分頁欄位擷取所有頁面的資料。
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」欄位代表在 Google Analytics (分析) 中符合查詢條件的資料列總數。這個值可能會大於回應中單一頁面傳回的實際資料列數量。itemsPerPage 欄位代表這個頁面中傳回的資料列數量。
只有在有上一頁或下一頁時，才會出現 previousLink 和 nextLink 參數。請查看這些連結，確認是否可透過 Core Reporting API 擷取更多資料頁面。
所有結果的總計
如上方分頁資訊一節所述，對 Core Reporting API 的查詢可以比對 Google Analytics (分析) 中的多列資料，但只會傳回一部分的資料。所有相符資料列的總指標值都會在 totalsForAllResults 物件中傳回。
這類資料適合用來計算平均值。
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(''));
}
實際範例
如要查看完整有效範例，請參閱每個用戶端程式庫範例目錄中的 Core Reporting API 範例。
Java
Google API Java 用戶端程式庫 Core Reporting API 範例
Python
Google API Python 用戶端程式庫 Core Reporting API 範例
PHP
Google API PHP 用戶端程式庫 Core Reporting API 範例
JavaScript
Google API JavaScript 用戶端程式庫 Core Reporting API 範例