Panduan Migrasi

Panduan ini memberikan panduan untuk melakukan migrasi Core Reporting API v3 ke Analytics Reporting API v4.

Pengantar

Untuk memanfaatkan fitur baru yang diperkenalkan di Analytics Reporting API v4, migrasikan kode Anda untuk menggunakan API. Panduan ini menunjukkan permintaan di Core Reporting API v3 dan permintaan yang setara di Analytics Reporting API v4 untuk mempermudah migrasi Anda.

Migrasi Python

Jika Anda adalah developer Python, gunakan library bantuan GAV4 di GitHub untuk mengonversi permintaan Google Analytics Core Reporting API v3 menjadi permintaan Analytics Reporting API v4

Endpoints

Core Reporting API v3 dan Analytics Reporting API v4 memiliki endpoint dan metode HTTP yang berbeda:

Endpoint v3

GET https://www.googleapis.com/analytics/v3/data/ga

Endpoint v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet

Contoh berikut membandingkan permintaan di v3 dengan permintaan yang setara di v4:

v3

Dokumentasi referensi 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

Dokumentasi referensi 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"
    }]
  }]
}

Library Klien dan Layanan Penemuan

Jika menggunakan Python, JavaScript, atau library klien lainnya yang bergantung pada Google Discovery Service, Anda harus memberikan lokasi dokumen discovery untuk Reporting API v4.

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(...)

Library klien Java dan PHP sudah di-build sebelumnya, tetapi Anda dapat menggunakan layanan discovery dan generator Google API untuk membuatnya.

Permintaan

Referensi API v4 menjelaskan struktur isi permintaan secara mendetail. Bagian berikut menjelaskan migrasi parameter permintaan v3 ke parameter permintaan v4.

ID Tampilan

Di v3, parameter ids, yang menerima "ID tabel", menggunakan format ga:XXXX, dengan XXXX adalah ID tampilan (profil). Di v4, ID tampilan (profil) ditentukan di kolom viewId dalam isi permintaan.

Contoh berikut membandingkan parameter ids dalam permintaan v3 dengan kolom viewId dalam permintaan v4:

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

Rentang Tanggal

Analytics Reporting API v4 memungkinkan Anda menentukan beberapa rentang tanggal dalam satu permintaan. Kolom dateRanges mengambil daftar objek DateRange. Di v3, Anda menggunakan parameter start-date dan end-date untuk menentukan rentang tanggal dalam permintaan.

Contoh berikut membandingkan parameter start-date dan end-date dalam permintaan v3 dan kolom dateRanges dalam permintaan v4:

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

Metrik

Parameter metrics v3 sesuai dengan kolom metrics v4 yang mengambil daftar objek Metrik.

Contoh berikut membandingkan parameter metrics dalam permintaan v3 dan kolom metrics dalam permintaan v4:

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

Dimensi

Parameter dimensions v3 sesuai dengan kolom dimensions v4 yang mengambil daftar objek Dimension.

Contoh berikut membandingkan parameter dimensions dalam permintaan v3 dan kolom dimensions dalam permintaan v4:

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

Pengurutan

Parameter sort v3 setara dengan kolom orderBys v4 yang mengambil daftar objek OrderBy.

Di v4, untuk mengurutkan hasil menurut nilai dimensi atau metrik:

  • Masukkan nama atau aliasnya melalui kolom fieldName.
  • Tentukan tata urutan (ASCENDING atau DESCENDING) melalui kolom sortOrder.

Contoh berikut membandingkan parameter sort dalam permintaan v3 dan kolom orderBy dalam permintaan v4; keduanya mengurutkan pengguna dalam urutan menurun dan sumber menurut abjad:

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"
    }],
  }]
}

Tingkat Pengambilan Sampel

Parameter samplingLevel v3 sesuai dengan kolom samplingLevel v4. Pada v3, nilai samplingLevel yang diterima adalah FASTER, HIGHER_PRECISION, dan DEFAULT; dan di v4, nilai samplingLevel yang diterima adalah SMALL, LARGE, dan DEFAULT. Perhatikan bahwa FASTER di v3 telah berubah menjadi SMALL di v4, HIGHER_PRECISION menjadi LARGE.

Contoh berikut membandingkan parameter samplingLevel dalam permintaan v3 dan kolom samplingLevel dalam permintaan v4:

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

Segmen

Parameter segment v3 sesuai dengan kolom segments v4 yang mengambil daftar objek Segmen.

ID segmen

Di v4, untuk meminta segmen berdasarkan ID segmen, buat objek Segment dan berikan ID-nya melalui kolom segmentId.

Contoh berikut membandingkan parameter segment dalam permintaan v3 dan kolom segments dalam permintaan v4:

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

Segmen Dinamis

Di v4, untuk mengekspresikan definisi segmen yang lebih rumit, gunakan kolom segments yang menyertakan objek DynamicSegment.

Contoh berikut membandingkan parameter segment dalam permintaan v3 dan kolom segments yang berisi objek DynamicSegment dalam permintaan v4:

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

Anda dapat menggabungkan kondisi dan urutan dalam sebuah segmen:

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

Sintaks Segmen v3 di v4

Kolom segmentId di API v4 mendukung sintaksis segmen di API v3.

