本文档将说明如何使用 Core Reporting API 访问 Google Analytics(分析)数据。
简介
Core Reporting API 可以访问 Google Analytics(分析)标准报告和自定义报告中的表格数据。要访问数据,您需要创建指定以下内容的查询:数据视图(配置文件)、开始日期和结束日期、构成表格列标题的维度和指标。此查询将会发送到 Core Reporting API,然后 Core Reporting API 会以表格形式返回所有数据。
如果这是您首次使用该 API,请参阅 Core Reporting API 概览,查看 Core Reporting API 的用途及其提供的数据。
开始之前
本指南将说明如何使用 Java、Python、PHP 以及 JavaScript 等编程语言访问 Google Analytics(分析)API。
每个客户端库提供单个 Analytics 服务对象来访问所有的 Core Reporting API 数据。要创建服务对象,您通常需要完成以下步骤:
- 在 Google API 控制台中注册您的应用。
- 授予访问 Google Analytics(分析)数据的权限。
- 创建一个 Analytics 服务对象。
如果您未能完成上述步骤,请停止操作,并阅读了解 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 发出请求了。
注意:该分析服务对象也可用于访问管理 API。
概览
使用 Core Reporting API 的应用一般会遵循以下两个步骤:
- 查询 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 报表数据以及与数据相关的其他信息。
Google Analytics(分析)报告数据
您可以将 API 返回的主数据视为包含两大类数据的表格:
- 说明每列值类型的标题
- 表格中的数据行
列标题数据
每个 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 返回的主数据采用二维字符串 List
的形式。外部 list 表示所有数据行。每个内部 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 均与管理 API 层次结构中的不同实体相对应。您可以使用这些 ID 创建管理 API 查询,获取与该数据视图(配置文件)有关的更多配置信息。例如,您可以查询管理 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) { MaptotalsMap = 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 示例