Bu belgede, mevcut kodun Google Analytics Reporting API v4'ten Google Analytics Data API v1'e nasıl taşınacağı ile ilgili talimatlar ve iki API arasındaki temel farklara kısa bir genel bakış yer almaktadır.
Neden taşıma yapmam gerekiyor?
Uygulamanızın bir Google Analytics 4 mülkündeki verilere erişmesi gerekiyorsa Reporting API v4 yalnızca Universal Analytics ile oluşturulan mülklere erişebildiğinden, kodu Data API v1'i kullanacak şekilde güncellemek gerekir.
Ön koşullar
Lütfen hızlı başlangıç kılavuzunu kullanarak Data API v1 hakkında temel bilgiler edinin.
Başlarken
Başlamak için bir Google Analytics 4 mülkü hazırlayacak, Veri API'si v1'i etkinleştirecek ve ardından platformunuza uygun bir API istemci kitaplığı oluşturacaksınız.
Google Analytics 4 mülkü hazırlama
Data API v1'i desteklemek için kodunuzu taşımaya başlamadan önce web sitenizi Google Analytics 4 mülkü kullanacak şekilde taşımanız gerekir. Google Analytics 4 mülkünü Universal Analytics mülkündeki geçmiş verilerle doldurmak mümkün değildir.
API'yi etkinleştirme
Seçili Google Cloud projenizde Data API v1'i otomatik olarak etkinleştirmek için bu düğmeyi tıklayın.
Google Analytics Data API v1'i etkinleştirinİstemci kitaplığı kullanımı
İstemci kitaplığı yükleme
İstemci kitaplığı kullanıyorsanız programlama diliniz için Data API v1 istemci kitaplığını yüklemeniz gerekir.
Java
Python
Node.js
.NET
PHP
Go
go get google.golang.org/genproto/googleapis/analytics/data/v1beta
İstemci kitaplığını başlatma
Data API v1 istemci kitaplıkları, hızlı bir başlangıç yapmanız için tasarlanmıştır. Varsayılan olarak, istemci kitaplıkları hizmet hesabı kimlik bilgilerinizi otomatik olarak bulmaya çalışır.
Hizmet hesabı kimlik bilgilerini sağlamanın kolay bir yolu, GOOGLE_APPLICATION_CREDENTIALS ortam değişkenini ayarlamaktır. API istemcisi, hizmet hesabı anahtarı JSON dosyasını bulmak için bu değişkenin değerini kullanır.
Örneğin, aşağıdaki komutu çalıştırıp hizmet hesabı JSON dosyasının yolunu kullanarak hizmet hesabı kimlik bilgilerini ayarlayabilirsiniz:
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Aşağıda, Data API v1 istemci kitaplıklarını ilk kullanıma hazırlamak için yaygın olarak kullanılan kod snippet'leri verilmiştir.
Java
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
Python
# Using a default constructor instructs the client to use the credentials
# specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
client = BetaAnalyticsDataClient()
.NET
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
BetaAnalyticsDataClient client = BetaAnalyticsDataClient.Create();
PHP
// Using a default constructor instructs the client to use the credentials // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable. $client = new BetaAnalyticsDataClient();
Node.js
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
const analyticsDataClient = new BetaAnalyticsDataClient();
Bir ortam değişkeni kullanmak yerine, kimlik bilgileri bilgilerini başlatma sırasında açıkça bir API istemci örneğine geçirmek de mümkündür. Aşağıda, kimlik bilgilerini kod içinde açıkça ileterek Data API v1 istemci kitaplıklarını başlatmak için kullanılan snippet'ler bulunmaktadır.
Java
// Explicitly use service account credentials by specifying
// the private key file.
GoogleCredentials credentials =
GoogleCredentials.fromStream(new FileInputStream(credentialsJsonPath));
BetaAnalyticsDataSettings betaAnalyticsDataSettings =
BetaAnalyticsDataSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credentials))
.build();
try (BetaAnalyticsDataClient analyticsData =
BetaAnalyticsDataClient.create(betaAnalyticsDataSettings)) {
Python
# TODO(developer): Uncomment this variable and replace with a valid path to
# the credentials.json file for your service account downloaded from the
# Cloud Console.
# credentials_json_path = "/path/to/credentials.json"
# Explicitly use service account credentials by specifying
# the private key file.
client = BetaAnalyticsDataClient.from_service_account_json(credentials_json_path)
.NET
/**
* TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
* Otherwise, default service account credentials will be derived from
* the GOOGLE_APPLICATION_CREDENTIALS environment variable.
*/
// credentialsJsonPath = "/path/to/credentials.json";
// Explicitly use service account credentials by specifying
// the private key file.
BetaAnalyticsDataClient client = new BetaAnalyticsDataClientBuilder
{
CredentialsPath = credentialsJsonPath
}.Build();
PHP
/**
* @param string $credentialsJsonPath Valid path to the credentials.json file for your service
* account downloaded from the Cloud Console.
* Example: "/path/to/credentials.json"
*/
function client_from_json_credentials(string $credentialsJsonPath)
{
// Explicitly use service account credentials by specifying
// the private key file.
$client = new BetaAnalyticsDataClient([
'credentials' => $credentialsJsonPath
]);
return $client;
}
Node.js
/** TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
*/
// credentialsJsonPath = '/path/to/credentials.json';
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Explicitly use service account credentials by specifying
// the private key file.
const analyticsDataClient = new BetaAnalyticsDataClient({
keyFilename: credentialsJsonPath,
});
İstemci kitaplığı kullanmıyorsanız
Reporting API v4'ü istemci kitaplığı olmadan kullanıyorduysanız ve Data API v1 ile kullanmaya devam etmek istiyorsanız kimlik bilgilerinizi kullanmaya devam edebilirsiniz.
Data API tarafından sağlanan yeni HTTP uç noktası ve keşif belgesini kullanmanız gerekiyor:
Kodunuz bir Keşif belgesinden yararlanıyorsa bu belgeyi Data API v1 tarafından sağlanan keşif belgesine güncellemeniz gerekir:
Uç noktayı güncelledikten sonra, JSON sorgunuzu güncellemek için yeni istek yapısı ve Data API kavramları hakkında bilgi edinmeniz gerekir.
Temel Raporlama
Kullanılabilir raporlama yöntemleri
Reporting API v4, temel raporlama işlevine erişmek için tek bir batchGet yöntemi sunuyordu. Data API v1, aralarından seçim yapabileceğiniz çeşitli Temel raporlama yöntemleri sunar:
- runReport Bu yöntem, Google Analytics etkinlik verilerinizin özelleştirilmiş bir raporunu döndürür. Özetleme işlevini desteklemez ve basit rapor sorguları için tercih edilen yöntemdir.
- runPivotReport Bu yöntem, Google Analytics etkinlik verilerinizin özelleştirilmiş bir pivot raporunu döndürür. Reporting API v4'teki özetlere benzer şekilde, her pivot rapor yanıtındaki görünür boyut sütunlarını ve satırları açıklar.
- batchRunReports Bu, tek bir API çağrısı kullanarak birden fazla rapor oluşturulmasına olanak tanıyan
runReportyönteminin toplu sürümüdür. - 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.
Birkaç raporlama yöntemine sahip olmanın amacı çoğunlukla kolaylık sağlamaktır. Bazı yöntemler diğerlerinden daha karmaşık özellikleri (pivotlar, toplu işleme) desteklerken benzer bir istek yapısını paylaşır.
API şeması değişiklikleri
Hem Reporting API hem de Data API'nin raporlama özellikleri, temel olarak şemalarına (yani raporlama sorgularında desteklenen boyutlar ve metrikler) göre belirlenir. Universal Analytics ile Google Analytics 4 arasındaki kavramsal farklılıklar nedeniyle iki API arasında API şemaları açısından önemli farklar vardır.
- Data API tarafından desteklenen güncel boyut ve metrik listesi hakkında bilgi edinin. Şu anda tüm boyutlar ve metrikler birbiriyle uyumlu olduğundan, uyumlu kombinasyonları belirlemek için Boyut ve Metrik Gezgini'ni kullanmanıza gerek yoktur. Bu davranış gelecekte değişecek.
- Google Analytics 4'teki özel boyutlara, Reporting API v4'ün ga:dimensionXX boyut slotlarının yerine kullanılması gereken Data API v1 özel boyut söz dizimi kullanılarak erişilebilir.
- Google Analytics 4'teki özel metriklere, Reporting API v4'ün ga:metricXX metrik yuvalarının yerine kullanılması gereken Data API v1 özel metrik söz dizimi kullanılarak erişilebilir.
- Universal Analytics'te bulunan belirli boyut ve metriklerin Google Analytics 4'te doğrudan eşdeğeri vardır. Daha fazla bilgi için UA/GA4 API şeması denklik grafiğine bakın.
- Google Analytics 4'te boyut ve metrik adlarının
ga:öneki artık kullanılmamaktadır. - Universal Analytics'teki belirli işlevler henüz GA4'te (ör. Campaign Manager, DV360, Search Ads 360 entegrasyonu) kullanılamamaktadır. Bu işlev Google Analytics 4'te uygulandıktan sonra Data API bu işlevi destekleyecek, yeni boyutlar ve metrikler API şemasına eklenecektir.
Varlıklar
Google Analytics 4'te, Universal Analytics'te kullanıma sunulan görünüm (profil) kavramı yoktur. Bu nedenle, Data API v1 raporlama isteklerinin hiçbir yerinde viewId parametresi yoktur. Bunun yerine, Data API v1 yöntemleri çağrılırken istek URL'si yolunda sayısal Google Analytics 4 mülk kimliği belirtilmelidir.
Bu davranış, raporlama varlığını tanımlamak için görünüm (profil) kimliklerini kullanan Reporting API v4'ten farklıdır.
Veri API'sı s1
Data API v1'de URL yolunda sayısal bir Google Analytics 4 mülk kimliği belirtilmelidir.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
Reporting API v4
Reporting API v4, rapor sorgusunun gövdesinde bir Universal Analytics görünüm (profil) kimliğinin belirtilmesini gerektirir.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
....
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.
Tarih Aralıkları
Hem Reporting API v4 hem de Data API v1, bir raporlama isteğinde dateRanges alanı kullanılarak belirtilen birden fazla tarih aralığını destekler. Her iki API de aynı tarih giriş biçimini kullanır ve mutlak tarih değerlerini YYYY-MM-DD biçiminde veya yesderday, today, 7daysAgo gibi göreli tarihleri kabul eder.
Data API v1 istekleri 4 tarih aralığıyla sınırlıdır, Reporting API v4 ise tek bir rapor isteğinde 2 tarih aralığına izin verir.
Data API v1'deki her dateRange, yanıtta ilgili tarih aralığına referans vermek için kullanılabilecek isteğe bağlı bir name alanına sahip olabilir.
name belirtilmezse tarih aralığı adı otomatik olarak oluşturulur.
Data API v1 isteğinde birden fazla tarih aralığı belirtildiğinde, yanıta otomatik olarak yeni bir dateRange boyutu eklenir ve boyut değeri olarak tarih aralığı adı kullanılır. Bu davranışın, tarih aralığı verilerini her satırda bir metrik değerler grubu olarak döndüren Reporting API v4'ten farklı olduğunu unutmayın.
Data API v1 İsteği
Bir istekteki her dateRange değeri için isteğe bağlı bir name alanı kullanılır.
Bu tarih aralığı adı, yanıtta dateRange boyutunun değeri olarak kullanılır.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
"name": "year_ago"
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
"name": "current_year"
}
]
}
Data API v1 Yanıtı
Ek bir dateRange boyutu otomatik olarak yanıta dahil edilir.
dateRange boyut değeri, dateRange.name alanından gelen veya otomatik olarak oluşturulan bir tarih aralığının adını içerir.
....
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "dateRange"
}
],
....
"rows": [
....
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "year_ago"
}
],
"metricValues": [
{
"value": "253286"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "current_year"
}
],
"metricValues": [
{
"value": "272582"
}
]
},
....
Reporting API v4 İsteği
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
]
}
]
}
Reporting API v4 Yanıtı
Reporting API v4'te, her tarih aralığına ait değerler metrics alanı içinde gruplandırılır:
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"253286"
]
},
{
"values": [
"272582"
]
}
]
},
Sıralama
Data API v1 rapor sorgularının sıralama davranışı, Reporting API v4'ün orderBys alanına benzer şekilde orderBys alanı kullanılarak kontrol edilebilir.
OrderBy spesifikasyonu, Data API v1'de değişmiştir.
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.
Reporting API v4'ün desteklediği DELTA, SMART, HISTOGRAM_BUCKET sıralama türleri, Data API v1'de uygulanmamıştır.
Data API v1'in OrderType.NUMERIC sıralama türü, Reporting API v4'ün OrderType.DIMENSION_AS_INTEGER değerine eşdeğerdir.
Data API v1 İsteği
Bu örnekte, oturum sayısını ülkeye göre raporlayan ve satırları sessions metriğine göre azalan düzende sıralayan örnek bir sorgu gösterilmektedir.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Data API v1 Yanıtı
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "United States"
}
],
"metricValues": [
{
"value": "510449"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "283430"
}
]
},
....
],
"totalSize": 212,
"metadata": {}
}
Reporting API v4 İsteği
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"orderBys": [
{
"fieldName": "ga:sessions",
"sortOrder": "DESCENDING"
}
]
}
]
}
Reporting API v4 Yanıtı
{
"reports": [
{
....
"data": {
"rows": [
{
"dimensions": [
"United States"
],
"metrics": [
{
"values": [
"510449"
]
}
]
},
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"283430"
]
}
]
},
....
}
]
}
Filtreleme
Data API v1'in dimensionFilter ve metricFilter yan tümceleri, API'den yalnızca belirli boyut veya metrik değerleri için veri döndürmesini istemek amacıyla kullanılabilir. Bu, Reporting API v4'ün dimensionFilterClauses ve metricFilterClauses ile benzer.
Data API v1, Reporting API v4'ün filtersExpression yan tümcesi gibi filtre ifadesi dizelerini desteklemez. Bu ifadeler, dimensionFilter ve metricFilter yan tümceleri kullanılarak yeniden yazılmalıdır.
Data API v1 İsteği
Bu örnek istek, kullanıcıların ziyaret ettiği belirli sayfa yolları için oturum sayılarının listesini döndürür.
dimensionFilter tümcesi, yalnızca /webstore/ ile başlayan ve action=a12345 dizesini içeren pagePath boyut değerlerine sahip satırları döndürmek için kullanılır.
metricFilter tümcesi,runReport yönteminden yalnızca sessions metrik değerleri 1.000'den büyük olan satırları döndürmesini ister.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "pagePath"
}
],
"dimensionFilter": {
"andGroup": {
"expressions": [
{
"filter": {
"stringFilter": {
"value": "/webstore/",
"matchType": "BEGINS_WITH"
},
"fieldName": "pagePath"
}
},
{
"filter": {
"stringFilter": {
"matchType": "CONTAINS",
"value": "action=a12345"
},
"fieldName": "pagePath"
}
}
]
}
},
"metricFilter": {
"filter": {
"numericFilter": {
"value": {
"int64Value": 1000
},
"operation": "GREATER_THAN"
},
"fieldName": "sessions"
}
},
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Reporting API v4 İsteği
Bu örnek istek, Data API v1 örneğine benzer. Kullanıcıların ziyaret ettiği belirli sayfa yollarına ait oturum sayılarının listesini döndürür.
dimensionFilterClauses alanı, yalnızca /webstore/ ile başlayan ve action=a12345 dizesini içeren pagePath boyut değerlerine sahip satırları döndürmek için kullanılır.
metricFilterClauses alanı,yalnızca ga:sessions metrik değerleri 1.000'den büyük olan satırları döndürmek için kullanılır.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:pagePath"
}
],
"metricFilterClauses": [
{
"filters": [
{
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "1000"
}
]
}
],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:pagePath",
"operator": "BEGINS_WITH",
"expressions": [
"/webstore/"
]
},
{
"dimensionName": "ga:pagePath",
"operator": "PARTIAL",
"expressions": [
"action=a12345"
]
}
],
"operator": "AND"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
]
}
Sayfalara ayırma
Data API v1, birden fazla sayfayı kapsayan yanıt sonuçlarını sayfalara ayırmak için limit ve ofset alanlarını kullanırken Reporting API v4 pageToken ve pageSize kullanır.
Data API v1'in pivot isteklerinde Pivot nesnesinin limit ve offset alanları, her pivot için ayrı ayrı sayfalara ayırma uygulamak amacıyla kullanılmalıdır. Artık her Pivot nesnesi için limit alanı zorunludur.
Varsayılan olarak, Data API v1 en fazla ilk 10.000 etkinlik verisi satırını döndürürken Reporting API v4'ün varsayılan değeri 1.000 satırdır.
Sorguyla eşleşen toplam satır sayısı, Data API v1'in yanıtında rowCount alanı kullanılarak döndürülür. Bu yanıt, Reporting API v4'e benzer şekilde yapılır.
Data API v1 İsteği
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"limit": 5,
"offset": 15
}
Data API v1 Yanıtı
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"rowCount": 228,
}
Reporting API v4 İsteği
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"pageSize": 5,
"pageToken": "5"
}
]
}
Reporting API v4 Yanıtı
{
"reports": [
{
....
"data": {
"rows": [
....
],
....
"rowCount": 225,
},
"nextPageToken": "15"
}
]
}
Metrik toplamaları
Data API v1, toplama değerlerini yalnızca bir istekte metricAggregations alanı belirtildiğinde hesaplar. Buna karşılık Reporting API v4, hideTotals ve hideValueRanges alanları true olarak ayarlanmadığı sürece varsayılan olarak her metrik için toplam, minimum ve maksimum değerleri döndürür.
Data API v1 İsteği
Toplamalar yalnızca, bir istekte metricAggregations alanı belirtilirse hesaplanır.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metricAggregations": [
"TOTAL",
"MAXIMUM",
"MINIMUM"
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Data API v1 Yanıtı
Birleştirilmiş metrik satırları, bir yanıtın totals, minimum ve maximum alanları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.
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"totals": [
{
"dimensionValues": [
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6026053"
}
]
}
],
"maximums": [
{
"dimensionValues": [
{
"value": "RESERVED_MAX"
},
{
"value": "RESERVED_MAX"
}
],
"metricValues": [
{
"value": "493655"
}
]
}
],
"minimums": [
{
"dimensionValues": [
{
"value": "RESERVED_MIN"
},
{
"value": "RESERVED_MIN"
}
],
"metricValues": [
{
"value": "1"
}
]
}
],
....
}
Reporting API v4 İsteği
Oturum sayısını ülkeye göre döndürmek için örnek bir istek.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
}
]
}
Reporting API v4 Yanıtı
totals, minimums ve maximums alanları Reporting API v4 yanıtında varsayılan olarak mevcuttur.
{
"reports": [
{
"columnHeader": {
....
},
"data": {
"rows": [
....
],
....
"totals": [
{
"values": [
"4493363"
]
}
],
"minimums": [
{
"values": [
"1"
]
}
],
"maximums": [
{
"values": [
"684005"
]
}
]
}
}
]
}
Pivotlar
Data API v1, runPivotReport ve batchRunPivotReports raporlama yöntemlerinde pivot işlevini destekler.
Reporting API v4, batchGet yöntemini kullanarak raporlama sorgularına pivotların eklenmesine olanak tanır.
Pivotlar, Reporting API v1'e kıyasla Data API v1'de farklı şekilde uygulanır. Her yanıt satırı, tablonun tek bir hücresini temsil eder. Reporting API v4'te ise tek bir yanıt satırı, eksiksiz bir tablo satırını temsil eder.
Veri API'sı s1
Aşağıda runPivotReport sorgusuna verilen Data API v1 yanıtının bir parçası bulunmaktadır. Özetlenmiş raporun her bir hücresi tek tek döndürülür:
"rows": [
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
Reporting API v4
Aşağıda, batchGet sorgusuna yönelik Reporting API v4 yanıtının bir parçası bulunmaktadır. Tek bir yanıt satırı, pivotValueRegions içindeki pivot noktası için tüm metrik değerlerini içeren tam bir tablo satırını temsil eder:
"data": {
"rows": [
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
Data API v1'de runPivotReport veya batchRunPivotReports sorgusunun her boyutu bir pivot nesne içinde tanımlanmalıdır. Boyut, bir pivot sorgunun özetinde kullanılmıyorsa raporda görünmez.
Data API v1'in pivot sütunları, Reporting API v4'ün dimensions alanı yerine fieldNames alanı kullanılarak belirtilir.
Data API v1 raporlama isteğinde boyut filtrelemesi isteniyorsa istek kapsamlı bir boyut filtresi kullanılmalıdır. Bu, bir pivot nesnede dimensionFilterClauses spesifikasyonunu kabul eden Reporting API v4'ten farklıdır.
Data API v1'in offset alanı, Reporting API v4'ün startGroup alanına işlevsel olarak benzer.
Data API v1'in limit alanı, Reporting API v4'ün maxGroupCount alanına benzer ve rapor kardinalitesini sınırlandırmak için kullanılmalıdır.
Her pivot için limit parametre çarpımı 100.000'i aşmadığı sürece Data API v1 birden fazla pivotu destekler. Reporting API v4 yalnızca bir pivot boyutu destekler.
Varsayılan olarak Data API v1, bir özet içindeki boyutları rapordaki ilk metriğe göre sıralar. Bu davranış, pivot sıralaması, istenen metriklerin "toplamı"nın azalan sırasına göre belirlendiği Reporting API v4'ten farklıdır. Data API v1'de sıralama düzenini belirtmek için Pivot spesifikasyonunun orderBys alanını kullanın.
Data API v1 İsteği
Bu Data API v1 pivot sorgusu, oturum sayılarını ülke bazında browser boyutuna göre özetleyen bir rapor oluşturur. Sorgunun, sıralama ve sayfalandırma ayarlarını korumak amacıyla benzer bir Reporting API v4 sorgusunun davranışını yeniden oluşturmak için orderBys, limit, offset alanlarını nasıl kullandığını unutmayın.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"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"
}
]
}
Data API v1 Yanıtı
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "(not set)"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
}
]
}
],
"rowCount": 234
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Safari"
}
]
},
{
"dimensionValues": [
{
"value": "Edge"
}
]
},
{
"dimensionValues": [
{
"value": "Opera"
}
]
}
],
"rowCount": 124
}
],
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "browser"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "237"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "44"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "22"
}
]
},
....
],
....
}
Reporting API v4 İsteği
Bu Reporting API v4 pivot sorgusu, ülkeye göre oturum sayılarının ga:browser boyutuna göre özetlendiği bir rapor oluşturur.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"pivots": [
{
"dimensions": [
{
"name": "ga:browser"
}
],
"startGroup": 3,
"maxGroupCount": 3,
"metrics": [
{
"expression": "ga:sessions"
}
]
}
]
}
]
}
Reporting API v4 Yanıtı
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:country"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:sessions",
"type": "INTEGER"
}
],
"pivotHeaders": [
{
"pivotHeaderEntries": [
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Edge"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Opera"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Samsung Internet"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
}
],
"totalPivotGroupsCount": 19
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"(not set)"
],
"metrics": [
{
"values": [
"781283"
],
"pivotValueRegions": [
{
"values": [
"6923",
"1385",
"66"
]
}
]
}
]
},
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
{
"dimensions": [
"Algeria"
],
"metrics": [
{
"values": [
"23208"
],
"pivotValueRegions": [
{
"values": [
"19252",
"66",
"1582"
]
}
]
}
]
},
....
],
....
}
}
]
}
Kohortlar
Data API v1, kohort raporlarını yapılandırmak için CohortSpec spesifikasyonunu kullanır. Bu, Reporting API v4'ün CohortGroup spesifikasyonuna benzerdir.
Data API v1'de bulunan tüm metrikler şu anda kohort sorgularıyla uyumludur, Reporting API v4 ise yalnızca bir özel metrik alt kümesinin bir kohort sorgusunda kullanılmasına izin verir.
Data API v1 kohort isteğinde cohortActiveUsers metriği gereklidir.
Hem Data API v1 hem de Reporting API v4, tek bir istekte en fazla 12 kohorta izin verir.
Yaşam boyu değer (YBD) metrikleri şu anda Data API v1'de desteklenmemektedir.
Kohort metriği denkliği
Reporting API v4'te tanımlanan kohort metriklerinin çoğu, aşağıdaki grafiğe göre Data API v1'de eşdeğer bir sonuç elde etmek için bir ifadeyle değiştirilebilir.
| Reporting API v4 metrik adı | Data API v1 metrik adı veya ifadesi |
|---|---|
| ga:cohortActiveUsers | cohortActiveUsers |
| ga:cohortTotalUsers | cohortTotalUsers |
| ga:cohortRetentionRate | "expression": "cohortActiveUsers/cohortTotalUsers" |
| ga:cohortRevenuePerUser | "expression": "totalRevenue/cohortActiveUsers" |
| ga:cohortVisitDurationPerUser | "expression": "userEngagementDuration/cohortActiveUsers" |
| ga:cohortAppviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortPageviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortSessionsPerUser | "expression": "sessions/cohortActiveUsers" |
| ga:cohortGoalCompletionsPerUser | "expression": "eventCount/cohortActiveUsers" ve istenen hedef tamamlama etkinliğine karşılık gelen eventName boyut filtresi. |
Data API v1 İsteği
İlk oturumu 03.01.2021'de gerçekleşen bir kullanıcı grubunu yapılandıran örnek sorgu. Etkin kullanıcı sayısı ve kullanıcıları elde tutma oranı, WEEKLY ayrıntı düzeyi kullanılarak kohort için 5 hafta boyunca hesaplanır.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"name": "cohort",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
],
"cohortsRange": {
"startOffset": 0,
"endOffset": 4,
"granularity": "WEEKLY"
}
},
"metrics": [
{
"name": "cohortActiveUsers"
},
{
"expression": "cohortActiveUsers/cohortTotalUsers",
"name": "cohortRetentionRate"
}
],
"dimensions": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
]
}
Data API v1 Yanıtı
{
"dimensionHeaders": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
],
"metricHeaders": [
{
"name": "cohortActiveUsers",
"type": "TYPE_INTEGER"
},
{
"name": "cohortRetentionRate",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0000"
}
],
"metricValues": [
{
"value": "4268816"
},
{
"value": "0.999913800857494"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0001"
}
],
"metricValues": [
{
"value": "241580"
},
{
"value": "0.056586926213534013"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0002"
}
],
"metricValues": [
{
"value": "159390"
},
{
"value": "0.037335003597877253"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0003"
}
],
"metricValues": [
{
"value": "131512"
},
{
"value": "0.030804950079453122"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0004"
}
],
"metricValues": [
{
"value": "96793"
},
{
"value": "0.022672482610259947"
}
]
}
],
"totalSize": 5,
"metadata": {}
}
Reporting API v4 İsteği
İlk oturumu 03.01.2021'de gerçekleşen bir kullanıcı grubunu yapılandıran örnek sorgu. Etkin kullanıcı sayısı ve kullanıcıları elde tutma oranı, WEEKLY ayrıntı düzeyi kullanılarak kohort için 5 hafta boyunca hesaplanır.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dimensions": [
{
"name": "ga:cohort"
},
{
"name": "ga:cohortNthWeek"
}
],
"metrics": [
{
"expression": "ga:cohortActiveUsers"
},
{
"expression": "ga:cohortRetentionRate"
}
],
"cohortGroup": {
"cohorts": [
{
"name": "cohort",
"type": "FIRST_VISIT_DATE",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
]
}
}
]
}
Reporting API v4 Yanıtı
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:cohort",
"ga:cohortNthWeek"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:cohortActiveUsers",
"type": "INTEGER"
},
{
"name": "ga:cohortRetentionRate",
"type": "PERCENT"
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"cohort",
"0000"
],
"metrics": [
{
"values": [
"40793",
"100.0"
]
}
]
},
{
"dimensions": [
"cohort",
"0001"
],
"metrics": [
{
"values": [
"3883",
"9.518789988478416"
]
}
]
},
{
"dimensions": [
"cohort",
"0002"
],
"metrics": [
{
"values": [
"2165",
"5.307283112298679"
]
}
]
},
{
"dimensions": [
"cohort",
"0003"
],
"metrics": [
{
"values": [
"1703",
"4.174735861544873"
]
}
]
},
{
"dimensions": [
"cohort",
"0004"
],
"metrics": [
{
"values": [
"1484",
"3.637879047875861"
]
}
]
},
{
"dimensions": [
"cohort",
"0005"
],
"metrics": [
{
"values": [
"1103",
"2.7038952761503197"
]
}
]
},
{
"dimensions": [
"cohort",
"0006"
],
"metrics": [
{
"values": [
"933",
"2.28715711028853"
]
}
]
},
{
"dimensions": [
"cohort",
"0007"
],
"metrics": [
{
"values": [
"336",
"0.8236707278209496"
]
}
]
}
],
"totals": [
{
"values": [
"52400",
"16.056676390557204"
]
}
],
"rowCount": 8,
"minimums": [
{
"values": [
"336",
"0.8236707278209496"
]
}
],
"maximums": [
{
"values": [
"40793",
"100.0"
]
}
],
"isDataGolden": true
}
}
]
}
Örneklendirme
Data API v1, kardinalite sınırlarının veri kalitesini düşüreceğini tahmin ettiğinde otomatik olarak veri örneklemeyi kullanır. Bir tarih aralığının sonuçları örneklenirse RunReportResponse öğesinin metadata değeri, Reporting API v4'te mevcut olan samplingLevel alanına karşılık gelen bir SamplingMetadata öğesi içerir.
Veri güncelliği
Data API, Reporting API v4'ün isDataGolden alanının eşdeğerini sağlamaz. Bu alan, bir rapordaki tüm isabetlerin işlenmesinin tamamlandığını belirtmek için kullanılır. Ek işlemler nedeniyle daha sonraki bir tarihte sorgulandığında aynı raporun farklı sonuçlar döndürmesi mümkündür.
(Desteklenmez) Segmentler
Segmentler şu anda Data API v1'de desteklenmemektedir.
Gerçek Zamanlı raporlama
Google Analytics 4 mülkleri için gerçek zamanlı raporlar oluşturmak amacıyla Data API v1'in properties.runRealtimeReport yöntemini kullanın. Universal Analytics mülkleri için gerçek zamanlı raporlama işlevi, Google Analytics API v3'ün data.realtime.get yöntemi ile sağlanmıştır.
Data API gerçek zamanlı raporlama şeması, Universal Analytics ile Google Analytics 4 arasındaki kavramsal farklılıklar nedeniyle Analytics API v3'ün gerçek zamanlı raporlama şemasından farklıdır.
Data API v1 İsteği
Aşağıdaki örnekte, Google Analytics API v3'ün varsayılan sıralama davranışını korumak için örnek Data API v1 sorgusuna isteğe bağlı bir orderBy öğesi eklendi.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }],
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
}
Data API v1 Yanıtı
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": ""
}
],
"metricValues": [
{
"value": "199"
}
]
},
{
"dimensionValues": [
{
"value": "Afghanistan"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
],
"metricValues": [
{
"value": "136"
}
]
},
....
],
"rowCount": 172
}
Google Analytics API v3 İsteği
GET https://analytics.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&metrics=rt:activeUsers&dimensions=rt:country
Google Analytics API v3 Yanıtı
{
"kind": "analytics#realtimeData",
"id": "https://www.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&dimensions=rt:country&metrics=rt:activeUsers",
"query": {
"ids": "ga:UA_VIEW_ID",
"dimensions": "rt:country",
"metrics": [
"rt:activeUsers"
],
"max-results": 10
},
"totalResults": 178,
"profileInfo": {
"profileId": "XXXXXX",
"accountId": "XXXXXX",
"webPropertyId": "UA-XXXXXX",
"profileName": "View Name",
},
"columnHeaders": [
{
"name": "rt:country",
"columnType": "DIMENSION",
"dataType": "STRING"
},
{
"name": "rt:activeUsers",
"columnType": "METRIC",
"dataType": "INTEGER"
}
],
"totalsForAllResults": {
"rt:activeUsers": "80351"
},
"rows": [
[
"(not set)",
"97"
],
[
"Afghanistan",
"2"
],
[
"Albania",
"78"
],
....
]
}
(Desteklenmez) Kullanıcı etkinliği raporlaması
Data API v1, Reporting API v4'ün userActivity.search yöntemine benzer bireysel kullanıcı etkinliklerini bildirme işlevini şu anda desteklememektedir.
API kotası değişiklikleri
Temel ve Gerçek zamanlı kota kategorileri
Kota amaçları doğrultusunda Data API'nin iki istek kategorisi vardır: Temel ve Gerçek zamanlı. Temel raporlama yöntemlerine (runReport, getMetadata, runPivotReport, batchRunReports, batchRunPivotReports) gönderilen API istekleri temel kotalar için ücret alır.
runRealtimeReport yöntemine gönderilen API isteklerinden Gerçek zamanlı kotalar ücret alınır.
Jeton kotaları
Proje kotalarına ek olarak her istek, sorgunun karmaşıklığına bağlı olarak ücretlendirilen mülk jeton kotalarını tüketir. API kotaları ve sınırlarının ayrıntılı açıklaması için lütfen Data API v1 kotaları belgelerine bakın.
Temel veya gerçek zamanlı bir raporlama isteğinde returnPropertyQuota öğesini true olarak ayarlayarak bir Analytics Mülkü için tüm kotaların mevcut durumunu almak mümkündür. Kota durumu, PropertyQuota öğesinde döndürülür.
(Desteklenmiyor) Kaynak Tabanlı Kota
Google Analytics 4'teki tüm temel raporlar örneklenmemiş verilere dayalı olduğundan Reporting API v4'te kullanıma sunulan Kaynak Tabanlı Kota artık geçerli değildir ve Data API v1 raporlama isteğinde useResourceQuotas alanının eşdeğeri yoktur.
(Desteklenmez) Günlük görüntüleme (profil) başına istek kotası
Google Analytics 4'te görünüm olmadığından Data API v1'de requests per view (profile) per day kotası yoktur ve bunun yerine jeton kotaları uygulanır.