Google Analytics Data API v1, pivot tablolar oluşturmanıza olanak tanır. Pivot tablolar, verilerinizi bir veya daha fazla boyutta özetleyerek (döndürerek) tablodaki bilgileri yeniden düzenleyerek verileri görselleştiren bir veri özetleme aracıdır.
Örnek olarak aşağıdaki ham veri tablosunu ele alalım:
Bu verileri kullanarak, oturum verilerini tarayıcıya göre ayıran, ülke ve dil boyutlarının ek pivotlar olarak seçildiği bir pivot tablo oluşturmak mümkündür.
Temel Raporlarla Paylaşılan Özellikler
Pivot raporlama istekleri, birçok paylaşılan özellik için Temel rapor istekleriyle aynı anlamlara sahiptir. Örneğin, sayfalara ayırma, Boyut Filtreleri ve Kullanıcı Özellikleri, Özet Raporlar'da Temel Raporlar ile aynı şekilde davranır. Bu kılavuz, özet raporlama özelliklerine odaklanmaktadır. Data API v1'in Temel Raporlama işlevini öğrenmek için raporlamayla ilgili temel bilgiler kılavuzunu ve gelişmiş kullanım alanları kılavuzunu okuyun.
Özet raporlama yöntemleri
Data API v1, aşağıdaki raporlama yöntemlerinde pivot işlevini destekler:
runPivotReport Bu yöntem, Google Analytics etkinlik verilerinizin özelleştirilmiş bir pivot raporunu döndürür. Her bir özet, rapor yanıtındaki görünür boyut sütunlarını ve satırlarını açıklar.
batchRunPivotReports Bu, tek bir API çağrısı kullanarak birden fazla rapor oluşturulmasına olanak tanıyan
runPivotReportyönteminin toplu sürümüdür.
Rapor Eden Varlık Seçme
Tüm Data API v1 yöntemleri, Google Analytics 4 mülk tanımlayıcısının bir URL istek yolunda properties/GA4_PROPERTY_ID biçiminde belirtilmesini gerektirir. Örneğin:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
Elde edilen rapor, belirtilen Google Analytics 4 mülkünde toplanan Google Analytics etkinlik verilerine göre oluşturulur.
Data API istemci kitaplıklarından birini kullanıyorsanız istek URL yolunu manuel olarak değiştirmenize gerek yoktur. Çoğu API istemcisi, properties/GA4_PROPERTY_ID biçiminde bir dize bekleyen property parametresi sağlar. İstemci kitaplıklarını kullanmaya ilişkin örnekler için Hızlı başlangıç kılavuzuna bakın.
Özet Rapor İsteği
Pivot tabloyla bir istek oluşturmak için runPivotReport veya batchRunPivotReports yöntemini kullanın.
Özetlenmiş verileri istemek için bir RunPivotReportRequest nesnesi oluşturabilirsiniz. Şu istek parametreleriyle başlamanızı öneririz:
- dateRanges alanında geçerli bir giriş.
- Boyutlar alanında en az bir geçerli giriş.
- metrics alanında en az bir geçerli giriş olmalıdır.
- Özetler alanında en az iki geçerli pivot girişi.
Aşağıda, önerilen alanları içeren örnek bir istek verilmiştir:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [
{ "name": "browser" },
{ "name": "country" },
{ "name": "language" }
],
"metrics": [{ "name": "sessions" }],
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5
},
{
"fieldNames": [
"country"
],
"limit": 250
},
{
"fieldNames": [
"language"
],
"limit": 15
}
]
}
Pivotlar
Rapor pivotlarını tanımlamak için istek gövdesinin pivot alanındaki Pivot nesnelerini kullanın. Her Pivot, rapor yanıtındaki görünür boyut sütunlarını ve satırları açıklar.
Her özetin limit parametresinin çarpımı 100.000'i aşmadığı sürece Data API v1,birden fazla özet sürecini destekler.
Aşağıda, browser boyutuna göre özetlenerek ülkeye göre oturum sayıları raporu oluşturmak için pivots kullanımının gösterildiği bir snippet bulunmaktadır. Sorgunun sıralama için orderBys alanını, sayfalara ayırma işlemini uygulamak için de limit ve offset alanlarını nasıl kullandığını unutmayın.
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
...
Boyutlar
Boyutlar, web siteniz veya uygulamanızla ilgili etkinlik verilerini açıklar ve gruplandırır. Örneğin city boyutu, her bir etkinliğin meydana geldiği şehri ("Paris" veya "New York") belirtir. Bir rapor isteğinde sıfır veya daha fazla boyut belirtebilirsiniz.
Boyutlar, istek gövdesinin dimensions alanı içinde tanımlanmalıdır. Bir raporda görünmeleri için bu boyutların Pivot nesnesinin fieldNames alanında da listelenmesi gerekir.
Pivot sorgunun herhangi bir özetinde kullanılmayan boyutlar, raporda görünmez. Her boyut, bir pivot noktasının fieldNames öğesinde mevcut olmak zorunda değildir. Boyutlar yalnızca filtrelerde kullanılabilir ve herhangi bir pivotun fieldNames öğesinde kullanılamaz.
Aşağıda browser, country ve language pivotlarına sahip bir tablo için dimension ve fieldNames alanlarının kullanımını gösteren bir snippet verilmiştir:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
},
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"language"
],
"limit": 10
}
],
Metrikler
Metrikler, web siteniz veya uygulamanız için etkinlik verilerinin nicel ölçümleridir. Bir rapor isteğinde bir veya daha fazla metrik belirtebilirsiniz. İsteklerde belirtilebilecek API Metriği adlarının tam listesi için API Metrikleri'ne bakın.
Pivot rapor isteklerinde metrikler, istek gövdesinin metrics alanı kullanılarak tanımlanır. Bu, Temel Raporlama yöntemlerine benzer.
Aşağıdaki bir örnek, raporda metrik değeri olarak kullanılacak oturum sayısını belirtir:
"metrics": [
{
"name": "sessions"
}
],
Metrik toplamaları
Her pivot için birleştirilmiş metrik değerlerini hesaplamak üzere bir Pivot nesnesinin metricAggregations alanını kullanın.
Toplamalar yalnızca, bir istekte metricAggregations alanı belirtilirse hesaplanır.
Aşağıda, browser pivot boyutu için toplamları isteyen bir sorgunun snippet'i verilmiştir:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
Hesaplanan metrikler, RunPivotReportResponse nesnesinin aggregates alanında döndürülür. Toplu metrik satırları için dimensionValues alanı, RESERVED_TOTAL, RESERVED_MAX veya RESERVED_MIN gibi özel bir değer içerir.
"aggregates": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6"
}
]
},
....
}
Sayfalara ayırma
Temel Raporlama yöntemlerine benzer şekilde, pivot istekleri de sayfalandırmayı uygulamak için Pivot nesnesinde sınır ve ofset alanlarını belirtmenize olanak tanır.
Sayfalara ayırma ayarları her özete ayrı olarak uygulanır.
Rapor kardinalitesini sınırlandırmak için her Pivot nesnesi için limit alanı zorunludur.
Her pivot için limit parametre çarpımı 100.000'i aşmadığı sürece Data API v1 birden fazla pivotu destekler.
Aşağıda, ofset değeri 10 olan sonraki beş language boyutunu almak için offset ve limit alanlarının kullanımını gösteren bir snippet verilmiştir:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Filtreleme
Temel Raporlama işlevine benzer şekilde, pivot raporlama isteğinde boyut filtrelemesi isteniyorsa istek kapsamlı bir boyut filtresi kullanılmalıdır.
Sıralama
Pivot rapor sorgularının sıralama davranışı, OrderBy nesnelerinin listesini içeren bir Pivot nesnesinin orderBys alanı kullanılarak her özet için tek tek kontrol edilebilir.
Her OrderBy aşağıdakilerden birini içerebilir:
- DimensionOrderBy, sonuçları bir boyutun değerlerine göre sıralar.
- MetricOrderBy, sonuçları bir metriğin değerlerine göre sıralar.
- PivotOrderBy, pivot sorgularında kullanılır ve sonuçları pivot sütun grubundaki bir metriğin değerlerine göre sıralar.
Bu örnekte, raporu browser boyutunda özetleyen ve sonuçları sessions metriğine göre azalan düzende sıralayan bir pivot tanımı snippet'i gösterilmektedir.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Yanıtı bildir
Bir pivot rapor API isteğinin Pivot Rapor Yanıtı, temel olarak bir başlık ve satırlardan oluşur.
Yanıt Başlıkları
Pivot rapor başlığı, özet rapordaki sütunları listeleyen PivotHeaders, DimensionHeaders ve MetricHeaders öğelerinden oluşur.
Örneğin, browser, country ve language pivot boyutlarına ve sessions metriğine sahip bir rapor, aşağıdaki gibi başlıklar elde eder:
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Chrome"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "United States"
}
]
},
{
"dimensionValues": [
{
"value": "Canada"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "English"
}
]
},
{
"dimensionValues": [
{
"value": "French"
}
]
},
...
],
...
}
],
"dimensionHeaders": [
{
"name": "browser"
},
{
"name": "country"
},
{
"name": "language"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
...
}
Aşağıdaki grafikte, pivot raporu oluşturmada Pivot Rapor Yanıtı'nın her bileşeninin rolü gösterilmektedir:
Yanıt Satırları
runPivotReport ve batchRunPivotReports yöntemlerinin pivot rapor yanıtı, her pivot rapor yanıt satırının tablodaki tek bir hücreyi, normal bir raporda ise tek bir yanıt satırı tam bir tablo satırını temsil etmesi bakımından runReport ve batchRunReports gibi Temel Raporlama yöntemlerinin yanıtlarından farklıdır.
Aşağıda browser, country ve language pivot boyutları ve sessions metriğini içeren bir sorgu için pivot rapor yanıtının bir parçası bulunmaktadır. Pivot raporun her bir hücresi tek tek döndürülür:
"rows": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "United States"
},
{
"value": "English"
}
],
"metricValues": [
{
"value": "1"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "Canada"
},
{
"value": "French"
}
],
"metricValues": [
{
"value": "3"
}
]
},
...
]
Bu veriler, aşağıdaki tabloda vurgulanan iki hücreye karşılık gelir:
İstemci kitaplıkları
İstemci kitaplıklarının nasıl yükleneceği ve yapılandırılacağıyla ilgili bir açıklama için Hızlı başlangıç kılavuzuna bakın.
Aşağıda, tarayıcı boyutuna göre özetlenmiş, ülkeye göre oturum sayısı raporu oluşturmak için bir pivot sorgu çalıştıran Python istemci kitaplığının kullanıldığı bir örnek verilmiştir.
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
DateRange,
Dimension,
Metric,
OrderBy,
Pivot,
RunPivotReportRequest,
)
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
run_pivot_report(property_id)
def run_pivot_report(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a pivot query to build a report of session counts by country,
pivoted by the browser dimension."""
client = BetaAnalyticsDataClient()
request = RunPivotReportRequest(
property=f"properties/{property_id}",
date_ranges=[DateRange(start_date="2021-01-01", end_date="2021-01-30")],
pivots=[
Pivot(
field_names=["country"],
limit=250,
order_bys=[
OrderBy(
dimension=OrderBy.DimensionOrderBy(dimension_name="country")
)
],
),
Pivot(
field_names=["browser"],
offset=3,
limit=3,
order_bys=[
OrderBy(
metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True
)
],
),
],
metrics=[Metric(name="sessions")],
dimensions=[Dimension(name="country"), Dimension(name="browser")],
)
response = client.run_pivot_report(request)
print_run_pivot_report_response(response)
def print_run_pivot_report_response(response):
"""Prints results of a runPivotReport call."""
print("Report result:")
for row in response.rows:
for dimension_value in row.dimension_values:
print(dimension_value.value)
for metric_value in row.metric_values:
print(metric_value.value)
Demo uygulama
JavaScript kullanarak bir pivot raporu nasıl oluşturacağınızı ve görüntüleyeceğinizi gösteren bir örnek için Google Analytics API v1 Pivot Report Demo uygulamasına bakın.