Dokumen ini berisi petunjuk tentang cara melakukan migrasi kode yang ada dari Google Analytics Reporting API v4 ke Google Analytics Data API v1 dan memberikan ringkasan singkat tentang perbedaan utama antara kedua API tersebut.
Mengapa saya perlu melakukan migrasi?
Jika aplikasi Anda perlu mengakses data di properti Google Analytics 4, Anda perlu memperbarui kode untuk menggunakan Data API v1, karena Reporting API v4 hanya dapat mengakses properti yang dibuat dengan Universal Analytics.
Prasyarat
Pelajari dasar-dasar Data API v1 menggunakan panduan memulai cepat.
Memulai
Untuk memulai, Anda akan menyiapkan properti Google Analytics 4, mengaktifkan Data API v1, lalu menyiapkan library klien API yang sesuai untuk platform Anda.
Menyiapkan properti Google Analytics 4
Sebelum mulai melakukan migrasi kode untuk mendukung Data API v1, Anda harus melakukan migrasi situs untuk menggunakan properti Google Analytics 4. Properti Google Analytics 4 tidak dapat diisi ulang dengan data historis dari properti Universal Analytics.
Mengaktifkan API
Klik tombol ini untuk mengaktifkan Data API v1 secara otomatis di Project Google Cloud yang Anda pilih.
Mengaktifkan Google Analytics Data API v1Menggunakan library klien
Menginstal library klien
Jika menggunakan library klien, Anda harus menginstal library klien Data API v1 untuk bahasa pemrograman Anda.
Java
Python
Node.js
.NET
PHP
Go
go get google.golang.org/genproto/googleapis/analytics/data/v1beta
Melakukan inisialisasi pada library klien
Library klien Data API v1 didesain untuk membuat Anda memulai dengan cepat. Secara default, library klien akan otomatis mencoba menemukan kredensial akun layanan Anda.
Cara mudah untuk memberikan kredensial akun layanan adalah dengan menetapkan
variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS, klien API akan menggunakan
nilai variabel ini untuk menemukan file JSON kunci akun layanan.
Misalnya, Anda dapat menetapkan kredensial akun layanan dengan menjalankan perintah berikut dan menggunakan jalur ke file JSON akun layanan:
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Di bawah ini terdapat cuplikan kode yang biasa digunakan untuk menginisialisasi library klien Data API v1.
Java
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
Python
# Using a default constructor instructs the client to use the credentials
# specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
client = BetaAnalyticsDataClient()
.NET
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
BetaAnalyticsDataClient client = BetaAnalyticsDataClient.Create();
PHP
// Using a default constructor instructs the client to use the credentials // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable. $client = new BetaAnalyticsDataClient();
Node.js
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
const analyticsDataClient = new BetaAnalyticsDataClient();
Sebagai ganti menggunakan variabel lingkungan, Anda juga dapat meneruskan informasi kredensial ke instance klien API secara eksplisit selama inisialisasi. Di bawah ini adalah cuplikan yang digunakan untuk menginisialisasi library klien Data API v1 dengan meneruskan kredensial secara eksplisit dalam kode.
Java
// Explicitly use service account credentials by specifying
// the private key file.
GoogleCredentials credentials =
GoogleCredentials.fromStream(new FileInputStream(credentialsJsonPath));
BetaAnalyticsDataSettings betaAnalyticsDataSettings =
BetaAnalyticsDataSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credentials))
.build();
try (BetaAnalyticsDataClient analyticsData =
BetaAnalyticsDataClient.create(betaAnalyticsDataSettings)) {
Python
# TODO(developer): Uncomment this variable and replace with a valid path to
# the credentials.json file for your service account downloaded from the
# Cloud Console.
# credentials_json_path = "/path/to/credentials.json"
# Explicitly use service account credentials by specifying
# the private key file.
client = BetaAnalyticsDataClient.from_service_account_json(credentials_json_path)
.NET
/**
* TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
* Otherwise, default service account credentials will be derived from
* the GOOGLE_APPLICATION_CREDENTIALS environment variable.
*/
// credentialsJsonPath = "/path/to/credentials.json";
// Explicitly use service account credentials by specifying
// the private key file.
BetaAnalyticsDataClient client = new BetaAnalyticsDataClientBuilder
{
CredentialsPath = credentialsJsonPath
}.Build();
PHP
/**
* @param string $credentialsJsonPath Valid path to the credentials.json file for your service
* account downloaded from the Cloud Console.
* Example: "/path/to/credentials.json"
*/
function client_from_json_credentials(string $credentialsJsonPath)
{
// Explicitly use service account credentials by specifying
// the private key file.
$client = new BetaAnalyticsDataClient([
'credentials' => $credentialsJsonPath
]);
return $client;
}
Node.js
/** TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
*/
// credentialsJsonPath = '/path/to/credentials.json';
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Explicitly use service account credentials by specifying
// the private key file.
const analyticsDataClient = new BetaAnalyticsDataClient({
keyFilename: credentialsJsonPath,
});
Tidak menggunakan library klien
Jika Anda menggunakan Reporting API v4 tanpa library klien dan ingin terus melakukannya dengan Data API v1, Anda tetap dapat menggunakan kredensial Anda.
Anda harus menggunakan endpoint HTTP baru dan dokumen penemuan yang disediakan oleh Data API:
Jika kode Anda memanfaatkan Dokumen penemuan, Anda harus memperbaruinya ke dokumen penemuan yang disediakan oleh Data API v1:
Setelah memperbarui endpoint, Anda perlu memahami struktur dan konsep permintaan baru Data API untuk memperbarui kueri JSON Anda.
Pelaporan Core
Metode pelaporan yang tersedia
Reporting API v4 menawarkan satu metode batchGet untuk mengakses fungsi Pelaporan Core-nya. Data API v1 menyediakan beberapa metode Pelaporan Core yang dapat dipilih:
- runReport Metode ini menampilkan laporan data peristiwa Google Analytics yang disesuaikan. Metode ini tidak mendukung fungsi pivot dan merupakan metode pilihan untuk kueri laporan sederhana.
- runPivotReport Metode ini menampilkan laporan pivot yang disesuaikan untuk data peristiwa Google Analytics Anda. Mirip dengan pivot pada Reporting API v4, setiap pivot mendeskripsikan baris dan kolom dimensi yang terlihat dalam respons laporan.
- batchRunReports Ini adalah versi batch metode
runReportyang memungkinkan pembuatan beberapa laporan menggunakan satu panggilan API. - batchRunPivotReports Ini adalah versi batch metode
runPivotReportyang memungkinkan pembuatan beberapa laporan menggunakan satu panggilan API.
Kemudahan menjadi tujuan dari memiliki berbagai metode pelaporan, dengan beberapa metode mendukung fitur yang lebih kompleks dibanding metode lainnya (pivot, batching), tetapi membagikan struktur permintaan yang serupa.
Perubahan skema API
Kemampuan pelaporan dalam Reporting API dan Data API terutama ditentukan oleh skemanya, yaitu dimensi dan metrik yang didukung dalam kueri pelaporan. Ada perbedaan signifikan pada skema API antara kedua API, karena adanya perbedaan konseptual antara Universal Analytics dan Google Analytics 4.
- Pelajari daftar dimensi dan metrik saat ini yang didukung oleh Data API. Saat ini, semua dimensi dan metrik kompatibel satu sama lain, sehingga Anda tidak perlu menggunakan Penjelajah Dimensi dan Metrik untuk menentukan kombinasi yang kompatibel. Perilaku ini akan berubah di masa mendatang.
- Dimensi kustom di Google Analytics 4 dapat diakses menggunakan sintaksis dimensi kustom Data API v1, yang harus digunakan, dan bukan slot dimensi ga:dimensionXX Reporting API v4.
- Metrik kustom di Google Analytics 4 dapat diakses menggunakan sintaksis metrik kustom Data API v1, yang harus digunakan, bukan slot metrik ga:metricXX Reporting API v4.
- Dimensi dan metrik tertentu yang ditemukan di Universal Analytics memiliki padanan langsung di Google Analytics 4. Lihat diagram kesetaraan skema UA/GA4 API untuk informasi selengkapnya.
- Nama dimensi dan metrik tidak lagi memiliki awalan
ga:di Google Analytics 4. - Fungsi tertentu yang ada di Universal Analytics belum tersedia di GA4 (misalnya, Campaign Manager, DV360, integrasi Search Ads 360). Setelah fungsi ini diterapkan di Google Analytics 4, Data API akan mendukungnya, dimensi dan metrik baru akan ditambahkan ke skema API.
Entitas
Google Analytics 4 tidak memiliki konsep tampilan (profil) yang diperkenalkan di Universal Analytics. Akibatnya, tidak ada parameter viewId dalam permintaan pelaporan Data API v1. Sebagai gantinya, ID properti Google Analytics 4 numerik
harus ditentukan dalam jalur URL permintaan saat memanggil metode Data API v1.
Perilaku ini berbeda dengan Reporting API v4, yang mengandalkan
ID (profil) tampilan untuk mengidentifikasi entitas pelaporan.
Data API v1
Dalam kasus Data API v1, ID properti Google Analytics 4 numerik harus ditentukan di jalur URL.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
Reporting API v4
Reporting API v4 memerlukan ID tampilan (profil) Universal Analytics agar ditentukan dalam isi kueri laporan.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
....
Jika menggunakan salah satu library klien Data API, Anda tidak perlu memanipulasi jalur URL permintaan secara manual. Sebagian besar klien API menyediakan parameter property yang mengharapkan string dalam bentuk properties/GA4_PROPERTY_ID. Lihat Panduan memulai cepat untuk mengetahui contoh penggunaan library klien.
Rentang Tanggal
Reporting API v4 dan Data API v1 mendukung beberapa rentang tanggal yang ditentukan menggunakan kolom dateRanges dalam permintaan pelaporan. Kedua API memiliki
format input tanggal yang sama, menerima nilai tanggal absolut dalam bentuk
YYYY-MM-DD, atau tanggal relatif seperti yesderday, today, 7daysAgo, dsb.
Permintaan Data API v1 dibatasi hingga 4 rentang tanggal, sedangkan Reporting API v4 mengizinkan 2 rentang tanggal dalam satu permintaan laporan.
Setiap dateRange di Data API v1 mungkin memiliki kolom name opsional yang dapat digunakan untuk mereferensikan rentang tanggal yang sesuai dalam respons.
Jika name tidak disediakan, nama rentang tanggal akan dibuat secara otomatis.
Jika beberapa rentang tanggal ditentukan dalam permintaan Data API v1, dimensi dateRange baru akan otomatis ditambahkan ke respons dan nama rentang tanggal digunakan sebagai nilai dimensi. Perhatikan bahwa perilaku ini berbeda dengan Reporting API v4, yang menampilkan data untuk rentang tanggal sebagai grup nilai metrik dalam setiap baris.
Permintaan Data API v1
Kolom name opsional digunakan untuk setiap nilai dateRange dalam permintaan.
Nama rentang tanggal ini akan digunakan sebagai nilai dimensi dateRange dalam respons.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
"name": "year_ago"
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
"name": "current_year"
}
]
}
Respons Data API v1
Dimensi dateRange tambahan secara otomatis disertakan dalam respons.
Nilai dimensi dateRange berisi nama rentang tanggal, yang
berasal dari kolom dateRange.name, atau otomatis dibuat.
....
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "dateRange"
}
],
....
"rows": [
....
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "year_ago"
}
],
"metricValues": [
{
"value": "253286"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "current_year"
}
],
"metricValues": [
{
"value": "272582"
}
]
},
....
Permintaan Reporting API v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
]
}
]
}
Respons Reporting API v4
Dalam Reporting API v4, nilai untuk setiap rentang tanggal dikelompokkan di dalam
kolom metrics:
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"253286"
]
},
{
"values": [
"272582"
]
}
]
},
Pengurutan
Perilaku pengurutan kueri laporan Data API v1 dapat dikontrol menggunakan kolom orderBys, mirip dengan kolom
orderBys Reporting API v4.
Spesifikasi OrderBy telah berubah di Data API v1.
Setiap OrderBy dapat berisi salah satu dari hal berikut:
- DimensionOrderBy, mengurutkan hasil menurut nilai dimensi.
- MetricOrderBy, mengurutkan hasil menurut nilai metrik.
- PivotOrderBy, digunakan dalam kueri pivot dan mengurutkan hasil menurut nilai metrik dalam grup kolom pivot.
Jenis pengurutan DELTA, SMART, HISTOGRAM_BUCKET yang didukung oleh Reporting API v4 tidak diterapkan di Data API v1.
Jenis pengurutan OrderType.NUMERIC dari Data API v1 setara dengan nilai OrderType.DIMENSION_AS_INTEGER dari Reporting API v4.
Permintaan Data API v1
Contoh ini menunjukkan kueri sampel yang melaporkan jumlah sesi menurut negara,
yang menyusun baris menurut metrik sessions dalam urutan menurun.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Respons Data API v1
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "United States"
}
],
"metricValues": [
{
"value": "510449"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "283430"
}
]
},
....
],
"totalSize": 212,
"metadata": {}
}
Permintaan Reporting API v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"orderBys": [
{
"fieldName": "ga:sessions",
"sortOrder": "DESCENDING"
}
]
}
]
}
Respons Reporting API v4
{
"reports": [
{
....
"data": {
"rows": [
{
"dimensions": [
"United States"
],
"metrics": [
{
"values": [
"510449"
]
}
]
},
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"283430"
]
}
]
},
....
}
]
}
Pemfilteran
Klausa dimensionFilter dan metricFilter dari Data API v1 dapat digunakan untuk meminta API agar hanya menampilkan data untuk nilai dimensi atau metrik tertentu. Ini mirip dengan dimensionFilterClauses dan metricFilterClauses dari Reporting API v4.
Data API v1 tidak mendukung string ekspresi filter seperti klausa filtersExpression dalam Reporting API v4. Ekspresi ini harus ditulis ulang menggunakan klausa dimensionFilter dan metricFilter.
Permintaan Data API v1
Contoh permintaan ini menampilkan daftar jumlah sesi untuk jalur halaman tertentu yang dikunjungi oleh pengguna.
Klausa dimensionFilter
digunakan untuk hanya menampilkan baris dengan nilai dimensi pagePath
yang dimulai dengan /webstore/ dan berisi string
action=a12345.
Klausa metricFilter meminta metode runReport untuk hanya menampilkan baris dengan nilai metrik sessions
yang lebih besar dari 1.000.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "pagePath"
}
],
"dimensionFilter": {
"andGroup": {
"expressions": [
{
"filter": {
"stringFilter": {
"value": "/webstore/",
"matchType": "BEGINS_WITH"
},
"fieldName": "pagePath"
}
},
{
"filter": {
"stringFilter": {
"matchType": "CONTAINS",
"value": "action=a12345"
},
"fieldName": "pagePath"
}
}
]
}
},
"metricFilter": {
"filter": {
"numericFilter": {
"value": {
"int64Value": 1000
},
"operation": "GREATER_THAN"
},
"fieldName": "sessions"
}
},
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Permintaan Reporting API v4
Permintaan sampel ini mirip dengan contoh Data API v1. Permintaan ini menampilkan daftar jumlah sesi untuk jalur halaman tertentu yang dikunjungi oleh pengguna.
Kolom dimensionFilterClauses digunakan hanya untuk menampilkan baris dengan nilai dimensi pagePath yang dimulai dengan /webstore/ dan berisi string action=a12345.
Kolom metricFilterClauses digunakan hanya untuk menampilkan baris dengan nilai metrik ga:sessions yang lebih besar dari 1.000.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:pagePath"
}
],
"metricFilterClauses": [
{
"filters": [
{
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "1000"
}
]
}
],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:pagePath",
"operator": "BEGINS_WITH",
"expressions": [
"/webstore/"
]
},
{
"dimensionName": "ga:pagePath",
"operator": "PARTIAL",
"expressions": [
"action=a12345"
]
}
],
"operator": "AND"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
]
}
Penomoran halaman
Data API v1 menggunakan kolom batas dan offset untuk penomoran halaman melalui hasil respons yang mencakup beberapa halaman, sedangkan Reporting API v4 menggunakan pageToken dan pageSize.
Untuk permintaan pivot dari Data API v1, kolom limit dan offset dari objek Pivot harus digunakan untuk menerapkan penomoran halaman untuk setiap pivot satu per satu. Kolom limit kini diperlukan untuk setiap objek Pivot.
Secara default, Data API v1 menampilkan maksimal 10.000 baris data peristiwa, sedangkan nilai default untuk Reporting API v4 adalah 1.000 baris.
Jumlah total baris yang cocok dengan kueri yang ditampilkan menggunakan kolom rowCount sebagai respons atas Data API v1, yang serupa dengan Reporting API v4.
Permintaan Data API v1
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"limit": 5,
"offset": 15
}
Respons Data API v1
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"rowCount": 228,
}
Permintaan Reporting API v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"pageSize": 5,
"pageToken": "5"
}
]
}
Respons Reporting API v4
{
"reports": [
{
....
"data": {
"rows": [
....
],
....
"rowCount": 225,
},
"nextPageToken": "15"
}
]
}
Agregasi metrik
Data API v1 menghitung nilai agregasi hanya jika kolom metricAggregations ditentukan dalam permintaan. Sebaliknya, Reporting API v4 menampilkan nilai total, minimum, dan maksimum untuk setiap metrik secara default, kecuali jika kolom
hideTotals dan hideValueRanges ditetapkan ke true.
Permintaan Data API v1
Agregasi hanya akan dihitung jika kolom metricAggregations ditentukan dalam permintaan.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metricAggregations": [
"TOTAL",
"MAXIMUM",
"MINIMUM"
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Respons Data API v1
Baris metrik gabungan ditampilkan di kolom totals, minimum, dan maximum
dari sebuah respons. Untuk baris metrik gabungan, kolom dimensionValues berisi nilai khusus RESERVED_TOTAL, RESERVED_MAX, atau RESERVED_MIN.
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"totals": [
{
"dimensionValues": [
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6026053"
}
]
}
],
"maximums": [
{
"dimensionValues": [
{
"value": "RESERVED_MAX"
},
{
"value": "RESERVED_MAX"
}
],
"metricValues": [
{
"value": "493655"
}
]
}
],
"minimums": [
{
"dimensionValues": [
{
"value": "RESERVED_MIN"
},
{
"value": "RESERVED_MIN"
}
],
"metricValues": [
{
"value": "1"
}
]
}
],
....
}
Permintaan Reporting API v4
Contoh permintaan untuk menampilkan jumlah sesi menurut negara.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
}
]
}
Respons Reporting API v4
Kolom totals, minimums, dan maximums ada secara default dalam respons Reporting API v4.
{
"reports": [
{
"columnHeader": {
....
},
"data": {
"rows": [
....
],
....
"totals": [
{
"values": [
"4493363"
]
}
],
"minimums": [
{
"values": [
"1"
]
}
],
"maximums": [
{
"values": [
"684005"
]
}
]
}
}
]
}
Pivot
Data API v1 mendukung fungsi pivot dalam metode pelaporan runPivotReport dan batchRunPivotReports.
Reporting API v4 memungkinkan penyertaan pivot dalam kueri pelaporan menggunakan metode batchGet.
Pivot diterapkan secara berbeda dalam Data API v1 dibandingkan dengan Reporting API v4 dengan cara masing-masing baris respons mewakili satu sel tabel, sedangkan di Reporting API v4 satu baris respons mewakili seluruh baris tabel.
Data API v1
Berikut adalah fragmen respons Data API v1 untuk kueri runPivotReport. Setiap sel dari laporan pivot ditampilkan satu per satu:
"rows": [
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
Reporting API v4
Berikut adalah fragmen respons Reporting API v4 untuk kueri batchGet. Satu baris respons mewakili seluruh baris tabel yang berisi semua nilai metrik untuk pivot di pivotValueRegions:
"data": {
"rows": [
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
Di Data API v1, setiap dimensi kueri runPivotReport atau batchRunPivotReports harus ditentukan dalam objek pivot. Dimensi tidak akan terlihat dalam laporan jika tidak digunakan dalam pivot kueri pivot.
Kolom pivot Data API v1 ditentukan menggunakan kolom fieldNames, bukan kolom dimensions dalam Reporting API v4.
Filter dimensi dengan cakupan permintaan harus digunakan jika pemfilteran dimensi diinginkan dalam permintaan pelaporan Data API v1. Hal ini berbeda dengan Reporting API v4, yang menerima spesifikasi dimensionFilterClauses dalam objek pivot.
Kolom offset Data API v1 secara fungsional mirip dengan kolom startGroup Reporting API v4.
Kolom limit Data API v1 mirip dengan kolom maxGroupCount Reporting API v4 dan harus digunakan untuk membatasi kardinalitas laporan.
Data API v1 mendukung beberapa pivot selama produk parameter limit untuk setiap pivot tidak melebihi 100.000. Reporting API v4 hanya mendukung
satu dimensi pivot.
Secara default, Data API v1 mengurutkan dimensi dalam pivot berdasarkan metrik pertama dalam laporan. Perilaku ini berbeda dengan Reporting API v4, dengan urutan pivot ditentukan berdasarkan urutan menurun dari "total" metrik yang diminta. Untuk menentukan tata urutan dalam Data API v1, gunakan kolom orderBys di spesifikasi Pivot.
Permintaan Data API v1
Kueri pivot Data API v1 ini membuat laporan jumlah sesi berdasarkan negara, yang diubah berdasarkan dimensi browser. Perhatikan cara kueri menggunakan kolom orderBys, limit,
offset untuk mereproduksi perilaku kueri Reporting API v4 yang serupa untuk mempertahankan setelan pengurutan dan penomoran halaman.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
},
{
"name": "browser"
}
]
}
Respons Data API v1
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "(not set)"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
}
]
}
],
"rowCount": 234
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Safari"
}
]
},
{
"dimensionValues": [
{
"value": "Edge"
}
]
},
{
"dimensionValues": [
{
"value": "Opera"
}
]
}
],
"rowCount": 124
}
],
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "browser"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "237"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "44"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "22"
}
]
},
....
],
....
}
Permintaan Reporting API v4
Kueri pivot Reporting API v4 ini membuat laporan jumlah sesi berdasarkan negara, yang diubah berdasarkan dimensi ga:browser.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"pivots": [
{
"dimensions": [
{
"name": "ga:browser"
}
],
"startGroup": 3,
"maxGroupCount": 3,
"metrics": [
{
"expression": "ga:sessions"
}
]
}
]
}
]
}
Respons Reporting API v4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:country"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:sessions",
"type": "INTEGER"
}
],
"pivotHeaders": [
{
"pivotHeaderEntries": [
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Edge"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Opera"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Samsung Internet"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
}
],
"totalPivotGroupsCount": 19
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"(not set)"
],
"metrics": [
{
"values": [
"781283"
],
"pivotValueRegions": [
{
"values": [
"6923",
"1385",
"66"
]
}
]
}
]
},
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
{
"dimensions": [
"Algeria"
],
"metrics": [
{
"values": [
"23208"
],
"pivotValueRegions": [
{
"values": [
"19252",
"66",
"1582"
]
}
]
}
]
},
....
],
....
}
}
]
}
Kelompok
Data API v1 menggunakan spesifikasi CohortSpec untuk mengonfigurasi laporan kelompok. Ini mirip dengan spesifikasi CohortGroup di Reporting API v4.
Semua metrik yang tersedia di Data API v1 saat ini kompatibel dengan kueri kelompok, sedangkan Reporting API v4 hanya mengizinkan subkumpulan metrik khusus untuk digunakan dalam kueri kelompok.
Dalam permintaan kelompok Data API v1, metrik cohortActiveUsers diperlukan.
Data API v1 dan Reporting API v4 mengizinkan hingga 12 kelompok dalam satu permintaan.
Metrik nilai umur (LTV) saat ini tidak didukung di Data API v1.
Kesetaraan metrik kelompok
Sebagian besar metrik kelompok yang ditentukan dalam Reporting API v4 bisa diganti dengan ekspresi untuk mendapatkan hasil yang setara dalam Data API v1, sesuai diagram di bawah.
| Nama metrik Reporting API v4 | Nama atau ekspresi metrik Data API v1 |
|---|---|
| ga:cohortActiveUsers | cohortActiveUsers |
| ga:cohortTotalUsers | cohortTotalUsers |
| ga:cohortRetentionRate | "ekspresi": "cohortActiveUsers/cohortTotalUsers" |
| ga:cohortRevenuePerUser | "ekspresi": "totalRevenue/cohortActiveUsers" |
| ga:cohortVisitDurationPerUser | "ekspresi": "userEngagementDuration/cohortActiveUsers" |
| ga:cohortAppviewsPerUser | "ekspresi": "screenPageViews/cohortActiveUsers" |
| ga:cohortPageviewsPerUser | "ekspresi": "screenPageViews/cohortActiveUsers" |
| ga:cohortSessionsPerUser | "ekspresi": "sessions/cohortActiveUsers" |
| ga:cohortGoalCompletionsPerUser | "ekspresi": "eventCount/cohortActiveUsers", selain filter dimensi menurut eventName yang sesuai dengan peristiwa sasaran tercapai yang diinginkan. |
Permintaan Data API v1
Contoh kueri yang mengonfigurasi kelompok pengguna yang sesi pertamanya terjadi pada minggu yang dimulai dari 03-01-2021. Jumlah pengguna aktif dan rasio retensi pengguna dihitung untuk kelompok selama 5 minggu, menggunakan tingkat perincian WEEKLY.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"name": "cohort",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
],
"cohortsRange": {
"startOffset": 0,
"endOffset": 4,
"granularity": "WEEKLY"
}
},
"metrics": [
{
"name": "cohortActiveUsers"
},
{
"expression": "cohortActiveUsers/cohortTotalUsers",
"name": "cohortRetentionRate"
}
],
"dimensions": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
]
}
Respons Data API v1
{
"dimensionHeaders": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
],
"metricHeaders": [
{
"name": "cohortActiveUsers",
"type": "TYPE_INTEGER"
},
{
"name": "cohortRetentionRate",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0000"
}
],
"metricValues": [
{
"value": "4268816"
},
{
"value": "0.999913800857494"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0001"
}
],
"metricValues": [
{
"value": "241580"
},
{
"value": "0.056586926213534013"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0002"
}
],
"metricValues": [
{
"value": "159390"
},
{
"value": "0.037335003597877253"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0003"
}
],
"metricValues": [
{
"value": "131512"
},
{
"value": "0.030804950079453122"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0004"
}
],
"metricValues": [
{
"value": "96793"
},
{
"value": "0.022672482610259947"
}
]
}
],
"totalSize": 5,
"metadata": {}
}
Permintaan Reporting API v4
Contoh kueri yang mengonfigurasi kelompok pengguna yang sesi pertamanya terjadi pada minggu yang dimulai dari 03-01-2021. Jumlah pengguna aktif dan rasio retensi pengguna dihitung untuk kelompok selama 5 minggu, menggunakan tingkat perincian WEEKLY.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dimensions": [
{
"name": "ga:cohort"
},
{
"name": "ga:cohortNthWeek"
}
],
"metrics": [
{
"expression": "ga:cohortActiveUsers"
},
{
"expression": "ga:cohortRetentionRate"
}
],
"cohortGroup": {
"cohorts": [
{
"name": "cohort",
"type": "FIRST_VISIT_DATE",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
]
}
}
]
}
Respons Reporting API v4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:cohort",
"ga:cohortNthWeek"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:cohortActiveUsers",
"type": "INTEGER"
},
{
"name": "ga:cohortRetentionRate",
"type": "PERCENT"
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"cohort",
"0000"
],
"metrics": [
{
"values": [
"40793",
"100.0"
]
}
]
},
{
"dimensions": [
"cohort",
"0001"
],
"metrics": [
{
"values": [
"3883",
"9.518789988478416"
]
}
]
},
{
"dimensions": [
"cohort",
"0002"
],
"metrics": [
{
"values": [
"2165",
"5.307283112298679"
]
}
]
},
{
"dimensions": [
"cohort",
"0003"
],
"metrics": [
{
"values": [
"1703",
"4.174735861544873"
]
}
]
},
{
"dimensions": [
"cohort",
"0004"
],
"metrics": [
{
"values": [
"1484",
"3.637879047875861"
]
}
]
},
{
"dimensions": [
"cohort",
"0005"
],
"metrics": [
{
"values": [
"1103",
"2.7038952761503197"
]
}
]
},
{
"dimensions": [
"cohort",
"0006"
],
"metrics": [
{
"values": [
"933",
"2.28715711028853"
]
}
]
},
{
"dimensions": [
"cohort",
"0007"
],
"metrics": [
{
"values": [
"336",
"0.8236707278209496"
]
}
]
}
],
"totals": [
{
"values": [
"52400",
"16.056676390557204"
]
}
],
"rowCount": 8,
"minimums": [
{
"values": [
"336",
"0.8236707278209496"
]
}
],
"maximums": [
{
"values": [
"40793",
"100.0"
]
}
],
"isDataGolden": true
}
}
]
}
Pengambilan Sampel
Data API v1 otomatis menggunakan pengambilan sampel data saat mengantisipasi bahwa batas kardinalitas akan mengurangi kualitas data. Jika hasil untuk rentang tanggal diambil sampelnya, metadata dari RunReportResponse akan berisi SamplingMetadata yang sesuai, mirip dengan kolom samplingLevel yang ada di Reporting API v4.
Keaktualan data
Data API tidak menyediakan kolom isDataGolden yang setara dengan Reporting API v4, yang digunakan untuk menunjukkan apakah semua hit untuk laporan selesai diproses. Laporan yang sama masih dapat untuk menampilkan hasil yang berbeda saat dikuerikan di kemudian hari karena pemrosesan tambahan.
(Tidak didukung) Segmen
Segmen saat ini tidak didukung di Data API v1.
Pelaporan Real-Time
Gunakan metode properties.runRealtimeReport dalam Data API v1 untuk membuat laporan real-time bagi properti Google Analytics 4. Fungsi pelaporan real-time untuk properti Universal Analytics disediakan oleh metode data.realtime.get dari Google Analytics API v3.
Skema pelaporan real-time Data API berbeda dengan skema pelaporan real-time Analytics API v3, karena perbedaan konseptual antara Universal Analytics dan Google Analytics 4.
Permintaan Data API v1
Pada contoh berikut, untuk mempertahankan perilaku pengurutan default
Google Analytics API v3, elemen orderBy opsional telah ditambahkan ke contoh
kueri Data API v1.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }],
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
}
Respons Data API v1
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": ""
}
],
"metricValues": [
{
"value": "199"
}
]
},
{
"dimensionValues": [
{
"value": "Afghanistan"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
],
"metricValues": [
{
"value": "136"
}
]
},
....
],
"rowCount": 172
}
Permintaan Google Analytics API v3
GET https://analytics.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&metrics=rt:activeUsers&dimensions=rt:country
Respons Google Analytics API v3
{
"kind": "analytics#realtimeData",
"id": "https://www.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&dimensions=rt:country&metrics=rt:activeUsers",
"query": {
"ids": "ga:UA_VIEW_ID",
"dimensions": "rt:country",
"metrics": [
"rt:activeUsers"
],
"max-results": 10
},
"totalResults": 178,
"profileInfo": {
"profileId": "XXXXXX",
"accountId": "XXXXXX",
"webPropertyId": "UA-XXXXXX",
"profileName": "View Name",
},
"columnHeaders": [
{
"name": "rt:country",
"columnType": "DIMENSION",
"dataType": "STRING"
},
{
"name": "rt:activeUsers",
"columnType": "METRIC",
"dataType": "INTEGER"
}
],
"totalsForAllResults": {
"rt:activeUsers": "80351"
},
"rows": [
[
"(not set)",
"97"
],
[
"Afghanistan",
"2"
],
[
"Albania",
"78"
],
....
]
}
(Tidak didukung) Pelaporan aktivitas pengguna
Data API v1 saat ini tidak mendukung fungsi untuk melaporkan aktivitas pengguna individual yang mirip dengan metode userActivity.search dari Reporting API v4.
Perubahan kuota API
Kategori kuota Real-Time dan Core
Untuk tujuan kuota, Data API memiliki dua kategori permintaan: Core dan
Real-Time. Permintaan API ke metode pelaporan Core (runReport, getMetadata,
runPivotReport, batchRunReports, batchRunPivotReports) menagih kuota Core.
Permintaan API ke metode runRealtimeReport menagih kuota Real-time.
Kuota token
Selain kuota project, setiap permintaan akan memakai kuota token properti yang dikenai biaya, bergantung pada kerumitan kueri. Lihat Dokumentasi kuota Data API v1 untuk mengetahui deskripsi mendetail tentang kuota dan batas API.
Anda dapat memperoleh status saat ini dari semua kuota untuk Properti Analytics dengan menetapkan returnPropertyQuota ke true dalam permintaan pelaporan core atau real time. Status kuota akan ditampilkan di PropertyQuota.
(Tidak didukung) Kuota Berbasis Resource
Karena semua laporan inti di Google Analytics 4 didasarkan pada data tanpa sampel, Kuota Berbasis Resource yang diperkenalkan di Reporting API v4 tidak lagi berlaku, dan tidak ada padanan kolom useResourceQuotas di permintaan pelaporan Data API v1.
(Tidak didukung) Kuota permintaan per tampilan (profil) per hari
Karena tidak ada tampilan di Google Analytics 4, kuota requests per view (profile) per day tidak ada dalam Data API v1 dan digantikan oleh kuota token.