Contoh berikut menunjukkan bagaimana parameter segment dalam permintaan v3 didukung oleh kolom segmentId dalam permintaan yang setara di v4:

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

Filter

v4 menggunakan dimensionFilterClauses untuk memfilter dimensi dan metricFilterClauses untuk memfilter metrik. dimensionFilterClauses berisi daftar objek DimensionFilter; dan metricFilterClauses berisi daftar objek MetricFilter.

Contoh berikut membandingkan parameter filters dalam permintaan v3 dan kolom dimensionFilterClauses dalam permintaan v4:

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

Sintaksis filter v3 di v4

Meskipun kolom filtersExpression di v4 mendukung sintaksis filters di v3, gunakan dimensionFilterClauses dan metricFilterClauses untuk memfilter dimensi dan metrik.

Contoh berikut menunjukkan bagaimana parameter filters dalam permintaan v3 didukung oleh kolom filtersExpression dalam permintaan yang setara di v4:

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

Baris kosong

Parameter include-empty-rows v3 sesuai dengan kolom includeEmptyRows di v4. Parameter v3 ditetapkan secara default ke true, sedangkan di v4, kolom ditetapkan secara default ke false. Jika tidak memiliki nilai yang ditetapkan di v3, Anda harus menetapkan nilai ke true di v4.

Contoh berikut membandingkan parameter include-empty-rows dalam permintaan v3 dengan kolom includeEmptyRows dalam permintaan v4:

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",
  }]
}

Penomoran halaman

v4 menggunakan kolom pageToken dan pageSize untuk memberi nomor pada sejumlah besar hasil. pageToken diperoleh dari properti nextPageToken objek respons.

Contoh berikut membandingkan parameter start-index dan max-results dalam permintaan v3 dengan kolom pageToken dan pageSize dalam permintaan v4:

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",
  }]
}

Parameter Standar

Analytics Reporting API v4 mendukung sebagian besar parameter kueri standar di API v3, kecuali untuk parameter userIp dan callback.

Contoh berikut membandingkan parameter quotaUser dalam permintaan v3 dengan parameter dalam permintaan v4:

Endpoint v3

GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2

Endpoint v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2

Respons

Karena v4 memungkinkan Anda untuk mengirim beberapa objek ReportRequest dalam satu permintaan HTTP, Anda akan mendapatkan array objek laporan dalam respons. Untuk setiap ReportRequest yang dikirim, Anda akan mendapatkan Laporan yang sesuai dalam respons.

Laporan

Report v4 memiliki tiga kolom level teratas: columnHeader, data, dan nextPageToken.

Karena isi respons v4 tidak menyertakan respons terhadap semua parameter kueri seperti halnya respons v3, untuk mendapatkan respons terhadap parameter kueri tertentu, aplikasi klien harus menambahkan parameter tersebut ke ReportRequest.

Kita telah mengatasi nextPageToken di bagian Penomoran halaman, jadi mari lihat objek columnHeader terlebih dahulu.

Header Kolom

Header kolom berisi daftar dimensions bernama dan objek MetricHeader, yang berisi daftar objek MetricHeaderEntry. Setiap objek MetricHeaderEntry menentukan metrik name dan type-nya (mata uang, persen, dll.) , yang membantu Anda memformat output.

Contoh berikut membandingkan kolom columnHeaders dalam respons v3 dengan kolom columnHeader dalam respons v4:

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"
            }
        ]
    }
},

Baris Laporan

Core Reporting API v3 menampilkan data laporan di array baris yang berisi dimensi dan metrik yang diminta.

Analytics Reporting API v4 menampilkan data laporan dalam objek ReportRow yang berisi array dimensi dan array objek DateRangeValues, yang masing-masing berisi satu atau dua rentang tanggal, seperti yang ditunjukkan diagram berikut:

Baris Laporan

Baris

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"
                ]
            }
        ]
    }
],

Contoh data

Jika hasilnya diambil sampelnya, Core Reporting API v3 akan menampilkan kolom boolean containsSampledData, yang ditetapkan ke true.

Analytics Reporting API v4 tidak menampilkan boolean jika data diambil sampelnya; tetapi API menampilkan kolom samplesReadCounts dan samplingSpaceSizes. Jika hasilnya tidak diambil sampelnya, kolom ini tidak akan ditentukan. Contoh Python berikut menunjukkan cara menghitung apakah laporan berisi data sampel:

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

Berikut adalah contoh respons yang berisi sampel data dari permintaan dengan dua rentang tanggal. Hasil dihitung dari hampir 500 ribu sampel dengan ukuran ruang pengambilan sampel sekitar 15 juta sesi:

{
  "reports":
  [
    {
      "columnHeader": {
        ...
      },
      "data": {
        ...
        "samplesReadCounts": [ "499630","499630"],
        "samplingSpaceSizes": ["15328013","15328013"],
      }
    }
  ]
}

Mengurai respons v4

Kode contoh berikut mengurai dan mencetak respons Analytics Reporting API v4:

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));
        }
      }
    }
  }
}

Penanganan error

Karena format respons error di v4 berbeda dengan yang ada di v3, perbarui kode Anda untuk menangani respons error v4.

Contoh berikut membandingkan respons error di v3 dengan respons error yang setara di v4:

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