Taşıma Rehberi

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

v3 referans belgeleri

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

v4 referans belgeleri

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 veya DESCENDING) 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:

Rapor Satırları

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.\" }"
   }
  ]
 }
}