Bu kılavuzda, Core Reporting API v3'ü Analytics Reporting API v4'e taşımayla ilgili yönergeler yer almaktadır.
Giriş
Analytics Reporting API v4'te sunulan yeni özelliklerden yararlanmak için kodunuzu API'yi kullanacak şekilde taşıyın. Bu kılavuzda, Core Reporting API v3'teki istekler ve Analytics Reporting API v4'teki eşdeğer istekler gösterilmektedir.
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ç Noktası
GET https://www.googleapis.com/analytics/v3/data/ga
v4 Uç Noktası
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
Aşağıdaki örneklerde, v3'teki bir istek ile v4'teki eşdeğer istek karşılaştırılmaktadı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 Service'e dayanan başka bir istemci kitaplığı kullanıyorsanız Reporting API v4 için keşif belgesinin konumunu sağlamanız 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 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ğini" 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 örneklerde, v3 isteğindeki ids
parametresi ile v4 isteğindeki viewId
alanı karşılaştırılmaktadı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 bir listesini alır.
v3'te, istekte tarih aralığı belirtmek için start-date
ve end-date
parametrelerini kullanırsınız.
Aşağıdaki örneklerde, v3 isteğindeki start-date
ve end-date
parametreleri ile v4 isteğindeki dateRanges
alanı karşılaştırılmaktadı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 bir listesini alan v4 metrics
alanına karşılık gelir.
Aşağıdaki örneklerde, v3 isteğindeki metrics
parametreleri ile v4 isteğindeki metrics
alanı karşılaştırılmaktadı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 örneklerde, v3 isteğindeki dimensions
parametreleri ile v4 isteğindeki dimensions
alanı karşılaştırılmaktadı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:
- 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 örneklerde, bir v3 isteğindeki sort
parametresi ile v4 isteğindeki orderBy
alanı karşılaştırılmaktadır. Her iki örnek de kullanıcıları azalan düzende 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. Kabul edilen samplingLevel
değerleri, v3'te FASTER
, HIGHER_PRECISION
ve DEFAULT
; v4'te ise SMALL
, LARGE
ve DEFAULT
değerleridir.samplingLevel
FASTER
özelliğinin v3'te SMALL
, v4'te HIGHER_PRECISION
yerine LARGE
olarak değiştiğini unutmayın.
Aşağıdaki örneklerde, v3 isteğindeki samplingLevel
parametresi ile v4 isteğindeki samplingLevel
alanı karşılaştırılmaktadı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'te, segment kimliğine göre bir segment istemek için bir Segment nesnesi oluşturun ve kimliğini segmentId alanı aracılığıyla sağlayın.
Aşağıdaki örneklerde, v3 isteğindeki segment
parametresi ile v4 isteğindeki segments
alanı karşılaştırılmaktadı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ı ifade etmek için bir DynamicSegment nesnesi içeren segments
alanını kullanın.
Aşağıdaki örneklerde, bir v3 isteğindeki segment
parametresi ile v4 isteğindeki DynamicSegment
nesnesi içeren segments
alanı karşılaştırılmaktadı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" ]
}
}]
}]
}
}]
}
}
}]
}]
}
Bir segmentteki koşulları ve adım sıralarını 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'te v3 Segment Söz Dizimi
v4 API'sindeki segmentId alanı, v3 API'deki segment söz dizimini destekler.
Aşağıdaki örneklerde, bir 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
, metrikleri filtrelemek için metricFilterClauses
kullanır. dimensionFilterClauses
, DimensionFilter nesnelerinin bir listesini ve metricFilterClauses
öğesi ise MetricFilter nesnelerinin bir listesini içerir.
Aşağıdaki örneklerde, v3 isteğindeki filters
parametresi ile v4 isteğindeki dimensionFilterClauses
alanı karşılaştırılmaktadı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"]
}]
}]
}]
v3, v4'te söz dizimi filtreleri
v4'teki filtersExpression
alanı, v3'teki filters
söz dizimini desteklese de boyutları ve metrikleri filtrelemek için dimensionFilterClauses
ve metricFilterClauses
kullanın.
Aşağıdaki örneklerde, bir 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 değerine, v4'te ise false değerine ayarlanır. v3'te ayarlanmış bir değer yoksa v4'te değeri true olarak ayarlamanız gerekir.
Aşağıdaki örneklerde, bir v3 isteğindeki include-empty-rows
parametresi, v4 isteğindeki includeEmptyRows
alanıyla karşılaştırılmaktadı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 alınır.
Aşağıdaki örneklerde, v3 isteğindeki start-index
ve max-results
parametreleri, v4 isteğindeki pageToken
ve pageSize
alanlarıyla karşılaştırılmaktadı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 dışında v3 API'deki standart sorgu parametrelerinin çoğunu destekler.
Aşağıdaki örneklerde, bir v3 isteğindeki quotaUser
parametresiyle bir v4 isteğindeki parametre karşılaştırılmaktadır:
v3 Uç Noktası
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 olanak tanıdığından yanıtta bir rapor nesnesi dizisi alırsınız. Gönderilen her ReportRequest için yanıtta bununla ilgili bir Rapor alırsınız.
Raporlar
4. sürüm bir raporun üç üst düzey alanı vardır: columnHeader
, data
ve nextPageToken
.
v4 yanıt gövdesi, v3 yanıtının içerdiği gibi tüm sorgu parametrelerine verilen yanıtları içermediğinden, belirli bir sorgu parametresine yanıt almak için istemci uygulamasının bu parametreyi ReportRequest'e eklemesi gerekir.
nextPageToken
öğesini Sayfalara ayırma bölümünde ele almıştık, bu nedenle önce columnHeader nesnesine bakalım.
Sütun Başlığı
Sütun başlığında, adlandırılmış boyutlar listesi ve MetricHeaderEntry nesnelerinin bir listesini içeren bir MetricHeader nesnesi bulunur. Her MetricHeaderEntry nesnesi, name
metriğini ve type
metriğini (para birimi, yüzde vb.) belirtir.
gibi bir işlev görür. Bu, çıkışı biçimlendirmenize yardımcı olur.
Aşağıdaki örneklerde, v3 yanıtındaki columnHeaders
alanı ile v4 yanıtındaki columnHeader
alanı karşılaştırılmaktadı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 rows 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 dizisi ve DateRangeValues nesneleri dizisi içeren bir ReportRow nesnesinde 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 örneklenirse Analytics Reporting API v4, bir boole döndürmez. API, samplesReadCounts
ve samplingSpaceSizes
alanlarını döndürür.
Sonuçlar örneklenmemişse bu alanlar tanımlanmaz.
Aşağıdaki Python örneğinde, bir raporun örneklenmiş veriler içerip içermediğinin nasıl hesaplanacağı gösterilmektedir:
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ığı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"],
}
}
]
}
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'tekinden farklı olduğundan, kodunuzu v4 hata yanıtlarını işleyecek şekilde güncelleyin.
Aşağıdaki örneklerde, v3'teki bir 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.\" }"
}
]
}
}