Bu kılavuzda temel raporlama API'sı v3'ü Analytics Reporting API v4'e taşıma yönergeleri yer almaktadır.
Giriş
Analytics Reporting API v4'te kullanıma sunulan yeni özelliklerden yararlanmak için kodunuzu kullanarak API'yi kullanın. Bu kılavuzda, temel raporlama API'si v3'teki istekler ve Analytics Reporting API v4'teki eşdeğer istekler, taşıma işleminizi kolaylaştırmaktadır.
Python taşıma
Python geliştiricisiyseniz, Google Analytics Core Reporting API v3 isteklerini Analytics Reporting API v4 isteklerine dönüştürmek için GitHub'daki GAV4 yardımcı kitaplığını kullanın.
Uç noktalar
Core Reporting API v3 ve Analytics Reporting API v4, farklı uç noktalara ve HTTP yöntemlerine sahiptir:
v3 Uç Nokta
GET https://www.googleapis.com/analytics/v3/data/ga
v4 Uç Noktası
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
Aşağıdaki örnekler v3'teki bir istek ile v4'teki eşdeğer isteği karşılaştırır:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users&dimensions=ga:pagePath
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
}],
"dimensions": [
{
"name":"ga:pagePath"
}]
}]
}
İstemci Kitaplıkları ve Keşif Hizmeti
Python, JavaScript veya Google Discovery Hizmetine dayalı başka bir istemci kitaplığı kullanıyorsanız Reporting API v4 için keşif dokümanının konumunu belirtmeniz gerekir.
Python
from apiclient import discovery
...
# Build the Analytics Reporting API v4 authorized service object.
analyticsReporting = discovery.build(
'analyticsreporting',
'v4',
http=http,
discoveryServiceUrl='https://analyticsreporting.googleapis.com/$discovery/rest')
JavaScript
gapi.client.load(
'https://analyticsreporting.googleapis.com/$discovery/rest',
'v4'
).then(...)
Java ve PHP istemci kitaplıkları önceden oluşturulmuştur ancak bunları oluşturmak için keşif hizmetini ve Google API'leri oluşturma aracını kullanabilirsiniz.
İstekler
API v4 referansı, istek gövdesinin yapısını ayrıntılı olarak açıklar. Aşağıdaki bölümlerde, v3 istek parametrelerinin v4 istek parametrelerine taşınması açıklanmaktadır.
Kimlikleri görüntüle
v3'te, "tablo kimliği"ni kabul eden bir ids parametresi ga:XXXX biçimindedir; burada XXXX, görünüm (profil) kimliğidir. v4'te, istek gövdesindeki viewId alanında bir görünüm (profil) kimliği belirtilir.
Aşağıdaki örnekler v3 isteğindeki ids parametresini ve v4 isteğindeki viewId alanını karşılaştırır:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
...
}]
}
Tarih Aralıkları
Analytics Reporting API v4, tek bir istekte birden fazla tarih aralığı belirtmenize olanak tanır. dateRanges alanı, DateRange nesnelerinin listesini alır.
v3'te, istekte bir tarih aralığı belirtmek için start-date ve end-date parametrelerini kullanırsınız.
Aşağıdaki örnekler v3 isteğindeki start-date ve end-date parametrelerini ve v4 isteğindeki dateRanges alanını karşılaştırır:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
....
}]
}
Metrikler
v3 metrics parametresi, Metrik nesnelerinin listesini alan v4 metrics alanına karşılık gelir.
Aşağıdaki örnekler v3 isteğindeki metrics parametrelerini ve v4 isteğindeki metrics alanını karşılaştırır:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users,ga:sessions \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
},{
"expression":"ga:sessions"
}],
...
}]
}
Boyutlar
v3 dimensions parametresi, Boyut nesnelerinin listesini alan v4 dimensions alanına karşılık gelir.
Aşağıdaki örnekler v3 isteğindeki dimensions parametrelerini ve v4 isteğindeki dimensions alanını karşılaştırır:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&dimensions=ga:country,ga:browser&... \
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"dimensions": [
{
"name":"ga:country"
},{
"name":"ga:browser"
}],
...
}]
}
Sıralama
v3 sort parametresi, OrderBy nesnelerinin listesini alan v4 orderBys alanına eş değerdir.
v4'te sonuçları bir boyut veya metrik değerine göre sıralamak için:
fieldNamealanını kullanarak adını veya takma adını girin.sortOrderalanını kullanarak sıralama sırasını (ASCENDINGveyaDESCENDING) belirtin.
Aşağıdaki örnekler bir v3 isteğindeki sort parametresini ve v4 isteğindeki orderBy alanını karşılaştırır. Bunlar, kullanıcıları azalan düzende sıralar ve kaynakları alfabetik olarak sıralar:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&sort=-ga:users,ga:source
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"orderBys": [
{
"fieldName": "ga:users",
"sortOrder": "DESCENDING"
},{
"fieldName": "ga:source"
}],
}]
}
Örnekleme Düzeyi
v3 samplingLevel parametresi, v4
samplingLevel alanına karşılık gelir. v3'te kabul edilen samplingLevel değerleri FASTER, HIGHER_PRECISION ve DEFAULT, v4'te ise kabul edilen samplingLevel değerleri SMALL, LARGE ve DEFAULT'dir.
Sürüm 3'te FASTER özelliğinin HIGHER_PRECISION sürüm 4, SMALL olarak ise LARGE olduğunu unutmayın.
Aşağıdaki örnekler v3 isteğindeki samplingLevel parametresini ve v4 isteğindeki samplingLevel alanını karşılaştırır:
v3
https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX ...\
samplingLevel=HIGHER_PRECISION
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"samplingLevel": "LARGE"
}]
}
Segmentler
v3 segment parametresi, Segment nesnelerinin listesini alan v4
segments alanına karşılık gelir.
Segment kimlikleri
v4 sürümünde, segment kimliğine göre segment istemek için bir Segment nesnesi oluşturun ve kimliğini segmentId alanı aracılığıyla sağlayın.
Aşağıdaki örnekler v3 isteğindeki segment parametresini ve v4 isteğindeki segments alanını karşılaştırır:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=gaid::-11
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "gaid::-11"
}]
}]
}
Dinamik Segmentler
v4'te, daha karmaşık segment tanımlarını belirtmek için bir DynamicSegment nesnesini içeren segments alanını kullanın.
Aşağıdaki örnekler bir v3 isteğindeki segment parametresini ve v4 isteğinde DynamicSegment nesnesi içeren segments alanını karşılaştırır:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"sessionSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:medium",
"operator": "EXACT",
"expressions": [ "referral" ]
}
}]
}]
}
}]
}
}
}]
}]
}
Koşulları ve adım dizilerini bir segmentte birleştirebilirsiniz:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=users::condition::ga:revenue>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:medium"}, {"name":"ga:segment"}],
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"userSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"metricFilter": {
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "10"
}
}]
}]
}
},
{
"sequenceSegment": {
"segmentSequenceSteps": [{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["desktop"]
}
}]
}],
"matchType": "PRECEDES"
},{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["mobile"]
}
}]
}]
}]
}
}]
}
}
}]
}]
v4 Segmentlerinde Söz Dizimi Söz Dizimi
v4 API'deki segmentId alanı, v3 API'deki segment söz dizimini destekler.
Aşağıdaki örnekler v3 isteğindeki segment parametresinin, v4'teki eşdeğer istekteki segmentId alanı tarafından nasıl desteklendiği gösterilmektedir:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "sessions::condition::ga:medium==referral"
}]
}]
}
Filtreler
v4, boyutları filtrelemek için dimensionFilterClauses ve metrikleri filtrelemek için metricFilterClauses özelliğini kullanır. dimensionFilterClauses, BoyutFiltre nesnelerinin listesini, metricFilterClauses öğesi de MetrikFiltresi nesnelerinin listesini içerir.
Aşağıdaki örnekler v3 isteğindeki filters parametresini ve v4 isteğindeki dimensionFilterClauses alanını karşılaştırır:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-06-01&end-date=2015-07-31&metrics=ga:users& \
dimensions=ga:browser&filters=ga:browser==Firefox
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:browser"}, {"name":"ga:country"}],
"dimensionFilterClauses": [{
"filters": [{
"dimension_name": "ga:browser",
"operator": "EXACT",
"expressions": ["Firefox"]
}]
}]
}]
v4'te v3 filtreleri söz dizimi
v4'teki filtersExpression alanı v3'te filters söz dizimini desteklese de boyut ve metrikleri filtrelemek için dimensionFilterClauses ve metricFilterClauses kullanın.
Aşağıdaki örnekler v3 isteğindeki filters parametresinin, v4'teki eşdeğer istekteki filtersExpression alanı tarafından nasıl desteklendiği gösterilmektedir:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga%XXXX \
&filters=ga:browser==Firefox
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"filtersExpression": "ga:browser==Firefox"
}]
}
Boş satırlar
v3 include-empty-rows parametresi, v4'teki includeEmptyRows alanına karşılık gelir. v3 parametresi varsayılan olarak true, v4 alanında ise varsayılan olarak false kullanılır. Değer v3'te ayarlanmamışsa v4'te değeri true olarak ayarlamanız gerekir.
Aşağıdaki örnekler v3 isteğindeki include-empty-rows parametresini v4 isteğindeki includeEmptyRows alanıyla karşılaştırır:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&include-empty-rows=true
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"includeEmptyRows": "true",
}]
}
Sayfalara ayırma
v4, çok sayıda sonucu sayfalara ayırmak için pageToken ve pageSize alanlarını kullanır. pageToken, bir yanıt nesnesinin nextPageToken özelliğinden elde edilir.
Aşağıdaki örnekler v3 isteğindeki start-index ve max-results parametrelerini, v4 isteğindeki pageToken ve pageSize alanlarıyla karşılaştırır:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&start-index=10001&max-results=10000
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
Standart Parametreler
Analytics Reporting API v4, userIp ve callback parametreleri hariç v3 API'deki standart sorgu parametrelerinin çoğunu destekler.
Aşağıdaki örnekler v3 isteğindeki quotaUser parametresini v4 isteğindeki değerle karşılaştırır:
v3 Uç Nokta
GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2
v4 Uç Noktası
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2
Yanıtlar
v4, tek bir HTTP isteğinde birden fazla ReportRequest nesnesi göndermenize izin verdiğinden, yanıtta bir dizi rapor nesnesi alırsınız. Gönderilen her ReportRequest için yanıta karşılık gelen bir Rapor alırsınız.
Raporlar
v4 Raporu'nda üç üst düzey alan bulunur: columnHeader, data ve nextPageToken.
v4 yanıt gövdesi, v3 yanıtında olduğu gibi tüm sorgu parametrelerine yanıt içermediğinden, istemcinin belirli bir sorgu parametresine yanıt alması için istemci uygulamasının bu parametreyi ReportRequest'e eklemesi gerekir.
Sayfalara ayırma bölümünde nextPageToken sorununu zaten ele aldık. Bu nedenle öncelikle columnHeader nesnesine bakalım.
Sütun Başlığı
Sütun başlığı,
boyutların
bir listesini ve MetricHeaderEntry
nesnelerin listesini içeren bir MetricHeader nesnesini içerir. Her bir MetricHeaderEntry
nesnesi, name metriğini ve type değerini (para birimi, yüzde vb.) belirtir
, çıkışı biçimlendirmenize yardımcı olur.
Aşağıdaki örnekler v3 yanıtındaki columnHeaders alanını v4 yanıtındaki columnHeader alanıyla karşılaştırır:
v3
"columnHeaders": [
{
"name":"ga:source",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:city",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:sessions",
"columnType":"METRIC",
"dataType":"INTEGER"
},{
"name":"ga:pageviews",
"columnType":
"METRIC",
"dataType":"INTEGER"
}
]
v4
"columnHeader": {
"dimensions": [
"ga:source",
"ga:city"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:pageviews",
"type": "INTEGER"
},
{
"name": "ga:sessions",
"type": "INTEGER"
}
]
}
},
Rapor Satırları
Core Reporting API v3, rapor verilerini, istenen boyutları ve metrikleri içeren satırlar dizisinde döndürür.
Analytics Reporting API v4, rapor verilerini, aşağıdaki şemada gösterildiği gibi her biri bir veya iki tarih aralığı içeren bir boyut satırı ve bir DateRangeValues nesnesi içeren ReportRow nesnesine döndürür.
Satırlar
v3
"rows": [
[
"google",
"Philadelphia",
"60",
"5"
],
[
"google",
"Johnstown",
"21",
"1"
],
[
"google",
"Progress",
"7",
"1"
]
],
v4
"rows": [
{
"dimensions": [
"google",
"Philadelphia"
],
"metrics": [
{
"values": [
"60",
"5"
]
}
]
},
{
"dimensions": [
"google",
"Johnstown"
],
"metrics": [
{
"values": [
"21",
"1"
]
}
]
},
{
"dimensions": [
"google",
"Progress"
],
"metrics": [
{
"values": [
"7",
"1"
]
}
]
}
],
Örneklenmiş veriler
Sonuçlar örneklenmişse Core Reporting API v3, true olarak ayarlanmış Boole alanını (containsSampledData) döndürür.
Veriler örneklenmişse Analytics Reporting API v4, boole döndürmez. Bunun yerine API, samplesReadCounts ve samplingSpaceSizes alanlarını döndürür.
Sonuçlar örneklenmezse bu alanlar tanımlanmaz.
Aşağıdaki Python örneği, bir raporun örneklenmiş veriler içerip içermediğini nasıl hesaplayacağınızı göstermektedir:
def ContainsSampledData(report):
"""Determines if the report contains sampled data.
Args:
report (Report): An Analytics Reporting API v4 response report.
Returns:
bool: True if the report contains sampled data.
"""
report_data = report.get('data', {})
sample_sizes = report_data.get('samplesReadCounts', [])
sample_spaces = report_data.get('samplingSpaceSizes', [])
if sample_sizes and sample_spaces:
return True
else:
return False
Aşağıda, iki tarih aralığı içeren bir istekten örneklenmiş verilerin yer aldığı bir örnek yanıt verilmiştir. Sonuçlar, yaklaşık 15 milyon oturumdan oluşan örnekleme alan boyutunun neredeyse 500 bin örneğinden hesaplandı:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
v4 yanıtını ayrıştırma
Aşağıdaki örnek kod, Analytics Reporting API v4 yanıtını ayrıştırır ve yazdırır:
Python
def printResponse(self, response):
"""Parses and prints the Analytics Reporting API v4 response"""
for report in response.get('reports', []):
columnHeader = report.get('columnHeader', {})
dimensionHeaders = columnHeader.get('dimensions', [])
metricHeaders = columnHeader.get('metricHeader', {}).get('metricHeaderEntries', [])
rows = report.get('data', {}).get('rows', [])
for row in rows:
dimensions = row.get('dimensions', [])
dateRangeValues = row.get('metrics', [])
for header, dimension in zip(dimensionHeaders, dimensions):
print header + ': ' + dimension
for i, values in enumerate(dateRangeValues):
print 'Date range (' + str(i) + ')'
for metricHeader, value in zip(metricHeaders, values.get('values')):
print metricHeader.get('name') + ': ' + value
Java
public static void printResponse(GetReportsResponse response) {
for (Report report: response.getReports()) {
ColumnHeader header = report.getColumnHeader();
List<String> dimensionHeaders = header.getDimensions();
List<MetricHeaderEntry> metricHeaders = header.getMetricHeader().getMetricHeaderEntries();
List<ReportRow> rows = report.getData().getRows();
for (ReportRow row: rows) {
List<String> dimensions = row.getDimensions();
List<DateRangeValues> metrics = row.getMetrics();
for (int i = 0; i < dimensionHeaders.size() && i < dimensions.size(); i++) {
System.out.println(dimensionHeaders.get(i) + ": " + dimensions.get(i));
}
for (int j = 0; j < metrics.size(); j++) {
System.out.print("Date Range (" + j + "): ");
DateRangeValues values = metrics.get(j);
for (int k = 0; k < values.size() && k < metricHeaders.size(); k++) {
System.out.println(metricHeaders.get(k).getName() + ": " + values.get(k));
}
}
}
}
}
Hata işleme
v4'teki hata yanıtı biçimi v3'teki biçimden farklı olduğundan, kodunuzu v4 hata yanıtlarını işleyecek şekilde güncelleyin.
Aşağıdaki örnekler v3'teki hata yanıtı ile v4'teki eşdeğer hata yanıtı karşılaştırılmaktadır:
v3
{
"error": {
"errors": [
{
"domain": "global",
"reason": "insufficientPermissions",
"message": "User does not have sufficient permissions for this profile.",
}
],
"code": 403,
"message": "User does not have sufficient permissions for this profile."
}
}
v4
{
"error": {
"code": 403,
"message": "User does not have sufficient permissions for this profile.",
"status": "PERMISSION_DENIED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "[ORIGINAL ERROR] generic::permission_denied: User does not have sufficient permissions for this profile. [google.rpc.error_details_ext] { message: \"User does not have sufficient permissions for this profile.\" }"
}
]
}
}