本文档将说明如何使用 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。
每个客户端库均会提供一个可以访问所有 Core Reporting API 数据的分析服务对象。要创建服务对象,您通常需要完成以下步骤:
- 在 Google API 控制台中注册您的应用。
- 授予访问 Google Analytics(分析)数据的权限。
- 创建 Google 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 会返回 Google 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
的形式。外部列表表示所有数据行。
每个内部列表表示一行,其中一行中单元格的顺序与上述列标题对象中字段的顺序相同。
由于每个单元格中的数据都是以字符串的形式返回的,因此每个列标题对象中的 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 构建管理 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 示例