Google Analytics Data API v1 memungkinkan Anda membuat tabel pivot. Tabel pivot adalah alat peringkas data yang memvisualisasikan data dengan menyusun ulang informasi dalam tabel dengan memutar (memutar) data pada satu atau beberapa dimensi.
Sebagai contoh, perhatikan tabel data mentah berikut:
Dengan menggunakan data ini, Anda dapat membuat tabel pivot, yang menguraikan data sesi berdasarkan browser, dengan dimensi negara dan bahasa yang dipilih sebagai pivot tambahan.
Fitur yang Dibagikan dengan Laporan Inti
Permintaan pelaporan pivot memiliki semantik yang sama dengan permintaan laporan Inti untuk banyak fitur bersama. Misalnya, penomoran halaman, Filter Dimensi, dan Properti Pengguna, memiliki perilaku yang sama di Laporan Pivot seperti Laporan Inti. Panduan ini berfokus pada fitur pelaporan pivot. Untuk memahami fungsi Pelaporan Inti Data API v1, baca panduan dasar-dasar pelaporan, serta panduan kasus penggunaan lanjutan.
Metode pelaporan pivot
Data API v1 mendukung fungsi pivot dalam metode pelaporan berikut:
runPivotReport Metode ini menampilkan laporan pivot yang disesuaikan untuk data peristiwa Google Analytics Anda. Setiap pivot menjelaskan kolom dan baris dimensi yang terlihat dalam respons laporan.
batchRunPivotReports Ini adalah versi batch metode
runPivotReportyang memungkinkan pembuatan beberapa laporan menggunakan satu panggilan API.
Memilih Entitas Pelaporan
Semua metode Data API v1 memerlukan ID properti Google Analytics 4
untuk ditentukan di dalam jalur permintaan URL dalam bentuk
properties/GA4_PROPERTY_ID, seperti:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
Laporan yang dihasilkan akan dibuat berdasarkan data peristiwa Google Analytics yang dikumpulkan di properti Google Analytics 4 yang ditentukan.
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.
Permintaan Laporan Pivot
Untuk membuat permintaan dengan tabel pivot, gunakan metode runPivotReport atau batchRunPivotReports.
Untuk meminta data pivot, Anda dapat membuat objek RunPivotReportRequest. Sebaiknya mulai dengan parameter permintaan berikut:
- Entri yang valid di kolom dateRanges.
- Minimal satu entri yang valid di kolom dimensions.
- Minimal satu entri yang valid di kolom metrics.
- Minimal dua entri pivot yang valid di kolom pivots.
Berikut adalah contoh permintaan dengan kolom yang direkomendasikan:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [
{ "name": "browser" },
{ "name": "country" },
{ "name": "language" }
],
"metrics": [{ "name": "sessions" }],
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5
},
{
"fieldNames": [
"country"
],
"limit": 250
},
{
"fieldNames": [
"language"
],
"limit": 15
}
]
}
Pivot
Gunakan objek Pivot di kolom pivot dari isi permintaan untuk menentukan pivot laporan. Setiap Pivot menjelaskan kolom dan baris dimensi
yang terlihat dalam respons laporan.
Data API v1 mendukung beberapa pivot selama hasil parameter limit untuk setiap pivot tidak melebihi 100.000.
Di bawah ini adalah cuplikan yang menunjukkan penggunaan pivots untuk membuat laporan
jumlah sesi berdasarkan negara, yang diputar berdasarkan dimensi browser. Perhatikan bagaimana kueri menggunakan kolom orderBys untuk pengurutan, serta kolom batas dan offset untuk menerapkan penomoran halaman.
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
...
Dimensi
Dimensi mendeskripsikan dan mengelompokkan data peristiwa untuk situs atau aplikasi Anda. Dimensi city, misalnya, menunjukkan kota ("Paris"
atau "New York") tempat setiap peristiwa berasal. Dalam permintaan laporan, Anda dapat
menentukan nol atau beberapa dimensi.
Dimensi harus ditentukan di dalam kolom
dimensi
pada isi permintaan. Agar terlihat dalam laporan, dimensi tersebut juga harus
tercantum di kolom fieldNames
dari objek Pivot.
Dimensi tidak akan terlihat dalam laporan jika tidak digunakan dalam pivot kueri pivot. Tidak semua dimensi harus ada dalam fieldNames pivot. Dimensi dapat digunakan secara eksklusif di filter dan bukan di fieldNames pivot mana pun.
Di bawah ini adalah cuplikan yang menunjukkan penggunaan kolom dimension dan fieldNames untuk tabel dengan pivot browser, country, dan language:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
},
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"language"
],
"limit": 10
}
],
Metrik
Metrik adalah pengukuran kuantitatif data peristiwa untuk situs atau aplikasi Anda. Dalam permintaan laporan, Anda dapat menentukan satu atau beberapa metrik. Lihat Metrik API untuk melihat daftar lengkap nama Metrik API yang tersedia untuk ditentukan dalam permintaan.
Dalam permintaan laporan pivot, metrik ditentukan menggunakan kolom metrics dari isi permintaan, yang mirip dengan metode Pelaporan Inti.
Contoh di bawah ini menentukan jumlah sesi yang akan digunakan sebagai nilai metrik dalam laporan:
"metrics": [
{
"name": "sessions"
}
],
Agregasi metrik
Gunakan kolom metricAggregations dari objek Pivot untuk menghitung nilai metrik gabungan untuk setiap pivot.
Agregasi hanya akan dihitung jika kolom metricAggregations ditentukan dalam permintaan.
Berikut adalah cuplikan kueri yang meminta total untuk dimensi pivot browser:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
Metrik yang dihitung ditampilkan di kolom agregat pada objek RunPivotReportResponse. Untuk baris metrik gabungan, kolom dimensionValues berisi nilai khusus RESERVED_TOTAL, RESERVED_MAX, atau RESERVED_MIN.
"aggregates": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6"
}
]
},
....
}
Penomoran halaman
Serupa dengan metode Core Reporting, permintaan pivot memungkinkan Anda menentukan kolom batas dan offset dalam objek Pivot untuk menerapkan penomoran halaman.
Setelan penomoran halaman diterapkan satu per satu ke setiap pivot.
Kolom limit diperlukan untuk setiap objek Pivot agar dapat membatasi kardinalitas laporan.
Data API v1 mendukung beberapa pivot selama produk parameter limit untuk setiap pivot tidak melebihi 100.000.
Di bawah ini adalah cuplikan yang menunjukkan penggunaan kolom offset dan limit untuk
mengambil lima dimensi language berikutnya dengan offset 10:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Pemfilteran
Serupa dengan fungsi Pelaporan Inti, filter dimensi cakupan permintaan harus digunakan jika pemfilteran dimensi diinginkan dalam permintaan pelaporan pivot.
Pengurutan
Perilaku pengurutan kueri laporan pivot dapat dikontrol untuk setiap pivot secara individual menggunakan kolom orderBys dari objek Pivot yang berisi daftar objek OrderBy.
Setiap OrderBy dapat berisi salah satu 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.
Contoh ini menunjukkan cuplikan untuk definisi pivot yang mengalihkan laporan pada dimensi browser, yang mengurutkan hasil menurut metrik sessions dalam urutan menurun.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Respons Laporan
Respons Laporan Pivot untuk permintaan API laporan pivot sebagian besar berupa header dan baris.
Header Respons
Header laporan pivot terdiri dari PivotHeaders, DimensionHeaders, dan MetricHeaders yang mencantumkan kolom dalam laporan pivot.
Misalnya, laporan dengan dimensi pivot browser, country, dan language serta metrik sessions akan menghasilkan header seperti ini:
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Chrome"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "United States"
}
]
},
{
"dimensionValues": [
{
"value": "Canada"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "English"
}
]
},
{
"dimensionValues": [
{
"value": "French"
}
]
},
...
],
...
}
],
"dimensionHeaders": [
{
"name": "browser"
},
{
"name": "country"
},
{
"name": "language"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
...
}
Diagram di bawah ini mengilustrasikan peran setiap komponen Respons Laporan Pivot dalam merender laporan pivot:
Baris Respons
Respons laporan pivot untuk metode runPivotReport dan batchRunPivotReports berbeda dengan respons untuk metode Core Reporting seperti runReport dan batchRunReports karena setiap baris respons laporan pivot mewakili satu sel tabel, sedangkan di laporan reguler, satu baris respons mewakili baris tabel lengkap.
Di bawah ini adalah fragmen respons laporan pivot untuk kueri dengan dimensi pivot browser, country, dan language serta metrik sessions. Setiap sel laporan pivot ditampilkan satu per satu:
"rows": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "United States"
},
{
"value": "English"
}
],
"metricValues": [
{
"value": "1"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "Canada"
},
{
"value": "French"
}
],
"metricValues": [
{
"value": "3"
}
]
},
...
]
Data ini sesuai dengan dua sel yang disorot dalam tabel di bawah:
Library klien
Lihat Panduan memulai cepat untuk mendapatkan penjelasan tentang cara menginstal dan mengonfigurasi library klien.
Di bawah ini adalah contoh penggunaan library klien Python yang menjalankan kueri pivot untuk membuat laporan jumlah sesi berdasarkan negara, yang diputar berdasarkan dimensi browser.
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
DateRange,
Dimension,
Metric,
OrderBy,
Pivot,
RunPivotReportRequest,
)
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
run_pivot_report(property_id)
def run_pivot_report(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a pivot query to build a report of session counts by country,
pivoted by the browser dimension."""
client = BetaAnalyticsDataClient()
request = RunPivotReportRequest(
property=f"properties/{property_id}",
date_ranges=[DateRange(start_date="2021-01-01", end_date="2021-01-30")],
pivots=[
Pivot(
field_names=["country"],
limit=250,
order_bys=[
OrderBy(
dimension=OrderBy.DimensionOrderBy(dimension_name="country")
)
],
),
Pivot(
field_names=["browser"],
offset=3,
limit=3,
order_bys=[
OrderBy(
metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True
)
],
),
],
metrics=[Metric(name="sessions")],
dimensions=[Dimension(name="country"), Dimension(name="browser")],
)
response = client.run_pivot_report(request)
print_run_pivot_report_response(response)
def print_run_pivot_report_response(response):
"""Prints results of a runPivotReport call."""
print("Report result:")
for row in response.rows:
for dimension_value in row.dimension_values:
print(dimension_value.value)
for metric_value in row.metric_values:
print(metric_value.value)
Aplikasi demo
Lihat aplikasi Demo Laporan Pivot Google Analytics API v1 untuk mengetahui contoh cara membuat dan menampilkan laporan pivot menggunakan JavaScript.