이 문서에서는 Core Reporting API를 사용하여 Google 애널리틱스 데이터에 액세스하는 방법을 설명합니다.
소개
Core Reporting API를 사용하면 Google 애널리틱스 표준 및 맞춤 보고서의 표 데이터에 액세스할 수 있습니다. 데이터에 액세스하려면 보기 (프로필), 시작일 및 종료일, 표의 열 헤더를 구성하는 측정기준과 측정항목을 지정하는 쿼리를 만듭니다. 이 쿼리는 Core Reporting API로 전송되고 Core Reporting API는 모든 데이터를 테이블 형식으로 반환합니다.
API를 처음 사용하는 경우 Core Reporting API 개요를 읽고 Core Reporting API의 목적과 이 API가 제공하는 데이터를 소개합니다.
시작하기 전에
이 가이드에서는 자바, Python, PHP, 자바스크립트 프로그래밍 언어를 사용하여 Google 애널리틱스 API에 액세스하는 방법을 설명합니다.
- API로 작동하는 프로그래밍 언어별 클라이언트 라이브러리의 전체 목록은 클라이언트 라이브러리 페이지를 참조하세요.
- 클라이언트 라이브러리 없이 API에 액세스하려면 참조 가이드를 참고하세요.
각 클라이언트 라이브러리는 모든 Core Reporting API 데이터에 액세스하기 위한 단일 분석 서비스 객체를 제공합니다. 서비스 객체를 만들려면 일반적으로 다음 단계를 따라야 합니다.
- Google API 콘솔에 애플리케이션을 등록합니다.
- Google 애널리틱스 데이터에 대한 액세스를 승인합니다.
- 애널리틱스 서비스 객체를 만듭니다.
이 단계를 완료하지 않았다면 중단하고 Hello Google Analytics API 튜토리얼을 읽어 보세요. 이 튜토리얼에서는 Google 애널리틱스 API 애플리케이션을 빌드하는 초기 단계를 안내합니다. 완료되면 이 가이드를 사용하여 실제 작업을 수행할 수 있습니다.
다음 코드 스니펫에는 승인된 서비스 객체를 저장하는 변수가 포함되어 있습니다.
Java
Analytics analytics = // Read Hello Analytics Tutorial for details.
Python
analytics = # Read Hello Analytics Tutorial for details.
2,399필리핀
$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를 사용하는 애플리케이션은 일반적으로 다음 두 단계를 따릅니다.
- Core Reporting API 쿼리
- API 결과 사용
두 단계를 모두 살펴보겠습니다.
Core Reporting API 쿼리
Core Reporting API 쿼리 빌드
분석 서비스 객체에는 Core Reporting API 쿼리를 빌드하는 메서드가 포함되어 있습니다.
각 Core Reporting API 쿼리에는 반환할 데이터를 지정하는 매개변수 집합이 포함됩니다.가장 중요한 쿼리 매개변수 중 하나는 ids 매개변수 또는 테이블 ID입니다. 이 매개변수는 데이터를 가져올
Google 애널리틱스 보기 (프로필)를 지정합니다. 값의 형식은 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')
2,399필리핀
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 애널리틱스 API 쿼리를 만들고 apiQuery 변수에 객체를 저장합니다.
모든 쿼리 매개변수와 각 매개변수에 관한 작업의 전체 목록은 Core Reporting API 참조 가이드에서 확인할 수 있습니다. 또한 측정기준 및 측정항목 매개변수를 사용하여 Google 애널리틱스에서 가져올 데이터를 지정할 수 있습니다. 전체 목록은 측정기준 및 측정항목 참조 페이지에서 확인할 수 있습니다.
Core Reporting API 데이터 요청하기
쿼리를 정의한 후 execute 메서드를 호출하여 쿼리를 Google 애널리틱스 서버로 전송합니다.
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()))
2,399필리핀
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가 애널리틱스 보고 데이터 및 데이터에 관한 기타 관련 정보를 반환합니다.
애널리틱스 보고 데이터
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')
2,399필리핀
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 필드는 문자열 값을 적절한 유형으로 파싱하는 데 사용할 수 있다는 점에서 특히 유용합니다. 가능한 모든 데이터 유형은
메타데이터 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'
2,399필리핀
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')
2,399필리핀
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')
2,399필리핀
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)
2,399필리핀
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 애널리틱스 데이터와 일치할 수 있습니다. 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')
2,399필리핀
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 애널리틱스에서 쿼리가 일치한 데이터의 총 행 수를 나타냅니다. 이는 응답의 한 페이지에 반환되는 실제 행 수보다 클 수 있습니다.
itemsPerPage 필드는 이 페이지에서 반환되는 행 수를 나타냅니다.
previousLink 및 nextLink 매개변수는 이전 또는 다음 페이지가 있는 경우에만 존재합니다. Core Reporting API에서 데이터 페이지를 더 가져올 수 있는지 확인하려면 다음 링크를 확인하세요.
모든 결과의 총계
위의 페이지로 나누기 정보 섹션에서 설명한 대로 Core Reporting API에 대한 쿼리는 Google 애널리틱스의 여러 데이터 행과 일치할 수 있지만 데이터의 하위 집합만 반환합니다.
일치하는 모든 행의 총 측정항목 값은 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
2,399필리핀
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 자바 클라이언트 라이브러리 Core Reporting API 샘플
Python
Google API Python 클라이언트 라이브러리 Core Reporting API 샘플
2,399필리핀
Google API PHP 클라이언트 라이브러리 Core Reporting API 샘플
JavaScript
Google API 자바스크립트 클라이언트 라이브러리 Core Reporting API 샘플