Google Analytics Data API v1, pivot tablolar oluşturmanıza olanak tanır. Pivot tablolar, verilerinizi bir veya daha fazla boyuta göre pivotlayarak (döndürerek) tablodaki bilgileri yeniden düzenleyerek verileri görselleştiren bir veri özetleme aracıdır.
Örneğin, aşağıdaki ham veri tablosunu inceleyin:
Bu verileri kullanarak, oturum verilerini tarayıcıya göre döken ve ülke ile dil boyutlarını ek pivot olarak seçen bir pivot tablo oluşturabilirsiniz.
Temel raporlarla paylaşılan özellikler
Pivot raporlama istekleri, birçok ortak özellik için Temel rapor istekleri ile aynı semantiklere sahiptir. Örneğin sayfalandırma, boyut filtreleri ve kullanıcı özellikleri, Pivot raporlarda temel raporlarla aynı şekilde çalışır. Bu kılavuzda, pivot raporlama özelliklerine odaklanılmaktadır. Data API v1'in Temel Raporlama işleviyle ilgili bilgi edinmek için raporlamayla ilgili temel bilgiler kılavuzunu ve ileri seviye kullanım alanları kılavuzunu okuyun.
Pivot 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 pivot, 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şturmaya olanak tanıyan
runPivotReportyönteminin toplu bir sürümüdür.
Raporlama birimi seçme
Data API v1'in tüm yöntemleri, Google Analytics mülk tanımlayıcısının bir URL istek yolunda properties/GA_PROPERTY_ID biçiminde belirtilmesini gerektirir. Örneğin:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
Oluşturulan rapor, belirtilen Google Analytics mülkünde toplanan Google Analytics etkinlik verilerine göre oluşturulur.
Data API istemci kitaplıklarından birini kullanıyorsanız istek URL'si yolunu manuel olarak değiştirmeniz gerekmez. Çoğu API istemcisi, properties/GA_PROPERTY_ID biçiminde bir dize bekleyen bir property parametresi sağlar. İstemci kitaplıklarının kullanım örnekleri için Hızlı başlangıç kılavuzuna göz atın.
Pivot Raporu İsteği
Pivot tablo içeren bir istek oluşturmak için runPivotReport veya batchRunPivotReports yöntemini kullanın.
Pivot verileri istemek için bir RunPivotReportRequest nesnesi oluşturabilirsiniz. Aşağıdaki 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ş.
- Pivot alanında en az iki geçerli pivot girişi.
Önerilen alanları içeren örnek bir istek aşağıda verilmiştir:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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
}
]
}
Pivot'lar
Rapor pivot'larını tanımlamak için istek gövdesinin pivot alanında Pivot nesnelerini kullanın. Her Pivot, rapor yanıtındaki görünür boyut sütunlarını ve satırlarını tanımlar.
Data API v1,her pivot için limit parametresinin çarpımı 100.000'ü aşmadığı sürece birden fazla pivot'u destekler.
Aşağıda, browser boyutuna göre ülkeye göre oturum sayısı raporu oluşturmak için pivots işlevinin kullanımını gösteren bir snippet verilmiştir. Sorgunun sıralama için orderBys alanını, sayfalandırma uygulamak için ise 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 tanımlar ve gruplandırır. Örneğin city boyutu, her etkinliğin kaynağı olan şehri ("Paris" veya "New York") belirtir. Rapor isteğinde sıfır veya daha fazla boyut belirtebilirsiniz.
Boyutlar, istek gövdesinin dimensions alanında tanımlanmalıdır. Bu boyutların bir raporda görünmesi için Pivot nesnesinin fieldNames alanında da listelenmeleri gerekir.
Bir boyut, özet sorgusunun herhangi bir özetinde kullanılmazsa raporda görünmez. Her boyut, pivot'un fieldNames'ünde bulunmayabilir. Boyutlar, herhangi bir pivot'un fieldNames bölümünde değil, yalnızca filtrelerde kullanılabilir.
Aşağıda, browser, country ve language pivot'ları içeren bir tabloda 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ızla ilgili etkinlik verilerinin nicel ölçümleridir. Rapor isteğinde bir veya daha fazla metrik belirtebilirsiniz. İsteklerde belirtilebilecek API metrik adlarının tam listesi için API Metrikleri bölümü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 örnekte, bir raporda metrik değeri olarak kullanılacak oturum sayısı belirtilmektedir:
"metrics": [
{
"name": "sessions"
}
],
Metrik toplamaları
Her pivot için toplu 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 boyutunun toplamlarını 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 özel değerini 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, sayfalandırmayı uygulamak için Pivot nesnesinde limit ve offset alanlarını belirtmenize olanak tanır.
Sayfalandırma ayarları her pivot'a ayrı ayrı uygulanır.
Rapor kardinalitesini sınırlamak için her Pivot nesnesi için limit alanı gereklidir.
Data API v1,her pivot için limit parametresinin çarpımı 100.000'i aşmadığı sürece birden fazla pivot destekler.
Aşağıda, 10 ofset ile 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 filtreleme 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 pivot için ayrı ayrı 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.
- Pivot sorgularında kullanılan ve sonuçları bir pivot sütun grubundaki bir metriğin değerlerine göre sıralayan PivotOrderBy.
Bu örnekte, raporu browser boyutunda döndüren 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
Pivot rapor API isteğinin Pivot Rapor Yanıtı, öncelikle bir başlık ve satırlardan oluşur.
Yanıt Başlıkları
Pivot rapor başlığı, pivot rapordaki sütunları listeleyen PivotHeaders, DimensionHeaders ve MetricHeaders öğelerinden oluşur.
Örneğin, browser, country ve language pivot boyutları ile sessions metriğinin yer aldığı bir raporda aşağıdaki gibi başlıklar gösterilir:
{
"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 rapor yanıtının her bir bileşeninin pivot raporu oluşturmadaki rolü gösterilmektedir:
Yanıt Satırı
runPivotReport ve batchRunPivotReports yöntemlerinin pivot rapor yanıtı, runReport ve batchRunReports gibi Temel Raporlama yöntemlerinin yanıtından farklıdır. Bunun nedeni, her pivot rapor yanıtı satırının tablonun tek bir hücresini temsil etmesidir. Normal bir raporda ise tek bir yanıt satırı, tablonun tamamını temsil eder.
Aşağıda, browser, country ve language pivot boyutları ile sessions metriğinin bulunduğu bir sorgu için pivot rapor yanıtının bir parçası verilmiştir. Pivot raporunun her hücresi ayrı ayrı 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 açıklama için Hızlı başlangıç kılavuzuna göz atın.
Aşağıdaki örneklerde, tarayıcı boyutuna göre pivot yapılan ülkeye göre oturum sayısı raporu oluşturmak için istemci kitaplığı kullanılarak bir pivot sorgusu çalıştırılır.
PHP
use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient; use Google\Analytics\Data\V1beta\DateRange; use Google\Analytics\Data\V1beta\Dimension; use Google\Analytics\Data\V1beta\Metric; use Google\Analytics\Data\V1beta\OrderBy; use Google\Analytics\Data\V1beta\OrderBy\DimensionOrderBy; use Google\Analytics\Data\V1beta\OrderBy\MetricOrderBy; use Google\Analytics\Data\V1beta\Pivot; use Google\Analytics\Data\V1beta\RunPivotReportRequest; use Google\Analytics\Data\V1beta\RunPivotReportResponse; /** * Runs a pivot query to build a report of session counts by country, * pivoted by the browser dimension. * @param string $propertyId Your GA-4 Property ID */ function run_pivot_report(string $propertyId) { // Create an instance of the Google Analytics Data API client library. $client = new BetaAnalyticsDataClient(); // Make an API call. $request = (new RunPivotReportRequest()) ->setProperty('properties/' . $propertyId) ->setDateRanges([new DateRange([ 'start_date' => '2021-01-01', 'end_date' => '2021-01-30', ]), ]) ->setPivots([ new Pivot([ 'field_names' => ['country'], 'limit' => 250, 'order_bys' => [new OrderBy([ 'dimension' => new DimensionOrderBy([ 'dimension_name' => 'country', ]), ])], ]), new Pivot([ 'field_names' => ['browser'], 'offset' => 3, 'limit' => 3, 'order_bys' => [new OrderBy([ 'metric' => new MetricOrderBy([ 'metric_name' => 'sessions', ]), 'desc' => true, ])], ]), ]) ->setMetrics([new Metric(['name' => 'sessions'])]) ->setDimensions([ new Dimension(['name' => 'country']), new Dimension(['name' => 'browser']), ]); $response = $client->runPivotReport($request); printPivotReportResponse($response); } /** * Print results of a runPivotReport call. * @param RunPivotReportResponse $response */ function printPivotReportResponse(RunPivotReportResponse $response) { print 'Report result: ' . PHP_EOL; foreach ($response->getRows() as $row) { printf( '%s %s' . PHP_EOL, $row->getDimensionValues()[0]->getValue(), $row->getMetricValues()[0]->getValue() ); } }
Python
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)
Node.js
// TODO(developer): Uncomment this variable and replace with your // Google Analytics 4 property ID before running the sample. // propertyId = 'YOUR-GA4-PROPERTY-ID'; // Imports the Google Analytics Data API client library. const {BetaAnalyticsDataClient} = require('@google-analytics/data'); // Initialize client that will be used to send requests. This client only // needs to be created once, and can be reused for multiple requests. const analyticsDataClient = new BetaAnalyticsDataClient(); // Runs a pivot query to build a report of session counts by country, pivoted by the browser dimension. async function runPivotReport() { const [response] = await analyticsDataClient.runPivotReport({ property: `properties/${propertyId}`, dateRanges: [ { startDate: '2021-01-01', endDate: '2021-01-30', }, ], pivots: [ { fieldNames: ['country'], limit: 250, orderBys: [ { dimension: { dimensionName: 'country', }, }, ], }, { fieldNames: ['browser'], offset: 3, limit: 3, orderBys: [ { metric: { metricName: 'sessions', }, desc: true, }, ], }, ], metrics: [ { name: 'sessions', }, ], dimensions: [ { name: 'country', }, { name: 'browser', }, ], }); printPivotReportResponse(response); } runPivotReport(); // Prints results of a runReport call. function printPivotReportResponse(response) { console.log('Report result:'); response.rows.forEach(row => { row.dimensionValues.forEach(dimensionValue => { console.log(dimensionValue.value); }); row.metricValues.forEach(metricValue => { console.log(metricValue.value); }); }); }
Demo uygulaması
JavaScript kullanarak pivot rapor oluşturma ve görüntüleme örneği için Google Analytics API v1 Pivot Raporu Demo uygulamasına göz atın.