Halaman ini diterjemahkan oleh Cloud Translation API.

Panduan Migrasi

Panduan ini berisi 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 developer Python, gunakan library bantuan GAV4 di GitHub untuk mengonversi permintaan Google Analytics Core Reporting API v3 menjadi permintaan Analytics Reporting API v4

Endpoint

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 dan 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 Anda menggunakan Python, JavaScript, atau library klien lainnya yang mengandalkan 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 telah di-build sebelumnya, tetapi Anda dapat menggunakan layanan penemuan dan generator Google API untuk membuatnya.

Requests

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

Lihat ID

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

Contoh berikut membandingkan parameter ids dalam permintaan v3 dan 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 Dimensi.

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:

Berikan 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. Di 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 diubah 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 Segmen dan berikan ID 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 DynamicSegmen.

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

Sintaksis 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 filterExpression 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 pada v4 default kolom adalah false. Jika belum menetapkan nilai di v3, Anda perlu 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 penomoran halaman melalui 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 v3 API, 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 mengirim beberapa objek ReportRequest dalam satu permintaan HTTP, Anda mendapatkan array objek laporan dalam respons. Untuk setiap ReportRequest yang dikirim, Anda akan mendapatkan Report yang sesuai dalam respons.

Laporan

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

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

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

Header Kolom

Header kolom berisi daftar objek dimensi dan MetricHeader, yang berisi daftar objek MetricHeaderEntry. Setiap objek MetricHeaderEntry menentukan metrik name dan type-nya (mata uang, persen, dll.) , yang akan 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 dalam 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 oleh 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. Hasilnya dihitung dari hampir 500 ribu sampel ukuran ruang pengambilan sampel sekitar 15 juta sesi:

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

Mengurai respons v4

Kode contoh berikut menguraikan 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 pada v4 berbeda dengan format di v3, update kode Anda untuk menangani respons error v4.

Contoh berikut membandingkan respons error di v3 dan 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.\" }"
   }
  ]
 }
}