Bu, Analytics Reporting API v4 için geliştirici kılavuzudur. API'nin ayrıntılı referansı için API Referansı'na bakın.
Raporlar
Analytics Reporting API v4, Raporlar kaynağına erişmek için batchGet yöntemini sağlar.
Aşağıdaki bölümlerde batchGet
için istek gövdesinin yapısı ve batchGet
kaynağındaki yanıt gövdesinin yapısı açıklanmaktadır.
İstek Metni
Analytics Reporting API v4'ü veri isteğinde bulunmak amacıyla kullanmak için aşağıdaki minimum gereksinimlere sahip bir ReportRequest nesnesi oluşturmanız gerekir:
- viewId alanı için geçerli bir görüntüleme kimliği.
- dateRanges alanında en az bir geçerli giriş.
- metrics alanında en az bir geçerli giriş olmalıdır.
Bir görünüm kimliğini bulmak için hesap özetleri yöntemini sorgulayın veya Hesap Gezgini'ni kullanın.
Tarih aralığı belirtilmemişse varsayılan tarih aralığı şu şekilde olur:
{"startDate": "7daysAgo", "endDate": "yesterday"}
.
Aşağıda, gerekli minimum alanların yer aldığı örnek bir istek verilmiştir:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:users"}]
}
]
}
batchGet
yöntemi, en fazla beş ReportRequest nesnesi kabul eder. Tüm istekler aynı dateRange
,
viewId
,
segments
,
samplingLevel
ve cohortGroup
özelliklerine sahip olmalıdır.
Yanıt Metni
API isteğinin yanıt gövdesi, bir Rapor nesneleri dizisidir. Rapor yapısı, rapordaki boyutları, metrikleri ve bunların veri türlerini açıklayan ColumnHeader nesnesinde tanımlanır. Boyut ve metriklerin değerleri data (veriler) alanında belirtilir.
Aşağıda, yukarıdaki örnek istek için örnek bir yanıt verilmiştir:
{
"reports": [
{
"columnHeader": {
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:users",
"type": "INTEGER"
}
]
}
},
"data": {
"isDataGolden": true,
"maximums": [
{
"values": [
"98"
]
}
],
"minimums": [
{
"values": [
"98"
]
}
],
"rowCount": 1,
"rows": [
{
"metrics": [
{
"values": [
"98"
]
}
]
}
],
"totals": [
{
"values": [
"98"
]
}
]
}
}
]
}
Metrikler
Metrikler nicel ölçümlerdir. Her istek için en az bir Metrik nesnesi gerekir.
Aşağıdaki örnekte, belirtilen tarih aralığındaki toplam oturum sayısını almak için batchGet
yöntemine Sessions
metriği sağlanmıştır:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:sessions"}]
}
]
}
Kullanılabilir boyutların ve metriklerin listesini almak için boyutlar ve metrik gezginini veya Metadata API'sini kullanabilirsiniz.
Filtreleme
Bir batchGet
isteği gönderirken yalnızca belirli ölçütleri karşılayan metrikleri döndürmesini isteyebilirsiniz. Metrikleri filtrelemek için istek gövdesinde bir veya daha fazla MetricFilterClauses belirtin ve her bir MetricFilterClause
için bir veya daha fazla MetricFilters tanımlayın.
Her bir MetricFilter
içinde aşağıdakilerin değerlerini belirtin:
metricName
not
operator
comparisonValue
Metriği {metricName}
, {operator}
operator
ve {comparisonValue}
comparisonValue
temsil etsin. Bu durumda filtre şu şekilde çalışır:
if {metricName} {operator} {comparisonValue}
return the metric
not
için true
değerini belirtirseniz filtre şu şekilde çalışır:
if {metricName} {operator} {comparisonValue}
do not return the metric
Aşağıdaki örnekte, batchGet
yalnızca değeri 2'den büyük olan sayfa görüntülemelerini döndürür:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"metricFilterClauses": [{
"filters": [{
"metricName": "ga:pageviews",
"operator": "GREATER_THAN",
"comparisonValue": "2"
}]
}]
}]
}
İfadeler
Metrik ifadesi, mevcut metrikler üzerinde tanımladığınız matematiksel bir ifadedir. Dinamik hesaplanmış metrikler gibi çalışır. Metrik ifadesini temsil edecek bir takma ad tanımlayabilirsiniz. Örneğin:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{
"expression": "ga:goal1completions/ga:users",
"alias": "completions per user"
}
]
}
]
}
Sıralama
Sonuçları bir metrik değerine göre sıralamak için:
- Adını veya takma adını
fieldName
alanından sağlayın. sortOrder
alanı aracılığıyla sıralama düzenini (ASCENDING
veyaDESCENDING
) belirtin.
Aşağıdaki örnekte batchGet
, önce oturum sayısına, ardından sayfa görüntüleme sayısına göre büyükten küçüğe sıralanan metrikleri döndürür:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"orderBys":
[
{"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
{"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
]
}
]
}
Boyutlar
Boyutlar kullanıcılarınızın özelliklerini, oturumlarını ve işlemlerini tanımlar.
Örneğin Şehir boyutu, oturumların özelliğini tanımlar ve her bir oturumun oluştuğu şehri ("Paris" veya "New York") belirtir.
Bir batchGet
isteğinde sıfır veya daha fazla boyut nesnesi belirtebilirsiniz. Örneğin:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges":
[
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics":
[
{"expression": "ga:users"}
],
"dimensions":
[
{"name": "ga:city"}
]
}
]
}
Filtreleme
Bir batchGet
isteği gönderirken yalnızca belirli ölçütleri karşılayan boyutları döndürmesini isteyebilirsiniz. Boyutları filtrelemek için istek gövdesinde bir veya daha fazla DimensionsFilterClauses öğesini belirtin ve her bir DimensionsFilterClause
öğesinde bir veya daha fazla DimensionsFilters tanımlayın.
Her bir DimensionsFilters
içinde aşağıdakilerin değerlerini belirtin:
dimensionName
not
operator
expressions
caseSensitive
{dimensionName}
boyutu, {operator}
operator
ve {expressions}
expressions
temsil ediyor olsun. Bu durumda filtre şu şekilde çalışır:
if {dimensionName} {operator} {expressions}
return the dimension
not
için true
değerini belirtirseniz filtre şu şekilde çalışır:
if {dimensionName} {operator} {expressions}
do not return the dimension
Aşağıdaki örnekte batchGet
, Chrome tarayıcıda sayfa görüntülemelerini ve oturumları döndürür:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Chrome"]
}
]
}
]
}
]
}
Sıralama
Sonuçları boyut değerine göre sıralamak için:
- Dosyanın adını
fieldName
alanından sağlayın. sortOrder
alanından sıralama düzenini (ASCENDING
veyaDESCENDING
) belirtin.
Örneğin, aşağıdaki batchGet
, boyutları ülkeye ve ardından tarayıcıya göre sıralanmış şekilde döndürür:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
"orderBys": [
{"fieldName": "ga:country"},
{"fieldName": "ga:browser"}
]
}
]
}
Histogram paketleri
Tam sayı değerlerine sahip boyutların değerlerini aralıklar halinde gruplandırarak özelliklerini anlamak daha kolaydır. Sonuçta elde edilen paketlerde aralıkları tanımlamak için histogramBuckets
alanını kullanın ve sipariş türü olarak HISTOGRAM_BUCKET
değerini belirtin. Örneğin:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [
{
"name": "ga:sessionCount",
"histogramBuckets": ["1","10","100","200","400"]
}
],
"orderBys": [
{
"fieldName": "ga:sessionCount",
"orderType": "HISTOGRAM_BUCKET"
}
]
}
]
}
Birden Fazla Tarih Aralığı
Google Analytics Reporting API v4, tek bir istekte birden çok tarih aralığındaki verileri almanıza olanak tanır. İsteğiniz ister bir ister iki tarih aralığı belirtsin, veriler dateRangeValue nesnesinde döndürülür. Örneğin:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}]
}
]
}
Delta siparişi
İki tarih aralığında metrik değerleri isteğinde bulunurken sonuçları, tarih aralıklarındaki metriğin değerleri arasındaki farka göre sıralayabilirsiniz. Örneğin:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}],
"orderBys": [
{
"fieldName": "ga:sessions",
"orderType": "DELTA"
}
]
}
]
}
Tarih boyutu davranışı
Tarih veya saatle ilgili bir boyut isteğinde bulunursanız DateRangeValue nesnesi, yalnızca ilgili aralıklarda yer alan tarihlere ait değerleri içerir. Belirtilen tarih aralıklarında olmayan diğer tüm değerler 0
olur.
Örneğin, ga:date
boyutu ve ga:sessions
metriği için Ocak ve Şubat olmak üzere iki tarih aralığındaki bir isteği ele alalım.
Ocak ayındaki istenen verilerin yanıtında, Şubat ayındaki değerler 0
; Şubat ayındaki istenen verilerin yanıtında ise Ocak ayındaki değerler 0
olacaktır.
Ocak raporu
{
"dimensions": [
"20140101" # `ga:date` dimension value for January 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"8"
]
},
{
"values": [ # February DateRangeValue.
"0"
]
}
]
},
...
Şubat raporu
{
"dimensions": [
"20140201" # `ga:date` dimension value for February 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"0"
]
},
{
"values": [ # February DateRangeValue.
"7"
]
}
]
},
...
Segmentler
Analytics verilerinizin bir alt kümesini istemek için segmentleri kullanın. Örneğin, bir segmentte belirli bir ülkeden veya şehirden kullanıcıları, başka bir segmentte ise sitenizin belirli bir bölümünü ziyaret eden kullanıcıları tanımlayabilirsiniz. Filtreler yalnızca bir koşulu karşılayan satırları döndürürken segmentler, segmentleri içeren koşulları karşılayan kullanıcıların, oturumların veya etkinliklerin alt kümelerini döndürür.
Segmentlerle istekte bulunurken aşağıdakilerden emin olun:
- Bir
batchGet
yöntemindeki her ReportRequest, aynı segment tanımları içermelidir. - Boyut listesine
ga:segment
eklersiniz.
Örneğin:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
"metrics": [{"expression": "ga:sessions"}],
"segments": [
{
"dynamicSegment":
{
"name": "Sessions with Safari browser",
"userSegment":
{
"segmentFilters": [
{
"simpleSegment":
{
"orFiltersForSegment": [
{
"segmentFilterClauses": [
{
"dimensionFilter":
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Safari"]
}
}]
}]
}
}]
}
}
}]
}]
}
Segment içeren daha fazla örnek istek için Örnekler bölümüne bakın.
Segment kimliği
Segment istemek için segmentId
alanını kullanın.
Segment isteğinde bulunmak için hem segmentId
hem de dynamicSegment
kullanamazsınız.
Örneğin:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
"metrics": [{"expression": "ga:users"}],
"segments": [{"segmentId": "gaid::-3"}]
}
]
}
Örneklendirme
Örnekleme, verilerinizin sonuçlarını etkileyebilir ve API'den döndürülen değerlerin web arayüzüyle eşleşmemesinin yaygın bir nedenidir. İstediğiniz örnek boyutunu ayarlamak için samplingLevel
alanını kullanın.
- Daha küçük bir örnekleme boyutuyla hızlı yanıt için değeri
SMALL
olarak ayarlayın. - daha doğru ancak daha yavaş bir yanıt için değeri
LARGE
olarak ayarlayın. - Hızı ve doğruluğu dengeleyen bir yanıt için değeri
DEFAULT
olarak ayarlayın.
Örneğin:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}],
"metrics": [{"expression": "ga:sessions"}],
"samplingLevel": "LARGE"
}
]
}
Bir rapor örneklenmiş veriler içeriyorsa Analytics Reporting API v4, samplesReadCounts
ve samplingSpaceSizes
alanlarını döndürür.
Sonuçlar örneklenmemişse bu alanlar tanımlanmaz.
Aşağıda, iki tarih aralığına sahip bir istekten örneklenmiş veriler içeren bir yanıt örneği verilmiştir. Sonuçlar, yaklaşık 15 milyon oturum büyüklüğündeki bir örnekleme alanının yaklaşık 500 bin örneğinden hesaplanmıştır:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
Sayfalara ayırma
Analytics Reporting API v4, birden fazla sayfaya yayılan yanıt sonuçlarını sayfalara ayırmak için pageToken
ve pageSize
alanlarını kullanır. reports.batchGet
isteğine verilen yanıtta nextPageToken
parametresinden pageToken
elde edersiniz:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
Sonraki adım
Rapor oluşturmayla ilgili temel bilgileri öğrendiğinize göre, API v4'ün gelişmiş özelliklerine göz atabilirsiniz.