Nick Mihailovski, Google Analytics API Ekibi – Ağustos 2012
Bu eğiticide, Apps Komut Dosyası kullanılarak Google E-Tablolar'daki Yönetim ve Temel Raporlama API'lerine nasıl erişileceği açıklanmaktadır.
Giriş
Google Analytics verilerinize Google E-Tablolar'dan erişmek için Google Analytics API ve Google Apps Komut Dosyası'nı kullanabilirsiniz. Bu özellik, analiz verilerinizle birlikte Google E-Tablolar'ın kolay paylaşım, ortak çalışma, grafik oluşturma ve görselleştirme araçları gibi muhteşem özelliklerden yararlanmanıza olanak tanıdığından oldukça faydalıdır.
Bu eğitim, Google Apps Komut Dosyası'nı kullanarak Google E-Tablolar'da Google Analytics verilerinize erişmek için gerekli olan kodu adım adım açıklar.
Genel bakış
Bu eğitim, Google Analytics API'yi kullanmak için Apps Komut Dosyası ortamını nasıl kaydedeceğinizi ve yapılandırdığınızı gösterir. Yapılandırmanın ardından eğitim, yetkilendirilmiş kullanıcı için Management API'yi kullanarak görünüm (profil) kimliğini nasıl alacağınız konusunda size yol gösterir. Ardından, Google'dan en iyi 250 mobil arama anahtar kelimesini almak üzere Temel Raporlama API'sını sorgulamak için görünüm (profil) kimliğinin nasıl kullanılacağı. Son olarak sonuçlar bir Google E-tablosuna eklenir. Veri toplandıktan sonra eğiticide veri alımının nasıl otomatikleştirileceği de açıklanmaktadır.
Google Analytics API ve Apps Komut Dosyası'nı kullanarak uygulama oluştururken genellikle aşağıdaki adımları uygularsınız:
- Google E-Tablolar'da Google Analytics API'lerini etkinleştirme
- Google Analytics API'larıyla çalışma
Şimdi her adımı ayrıntılı olarak inceleyelim.
Apps Komut Dosyası'nda Google Analytics API'yi etkinleştirme
Google Analytics verilerinize Google E-Tablolar'dan erişimi etkinleştirmek için aşağıdaki adımları izleyin:
- Bir Google E-Tablolar dosyası oluşturun. Havalı bir ad verin.
- Yeni bir Apps Komut Dosyası oluşturun.
- Menüde Uzantılar > Apps Komut Dosyası'na gidin.
- Bir menü açılırsa Boş Proje'yi tıklamanız yeterlidir.
- Projeye bir ad verin. Hoş bir adı olduğundan emin olun.
Yeni bir komut dosyası oluşturduktan sonra Google Analytics Hizmeti'ni etkinleştirmeniz gerekir.
- Komut dosyası düzenleyicide Kaynaklar > Gelişmiş Google hizmetleri... seçeneğini belirleyin.
- Açılan iletişim kutusunda, Google Analytics API'nin yanındaki açık/kapalı anahtarını tıklayın.
- İletişim kutusunun alt kısmında Google Developers Console bağlantısını tıklayın.
- Yeni konsolda, Google Analytics API'nin yanındaki açık/kapalı anahtarını tekrar tıklayın. (Etkinleştirildiğinde, sayfanın en üstüne atlar.)
- Komut dosyası düzenleyiciye dönün ve iletişim kutusunda Tamam'ı tıklayın.
Komut dosyanıza başarıyla yeni bir Google API'leri hizmeti eklediğinizi belirten küçük sarı bir iletişim kutusu açılır. Artık ilk komut dosyanızı yazmaya hazırsınız.
Google Analytics API ile çalışma
Bu eğitimdeki bu komut dosyası, en iyi 250 Google mobil arama anahtar kelimesi için Google Analytics API'yi sorgulayacak, ardından sonuçları Google E-Tablolar'a aktaracaktır. Bunun için komut dosyası aşağıdaki adımları uygular:
- Yetkili kullanıcının ilk görünümünü (profil) alın.
- Temel Raporlama API'sını veriler için sorgulayın.
- E-tabloya veri ekleyin.
Boş projeye aşağıdaki işlevi ekleyin.
function runDemo() {
try {
var firstProfile = getFirstProfile();
var results = getReportDataForProfile(firstProfile);
outputToSpreadsheet(results);
} catch(error) {
Browser.msgBox(error.message);
}
}
Yukarıdaki kodda, API hatalarını işlemek için bir try...catch bloğu kullanılmıştır. Herhangi bir hata oluşursa programın yürütülmesi durdurulur ve hata bir mesaj kutusunda gösterilir. try bloğunda, komut dosyasının uygulayacağı adımların her birini gerçekleştirmek için bir işlev kullanılır. Şimdi bu işlevlerin her birinin kodunu ekleyelim.
Yetkili Kullanıcının İlk Görünümünü (Profil) alma
Google Analytics'te her rapor bir görünüme (profile) aittir ve bir görünüm (profil) kimliğiyle tanımlanır. Dolayısıyla, rapor verileri için bir sorgu belirtirken, verileri almak istediğiniz görünümün (profilin) görünüm (profil) kimliğini de belirtmeniz gerekir.
Google Analytics Management API, bir kullanıcıya ait olan tüm hesaplara, web mülklerine ve görünüm (profil) varlıklarına erişim sağlar. Bu varlıklardan her biri bir hiyerarşiye aittir ve yetkilendirilmiş kullanıcı için bir görünüm (profil) kimliği almak üzere bu hiyerarşiyi programatik olarak gezinebilirsiniz.
Yazacağımız ikinci işlev, Management API hiyerarşisinin derinliklerine inecek ve kullanıcının ilk görünümünü (profil) döndürecektir. Aşağıdaki kodu kopyalayıp Apps Komut Dosyası projenize yapıştırın:
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.');
}
}
Bu işlevde ilk olarak Analytics.Management.Accounts.list yöntemi kullanılarak Hesaplar koleksiyonu sorgulanır. Yetkili kullanıcının
Google Analytics hesabı varsa ilk hesabın kimliği
alınır. Ardından, Analytics.Management.Webproperties.list yöntemi çağrılıp yöntem önceki adımda alınan hesap kimliği iletilerek web mülkleri koleksiyonu sorgulanır.
Web mülkleri mevcutsa görünüm (profil) koleksiyonu son olarak Analytics.Management.Profiles.list yöntemi kullanılarak sorgulanır. Hem hesap kimliği hem de web mülkü kimlikleri bu yönteme parametre olarak aktarılır. Görünümler (profiller) varsa ilk görünüm (profil) döndürülür.
Herhangi bir zamanda API hatası oluşursa veya API yanıtı hiçbir sonuç içermiyorsa hiçbir sonuç bulunamadığını açıklayan bir mesaj içeren hata mesajı gönderilir. Yukarıdaki runDemo işlevinde bulunan catch bloğu bu hatayı yakalar ve mesajı kullanıcıya yazdırır.
Komut dosyası geri döndükten sonra artık raporlama verilerini sorgulayabilir.
Temel Raporlama API'sını veriler için sorgulayın.
Bir görünüm (profil) kimliğiniz olduğunda Google Analytics rapor verilerini sorgulamak için Temel Raporlama API'sını kullanırsınız. Bu bölümde, Apps Komut Dosyası'nı kullanarak bu API'yi nasıl sorgulayacağınızı öğreneceksiniz.
Aşağıdaki kodu Apps Komut Dosyası projenize ekleyin:
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');
}
Kodun ilk bölümü, Analytics.Data.Ga.get yöntemini kullanarak bir Core Reporting API sorgusu oluşturur. Yöntem, alınacak raporun türünü belirten bir dizi parametreyi kabul eder. Her Core Reporting API sorgusu, bir dizi zorunlu ve isteğe bağlı parametreden oluşur. Zorunlu parametreler yönteme parametre olarak, isteğe bağlı parametreler ise nesne olarak aktarılır.
table ID parametresi gereklidir ve ga: ön eki görünüm (profil) kimliğiyle birleştirilerek oluşturulur. Kod, önceki adımda alınan görünüm (profil) kimliğini kullanarak tablo kimliğini oluşturur. Başlangıç ve bitiş tarihi de zorunludur. Ayrıca, alınacak verilerin tarih aralığı da belirtilir.
Her ikisi de getLastNdays işlevi kullanılarak bugünün tarihine göre hesaplanır. Son olarak, isteğe bağlı tüm parametreler optArgs nesnesi kullanılarak işleve aktarılır.
Analytics.Data.Ga.get yöntemi çalıştığında, Core Reporting API'ye bir istek gönderilir. Bir hata oluşursa dış runDemo yönteminde tanımlanan try...catch blokunda yakalanır. İstek başarılı olduysa sonuçlar döndürülür.
E-tabloya Veri Ekleme
Komut dosyasındaki son adım, Core Reporting API'deki sonuçların çıktısını Google E-Tablolar'a aktarmaktır. Bu işi outputToSpreadsheet yöntemi yapar. Aşağıdaki kodu projenize ekleyin:
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());
}
Bu işlev, etkin e-tabloya öncelikle yeni bir sayfa ekler. Ardından, tüm üstbilgi ve raporlama verilerini e-tabloya ekler. Google E-Tablolar'a veri ekleme hakkında daha fazla ipucu için E-tablolarda Veri Depolama başlıklı makaledeki JavaScript Nesnelerinden E-Tabloya Veri Yazma konusunu okuyun.
Komut Dosyasını Çalıştırma
Tüm kodu projeye ekledikten sonra çalıştırabilirsiniz.
- Komut dosyası düzenleyici araç çubuğunda, işlev seçme açılır listesinde
runDemosimgesini seçin. - Ardından
playdüğmesini tıklayın.
Bu komut dosyasını ilk kez çalıştırdığınızda, Google Analytics hesabınızın verilerine erişmesi için bu komut dosyasını yetkilendirmenizi gerektiren bir pop-up kutu görüntülenir.
Yetkilendir'i tıklayın.
Tıklandığında google.com'da barındırılan yeni bir sayfa açılır ve bu komut dosyasının verilerinize erişmesine izin vermeniz istenir. İzin ver'i tıkladığınızda onay sayfasına yönlendirilirsiniz. Bu noktada, komut dosyası artık Google Analytics verilerinize erişebilir ve çalışmaya devam edebilir.
Komut dosyası çalıştırıldıktan sonra, Google E-Tablolar'ın bulunduğu pencerenin üzerine tıklayın. API'den döndürülen tüm anahtar kelime verilerini veya hata mesajı içeren bir mesaj kutusunu görürsünüz.
Komut Dosyasını Otomatikleştirin
Bu noktada, Google Analytics API'yi sorgulayan bir komut dosyanızın olması gerekir.
Artık bu komut dosyasını, her gece yeni veriler alacak şekilde otomatikleştirmek isteyebilirsiniz.
Apps Komut Dosyası, triggers özelliğini kullanarak otomasyonu çok kolaylaştırır.
Bu komut dosyasını otomatikleştirmek için aşağıdaki adımları uygulayın:
- Komut dosyası düzenleyici araç çubuğunda
Resources -> All your triggers...simgesini tıklayın Add a new triggersimgesini tıklayın. Tetikleyiciler iletişim kutusu görünür.- Tetikleyiciyi her gece
runDemoyöntemini yürütecek şekilde yapılandırınRunaçılır listesi şu değere ayarlanmalıdır:runDemoEventsaçılır listesi şu değere ayarlanmalıdır:Time-driven,Day timerveMidnight to 1am.
Bu komut dosyası yapılandırıldıktan sonra her gece çalışarak sabahları yeni veriler sunar.
Gece herhangi bir hata oluşursa, bu konuda bilgilendirilmek istersiniz. Apps Komut Dosyası, herhangi bir hata oluşursa e-posta uyarısı göndermenize de olanak tanır. Bunu yapılandırmak için tetikleyiciler iletişim kutusundaki notifications bağlantısını tıklayın.
Yeni bir iletişim kutusu açılır ve hataların gönderilmesini istediğiniz e-posta adresini yapılandırmanıza olanak tanır.
Sonuç
komut dosyanıza başarılı bir şekilde kaydolup erişim yetkisi verdiniz. Görünüm (profil) kimliğini almak için Management API'yi birden fazla kez sorguladınız. Ardından, verileri almak ve Google E-Tablolar'da çıktısını almak amacıyla Core Reporting API'yi sorgulamak için görünüm (profil) kimliğini kullandınız.
Eğiticide açıklanan teknikleri kullanarak daha karmaşık analizler yapabilir, daha fazla bilgi edinebilir, özel kontrol panelleri oluşturabilir ve manuel raporlar çalıştırmak için harcadığınız zamanı azaltabilirsiniz.
Google Analytics API ve Google Apps Komut Dosyası'ndan daha fazla yararlanmanıza yardımcı olabilecek diğer faydalı eğiticileri aşağıda bulabilirsiniz:
- E-Tablolardan Veri Okuma – Böylece API sorgularınızı JavaScript yerine bir e-tabloda belirtebilirsiniz.
- E-tablolardan Grafik Ekleme – Böylece Analytics Verilerinizi kullanarak Google Sites'ta gösterge tabloları oluşturabilirsiniz.
- Özel Menüler – Şirketinizdeki diğer kullanıcıların yazdığınız komut dosyalarını kullanmasını kolaylaştırmak için.