Nick Mihailovski, Google 애널리틱스 API팀 – 2012년 8월
이 가이드에서는 Apps Script를 사용하여 Google 스프레드시트 내에서 Management 및 Core Reporting API에 액세스하는 방법을 설명합니다.
소개
Google Analytics API 및 Google Apps Script를 사용하면 Google Sheets에서 Google 애널리틱스 데이터에 액세스할 수 있습니다. 이 기능은 간편한 공유, 공동작업, 차트 작성, 시각화 도구와 같은 Google 스프레드시트의 뛰어난 기능을 분석 데이터와 함께 모두 활용할 수 있다는 점에서 매우 유용합니다.
이 튜토리얼에서는 Google Apps Script를 사용하여 Google Sheets에서 Google 애널리틱스 데이터에 액세스하는 데 필요한 코드를 설명합니다.
개요
이 가이드에서는 Google 애널리틱스 API를 사용하도록 Apps Script 환경을 등록하고 구성하는 방법을 보여줍니다. 구성이 완료되면 튜토리얼에서는 Management API를 사용하여 승인된 사용자의 보기 (프로필) ID를 검색하는 방법을 안내합니다. 그런 다음 보기 (프로필) ID를 사용하여 Core Reporting API에 쿼리하여 Google에서 상위 250개 모바일 검색 키워드를 검색하는 방법 마지막으로 결과가 Google 스프레드시트에 삽입됩니다. 데이터가 확보되면 이 가이드에서는 데이터 검색을 자동화하는 방법도 설명합니다.
Google 애널리틱스 API 및 Apps Script를 사용하여 애플리케이션을 빌드하는 경우 일반적으로 다음 단계를 거칩니다.
- Google Sheets에서 Google 애널리틱스 API 사용 설정
- Google 애널리틱스 API 사용
각 단계를 자세히 살펴보겠습니다.
Apps Script에서 Google 애널리틱스 API 사용 설정
Google 스프레드시트 내에서 Google 애널리틱스 데이터에 액세스할 수 있도록 하려면 다음 단계를 따르세요.
- Google Sheets 파일을 만듭니다. 멋진 이름을 지어주세요.
- 새 Apps Script를 만듭니다.
- 메뉴에서 확장 프로그램 > Apps Script로 이동합니다.
- 메뉴가 나타나면 빈 프로젝트를 클릭합니다.
- 프로젝트 이름을 지정합니다. 멋진 이름이 있는지 확인하세요.
새 스크립트를 만들었으면 Google 애널리틱스 서비스를 사용 설정해야 합니다.
- 스크립트 편집기에서 리소스 > 고급 Google 서비스...를 선택합니다.
- 대화상자가 표시되면 Google 애널리틱스 API 옆에 있는 사용/사용 중지 스위치를 클릭합니다.
- 대화상자 하단에서 Google Developers Console 링크를 클릭합니다.
- 새 콘솔에서 Google 애널리틱스 API 옆에 있는 on/off 스위치를 다시 클릭합니다. 사용 설정하면 페이지 상단으로 이동합니다.
- 스크립트 편집기로 돌아가서 대화상자에서 OK를 클릭합니다.
스크립트에 새 Google API 서비스를 성공적으로 추가했음을 나타내는 작은 노란색 대화상자가 나타납니다. 이제 첫 번째 스크립트를 작성할 준비가 되었습니다.
Google 애널리틱스 API 사용
이 튜토리얼의 이 스크립트는 Google Analytics API에 상위 250개의 Google 모바일 검색 키워드를 쿼리한 후 결과를 Google Sheets로 출력합니다. 이를 위해 스크립트는 다음 단계를 거칩니다.
- 승인된 사용자의 첫 번째 보기 (프로필)를 가져옵니다.
- Core Reporting API에서 데이터를 쿼리합니다.
- 스프레드시트에 데이터를 삽입합니다.
다음 함수를 빈 프로젝트에 추가합니다.
function runDemo() {
try {
var firstProfile = getFirstProfile();
var results = getReportDataForProfile(firstProfile);
outputToSpreadsheet(results);
} catch(error) {
Browser.msgBox(error.message);
}
}
위 코드에서 try...catch 블록은 모든 API 오류를 처리하는 데 사용됩니다. 오류가 발생하면 프로그램 실행이 중단되고 메시지 상자에 오류가 표시됩니다. try 블록에서 함수는 스크립트가 수행할 각 단계를 실행하는 데 사용됩니다. 이제 각 함수의 코드를 추가해 보겠습니다.
승인된 사용자의 최초 보기 (프로필) 검색
Google 애널리틱스에서 각 보고서는 보기 (프로필)에 속하며 보기 (프로필) ID로 식별됩니다. 따라서 보고서 데이터에 대한 쿼리를 지정할 때 데이터를 검색하려는 보기 (프로필)의 보기 (프로필) ID도 지정해야 합니다.
Google Analytics Management API를 사용하면 사용자에게 속한 모든 계정, 웹속성, 보기 (프로필) 항목에 액세스할 수 있습니다. 각 항목은 계층 구조에 속하며 프로그래매틱 방식으로 이 계층 구조를 순회하여 승인된 사용자의 보기 (프로필) ID를 검색할 수 있습니다.
작성할 두 번째 함수는 Management API 계층 구조를 순회하고 사용자의 첫 번째 보기 (프로필)를 반환합니다. 다음 코드를 복사하여 Apps Script 프로젝트에 붙여넣습니다.
function getFirstProfile() {
var accounts = Analytics.Management.Accounts.list();
if (accounts.getItems()) {
var firstAccountId = accounts.getItems()[0].getId();
var webProperties = Analytics.Management.Webproperties.list(firstAccountId);
if (webProperties.getItems()) {
var firstWebPropertyId = webProperties.getItems()[0].getId();
var profiles = Analytics.Management.Profiles.list(firstAccountId, firstWebPropertyId);
if (profiles.getItems()) {
var firstProfile = profiles.getItems()[0];
return firstProfile;
} else {
throw new Error('No views (profiles) found.');
}
} else {
throw new Error('No webproperties found.');
}
} else {
throw new Error('No accounts found.');
}
}
이 함수에서는 먼저 Analytics.Management.Accounts.list 메서드를 사용하여 Accounts 컬렉션을 쿼리합니다. 승인된
사용자에게 Google 애널리틱스 계정이 있으면 첫 번째 계정의 ID가
가져옵니다. 그런 다음 Analytics.Management.Webproperties.list 메서드를 호출하고 이전 단계에서 검색한 계정 ID에 해당 메서드를 전달하여 웹 속성 컬렉션을 쿼리합니다.
웹 속성이 있는 경우 마지막으로 Analytics.Management.Profiles.list 메서드를 사용하여 보기 (프로필) 컬렉션을 쿼리합니다. 계정 ID와
웹 속성 ID가 모두 이 메서드에 매개변수로 전달됩니다. 보기 (프로필)가 있으면 첫 번째 보기 (프로필)가 반환됩니다.
언제든지 API 오류가 발생하거나 API 응답에 결과가 없으면 찾을 수 없다는 메시지가 포함된 오류가 발생합니다. 위 runDemo 함수의 catch 블록은 이 오류를 포착하여 사용자에게 메시지를 출력합니다.
스크립트가 반환된 후 이제 보고 데이터를 쿼리할 수 있습니다.
Core Reporting API에서 데이터를 쿼리합니다.
보기 (프로필) ID가 있으면 Core Reporting API를 사용하여 Google 애널리틱스 보고서 데이터를 쿼리합니다. 이 섹션에서는 Apps Script를 사용하여 이 API를 쿼리하는 방법을 알아봅니다.
Apps Script 프로젝트에 다음 코드를 추가합니다.
function getReportDataForProfile(firstProfile) {
var profileId = firstProfile.getId();
var tableId = 'ga:' + profileId;
var startDate = getLastNdays(14); // 2 weeks (a fortnight) ago.
var endDate = getLastNdays(0); // Today.
var optArgs = {
'dimensions': 'ga:keyword', // Comma separated list of dimensions.
'sort': '-ga:sessions,ga:keyword', // Sort by sessions descending, then keyword.
'segment': 'dynamic::ga:isMobile==Yes', // Process only mobile traffic.
'filters': 'ga:source==google', // Display only google traffic.
'start-index': '1',
'max-results': '250' // Display the first 250 results.
};
// Make a request to the API.
var results = Analytics.Data.Ga.get(
tableId, // Table id (format ga:xxxxxx).
startDate, // Start-date (format yyyy-MM-dd).
endDate, // End-date (format yyyy-MM-dd).
'ga:sessions,ga:pageviews', // Comma seperated list of metrics.
optArgs);
if (results.getRows()) {
return results;
} else {
throw new Error('No views (profiles) found');
}
}
function getLastNdays(nDaysAgo) {
var today = new Date();
var before = new Date();
before.setDate(today.getDate() - nDaysAgo);
return Utilities.formatDate(before, 'GMT', 'yyyy-MM-dd');
}
코드의 첫 번째 부분은 Analytics.Data.Ga.get 메서드를 사용하여 Core Reporting API 쿼리를 구성합니다. 이 메서드는 검색할 보고서 유형을 지정하는 여러 매개변수를 허용합니다. 각 Core Reporting API 쿼리는 필수 매개변수와 선택적 매개변수 집합으로 구성됩니다. 필수 매개변수는 매개변수로 메서드에 전달되고 선택적 매개변수는 객체로 전달됩니다.
table ID 매개변수는 필수 항목이며 접두사 ga:를 보기 (프로필) ID와 결합해 만들어집니다. 이 코드는 이전 단계에서 검색한 뷰 (프로필) ID를 사용하여 테이블 ID를 만듭니다. 시작일과 종료일도 필요하며 검색할 데이터의 기간을 지정합니다.
둘 다 getLastNdays 함수를 사용하여 오늘 날짜를 기준으로 계산됩니다. 마지막으로 모든 선택적 매개변수는 optArgs 객체를 사용하여 함수에 전달됩니다.
Analytics.Data.Ga.get 메서드가 실행되면 Core Reporting API에 요청이 전송됩니다. 오류가 발생하면 외부 runDemo 메서드에 정의된 try...catch 블록에서 포착됩니다. 요청이 성공하면 결과가 반환됩니다.
스프레드시트에 데이터 삽입
스크립트의 마지막 단계는 Core Reporting API의 결과를 Google Sheets로 출력하는 것입니다. outputToSpreadsheet 메서드가 이 작업을 실행합니다. 프로젝트에 다음 코드를 추가합니다.
function outputToSpreadsheet(results) {
var sheet = SpreadsheetApp.getActiveSpreadsheet().insertSheet();
// Print the headers.
var headerNames = [];
for (var i = 0, header; header = results.getColumnHeaders()[i]; ++i) {
headerNames.push(header.getName());
}
sheet.getRange(1, 1, 1, headerNames.length)
.setValues([headerNames]);
// Print the rows of data.
sheet.getRange(2, 1, results.getRows().length, headerNames.length)
.setValues(results.getRows());
}
이 함수는 먼저 새 시트를 활성 스프레드시트에 삽입합니다. 그런 다음 모든 헤더와 보고 데이터를 시트에 삽입합니다. Google Sheets에 데이터를 삽입하는 방법에 대한 자세한 내용은 스프레드시트에 데이터 저장 튜토리얼의 자바스크립트 객체에서 스프레드시트에 데이터 쓰기를 참조하세요.
스크립트 실행
모든 코드를 프로젝트에 추가했으면 이제 실행할 수 있습니다.
- 스크립트 편집기 툴바의 함수 선택 드롭다운에서
runDemo를 선택합니다. - 그런 다음
play버튼을 클릭합니다.
이 스크립트를 처음 실행하면 Google 애널리틱스 계정 데이터에 액세스할 수 있도록 스크립트를 승인하라는 팝업 상자가 표시됩니다.
승인을 클릭합니다.
클릭하면 google.com에 호스팅된 새 페이지가 열리고 이 스크립트에 데이터 액세스 권한을 부여하라는 메시지가 표시됩니다. 허용을 클릭하면 확인 페이지로 리디렉션됩니다. 이 시점에서 스크립트가 Google 애널리틱스 데이터에 액세스할 수 있고 계속 실행할 수 있습니다.
스크립트가 실행되면 Google Sheets가 표시된 창으로 클릭합니다. API에서 반환된 모든 키워드 데이터가 표시되거나 오류 메시지가 포함된 메시지 상자가 표시됩니다.
스크립트 자동화
이제 Google 애널리틱스 API를 쿼리하는 스크립트가 있어야 합니다.
이제 이 스크립트를 자동화하여 매일 밤 새 데이터를 검색해야 할 수 있습니다.
Apps Script에서는 triggers 기능을 사용하여 자동화를 매우 쉽게 수행할 수 있습니다.
이 스크립트를 자동화하려면 다음 단계를 따르세요.
- 스크립트 편집기 툴바에서
Resources -> All your triggers...아이콘을 클릭합니다. Add a new trigger아이콘을 클릭합니다. 트리거 대화상자가 나타납니다.- 매일 밤
runDemo메서드를 실행하도록 트리거를 구성합니다.Run드롭다운은runDemo로 설정해야 합니다.Events드롭다운은Time-driven,Day timer,Midnight to 1am로 설정해야 합니다.
구성이 완료되면 이 스크립트가 매일 밤 실행되어 아침에 새로운 데이터를 제공합니다.
야간에 오류가 발생하면 알림을 받게 됩니다. 또한 Apps Script를 사용하면 실패가 발생할 경우 이메일 알림을 보낼 수 있습니다. 이를 구성하려면 트리거 대화상자에서 notifications 링크를 클릭합니다.
새 대화상자가 열리고 오류를 전송할 이메일을 설정할 수 있습니다.
결론
스크립트에 대한 액세스 권한이 등록되고 승인되었습니다. 보기 (프로필) ID를 가져오기 위해 Management API를 여러 번 쿼리했습니다. 그런 다음 보기 (프로필) ID를 사용하여 Core Reporting API를 쿼리하여 데이터를 검색하고 Google 스프레드시트로 출력했습니다.
가이드에 설명된 기법을 사용하면 더 복잡한 분석을 수행하고, 유용한 정보를 얻고, 커스텀 대시보드를 빌드하고, 수동 보고서를 실행하는 데 걸리는 시간을 줄일 수 있습니다.
Google 애널리틱스 API 및 Google Apps Script를 최대한 활용하는 데 도움이 될 만한 몇 가지 유용한 가이드는 다음과 같습니다.
- 스프레드시트에서 데이터 읽기 – JavaScript 대신 스프레드시트에서 API 쿼리를 지정할 수 있습니다.
- 스프레드시트의 차트를 Google 사이트 도구에 삽입 – 애널리틱스 데이터를 사용하여 Google 사이트 도구에서 대시보드를 만들 수 있습니다.
- 맞춤 메뉴 – 작성한 스크립트를 회사의 다른 사용자가 쉽게 사용할 수 있도록 합니다.