Dokumen ini menyediakan referensi lengkap untuk kueri dan respons untuk Multi-Channel Funnels Reporting API.
Pengantar
Multi-Channel Funnels Reporting API memungkinkan Anda meminta data laporan Funnel Multisaluran Google Analytics. Setiap laporan terdiri dari statistik yang berasal dari data yang dikirim kembali oleh kode pelacakan ke Analytics, yang disusun sebagai dimensi dan metrik. Dengan memilih kombinasi dimensi dan metrik sendiri, Anda dapat menggunakan Reporting API untuk membuat laporan yang disesuaikan dengan spesifikasi Anda sendiri.
API berisi satu metode yang meminta data laporan: report.get. Dengan metode ini, Anda memberikan ID tabel yang sesuai dengan tampilan (profil) yang datanya ingin Anda ambil. Selain itu, Anda menentukan hal berikut:
- Kombinasi dimensi dan metrik.
- Rentang tanggal.
- Kumpulan parameter opsi yang mengontrol data yang ditampilkan
API akan membuat metode report.get tersedia di endpoint REST: https://www.googleapis.com/analytics/v3/data/mcf. Bagian berikut menunjukkan contoh permintaan dan menjelaskan masing-masing parameter.
Permintaan
API menyediakan satu metode untuk meminta data:
analytics.data.mcf.get()
Kueri juga dapat dikueri sebagai endpoint REST:
Authorization: Bearer {oauth2-token} GET https://www.googleapis.com/analytics/v3/data/mcf ?ids=ga:12345 &metrics=mcf:totalConversions,mcf:totalConversionValue &start-date=2011-10-01 &end-date=2011-10-31
Setiap parameter kueri URL menentukan parameter kueri API yang harus dienkode ke URL.
Semua Permintaan ke Multi-Channel Funnels Reporting API harus diizinkan, sebaiknya melalui OAuth 2.0.
Ringkasan Parameter Kueri
Tabel berikut merangkum semua parameter kueri yang diterima oleh Multi-Channel Funnels Reporting API. Klik setiap nama parameter untuk deskripsi mendetail.
Name | Nilai | Wajib | Ringkasan |
---|---|---|---|
ids |
string |
ya | ID tabel unik dalam bentuk ga:XXXX, XXXX adalah ID tampilan (profil) Analytics yang kuerinya akan mengambil data. |
start-date |
string |
ya |
Tanggal mulai untuk mengambil data Analytics. Permintaan dapat menentukan tanggal mulai
yang diformat sebagai YYYY-MM-DD , atau sebagai tanggal relatif
(mis., today , yesterday , atau NdaysAgo dengan N berupa bilangan bulat positif).
|
end-date |
string |
ya |
Tanggal akhir untuk mengambil data Analytics. Permintaan dapat menentukan tanggal akhir
yang diformat sebagai YYYY-MM-DD , atau sebagai tanggal relatif (misalnya,
today , yesterday , atau NdaysAgo dengan N sebagai bilangan bulat positif).
|
metrics |
string |
ya | Daftar metrik yang dipisahkan koma, seperti
mcf:totalConversions,mcf:totalConversionValue .
Kueri yang valid harus menentukan setidaknya satu metrik. |
dimensions |
string |
tidak | Daftar dimensi yang dipisahkan koma untuk laporan Funnel Multisaluran,
seperti mcf:source,mcf:keyword . |
sort |
string |
tidak | Daftar dimensi dan metrik yang dipisahkan koma yang menunjukkan tata urutan dan arah pengurutan untuk data yang ditampilkan. |
filters |
string |
tidak | Filter dimensi atau metrik yang membatasi data yang ditampilkan untuk permintaan Anda. |
samplingLevel |
string |
tidak | Level pengambilan sampel yang diinginkan. Nilai yang Diizinkan:
|
start-index |
integer |
tidak | Baris data pertama yang akan diambil, mulai dari 1.
Gunakan parameter ini sebagai mekanisme penomoran halaman bersama dengan
parameter max-results . |
max-results |
integer |
tidak | Jumlah maksimum baris untuk disertakan dalam respons. |
Detail Parameter Kueri
id
ids=ga:12345
ga:
dengan
ID tampilan (profil) laporan. Anda dapat mengambil ID tampilan (profil) untuk
laporan
menggunakan metode analytics.management.profiles.list
,
yang menyediakan id
di resource Tampilan (Profil) di
Google Analytics Management API.
tanggal mulai
start-date=2011-10-01
start-date
dan end-date
dalam permintaan, server akan menampilkan error.
Nilai tanggal dapat ditetapkan untuk tanggal tertentu menggunakan pola
YYYY-MM-DD
atau relatif menggunakan pola today
,
yesterday
, atau NdaysAgo
.
Nilai harus cocok dengan
[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
.
start-date
paling awal yang valid adalah 2011-01-01
.
Tidak ada pembatasan atas untuk start-date
.Contoh rentang tanggal untuk 7 hari terakhir (mulai kemarin) menggunakan tanggal relatif:
&start-date=7daysAgo &end-date=yesterday
tanggal akhir
end-date=2011-10-31
start-date
dan end-date
dalam permintaan, server akan menampilkan error.
Nilai tanggal dapat ditetapkan untuk tanggal tertentu menggunakan pola
YYYY-MM-DD
atau relatif menggunakan pola today
,
yesterday
, atau NdaysAgo
.
Nilai harus cocok dengan
[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo)
.
end-date
yang paling awal dan valid adalah
2005-01-01
. Tidak ada batasan atas untuk
end-date
. Contoh rentang tanggal untuk 10 hari terakhir (mulai hari ini) menggunakan tanggal relatif:
&start-date=9daysAgo &end-date=today
dimensi
dimensions=mcf:source,mcf:keyword
Parameter dimensi menentukan kunci data utama untuk laporan Funnel Multisaluran Anda, seperti mcf:source
atau mcf:medium
.
Gunakan dimensi untuk menyegmentasikan metrik konversi Anda. Misalnya, meskipun Anda
dapat meminta jumlah total konversi ke situs Anda, mungkin akan lebih menarik
untuk menanyakan jumlah konversi yang disegmentasikan menurut media.
Dalam hal ini, Anda akan melihat jumlah konversi dari organik, rujukan,
email, dan sebagainya.
Saat menggunakan dimensions
dalam permintaan data, perhatikan batasan berikut:
- Anda dapat memberikan maksimal 7 dimensi dalam kueri apa pun.
- Anda tidak dapat mengirim kueri yang hanya terdiri dari dimensi: Anda harus menggabungkan setiap dimensi yang diminta dengan setidaknya satu metrik.
Nilai Tidak Tersedia
Jika nilai dimensi tidak dapat ditentukan, Analytics akan menggunakan string khusus (belum ditetapkan).
metrik
metrics=mcf:totalConversions,mcf:totalConversionValue
Statistik gabungan untuk aktivitas pengguna ke situs Anda, seperti jumlah total konversi atau nilai konversi total.
Jika kueri tidak memiliki parameter dimensions
, metrik yang ditampilkan
memberikan nilai gabungan untuk rentang tanggal yang diminta,
seperti total nilai konversi secara keseluruhan. Namun, jika dimensi diminta, nilai akan disegmentasikan menurut nilai dimensi.
Misalnya, mcf:totalConversions
yang diminta dengan
mcf:source
akan menampilkan total konversi per sumber.
Saat meminta metrik, perhatikan:
- Setiap permintaan harus menyediakan setidaknya satu metrik; permintaan tidak boleh hanya terdiri dari dimensi.
- Anda dapat memasukkan maksimum 10 metrik untuk kueri apa pun.
mengurutkan
sort=mcf:source,mcf:medium
Daftar metrik dan dimensi yang menunjukkan tata urutan dan arah pengurutan untuk data yang ditampilkan.
- Urutan urutan ditentukan oleh urutan metrik dari dimensi kiri ke kanan yang tercantum.
- Pengurutan arah secara default ditetapkan ke menaik dan dapat
diubah menjadi menurun menggunakan awalan tanda minus (
-
) di kolom yang diminta.
Dengan mengurutkan hasil kueri, Anda dapat mengajukan pertanyaan yang berbeda tentang data. Misalnya, untuk menjawab pertanyaan
"Apa saja sumber konversi teratas saya, dan melalui media apa{1}quot;
Anda dapat membuat kueri dengan parameter berikut. Urutkan
terlebih dahulu berdasarkan mcf:source
, lalu menurut mcf:medium
,
keduanya dalam urutan menaik:
sort=mcf:source,mcf:medium
Untuk menjawab pertanyaan terkait "Apa media konversi teratas saya,
dan dari sumber mana yang menghasilkan quot;, Anda dapat membuat kueri dengan
parameter berikut. Turunan ini mengurutkan terlebih dahulu menurut mcf:medium
, lalu
mcf:source
, dalam urutan menaik:
sort=mcf:medium,mcf:source
Saat menggunakan parameter sort
, perhatikan hal berikut:
- Urutkan hanya menurut nilai dimensi atau metrik yang telah Anda gunakan dalam parameter
dimensions
ataumetrics
. Jika permintaan Anda mengurutkan kolom yang tidak ditunjukkan dalam parameter dimensi atau metrik, Anda akan menerima error. - Secara default, string diurutkan dalam urutan abjad menaik di lokalitas en-US.
- Secara default, angka diurutkan dalam urutan numerik yang naik.
- Tanggal diurutkan dalam urutan menaik menurut tanggal secara default.
filter
filters=mcf:medium%3D%3Dreferral
Parameter string kueri filters
membatasi data yang ditampilkan dari permintaan Anda. Untuk menggunakan parameter filters
, masukkan dimensi atau metrik yang akan digunakan untuk memfilter, diikuti dengan ekspresi filter. Misalnya, kueri berikut
meminta mcf:totalConversions
dan mcf:source
untuk
tampilan (profil) 12134
, dengan dimensi mcf:medium
berupa string referral
:
https://www.googleapis.com/analytics/v3/data/mcf ?ids=mcf:12134 &dimensions=mcf:source &metrics=mcf:totalConversions &filters=mcf:medium%3D%3Dreferral &start-date=2011-10-01 &end-date=2011-10-31
Baca Referensi Core Reporting API untuk mengetahui detailnya.
Tingkat sampling
samplingLevel=DEFAULT
DEFAULT
— Menampilkan respons dengan ukuran sampel yang menyeimbangkan kecepatan dan akurasi.FASTER
— Menampilkan respons cepat dengan ukuran sampel yang lebih kecil.HIGHER_PRECISION
— Menampilkan respons yang lebih akurat menggunakan ukuran sampel yang besar, tetapi hal ini dapat menyebabkan respons yang lebih lambat.
DEFAULT
akan
digunakan.hasil maks
max-results=100
Jumlah maksimum baris untuk disertakan dalam respons ini. Anda dapat
menggunakannya bersama start-index
untuk mengambil
subset elemen, atau menggunakannya sendiri untuk membatasi jumlah
elemen yang ditampilkan, dimulai dengan elemen pertama.
Jika max-results
tidak disediakan, kueri akan menampilkan
nilai maksimum default 1.000 baris.
Multi-Channel Funnels Reporting API menampilkan maksimum 10.000 baris
per permintaan, berapa pun jumlah yang Anda minta. Fitur ini juga dapat menampilkan
baris yang lebih sedikit dari yang diminta, jika segmen dimensi
tidak sebanyak yang Anda harapkan. Misalnya, nilai untuk mcf:medium
kurang dari 300, sehingga jika menyegmentasikan hanya menurut media, Anda tidak bisa mendapatkan lebih dari 300 baris, meskipun Anda menetapkan max-results
ke nilai yang lebih tinggi.
Tanggapan
Jika berhasil, permintaan ini akan menampilkan isi respons dengan struktur JSON yang ditetapkan di bawah.
Catatan: istilah "hasil" mengacu pada keseluruhan rangkaian baris yang cocok dengan kueri, sedangkan "respons" merujuk pada kumpulan baris yang ditampilkan pada halaman hasil saat ini. Jumlahnya dapat berbeda jika jumlah total hasil lebih besar dari ukuran halaman untuk respons saat ini, seperti yang dijelaskan dalam itemsPerPage.
Format Respons
{
"kind": "analytics#mcfData",
"id": string,
"query": {
"start-date": string,
"end-date": string,
"ids": string,
"dimensions": [
string
],
"metrics": [
string
],
"sort": [
string
],
"filters": string,
"samplingLevel": string,
"start-index": integer,
"max-results": integer
},
"itemsPerPage": integer,
"totalResults": integer,
"selfLink": string,
"previousLink": string,
"nextLink": string,
"profileInfo": {
"profileId": string,
"accountId": string,
"webPropertyId": string,
"internalWebPropertyId": string,
"profileName": string,
"tableId": string
},
"containsSampledData": boolean,
"sampleSize": string,
"sampleSpace": string,
"columnHeaders": [
{
"name": string,
"columnType": string,
"dataType": string
}
],
"totalsForAllResults": [
{
metricName: string,
...
}
]
"rows": [
[
McfData.Rows
]
],
}
Kolom Respons
Properti struktur isi respons didefinisikan sebagai berikut:
Nama Properti | Nilai | Deskripsi |
---|---|---|
kind |
string |
Jenis fasilitas. Nilai adalah "analytics#mcfData". |
id |
string |
ID untuk respons data ini. |
query |
object |
Objek ini berisi semua nilai yang diteruskan sebagai parameter ke kueri. Arti dari setiap kolom dijelaskan dalam deskripsi parameter kueri yang sesuai. |
query.start-date |
string |
Tanggal mulai. |
query.end-date |
string |
Tanggal akhir. |
query.ids |
string |
ID tabel unik. |
query.dimensions[] |
list |
Daftar dimensi analisis. |
query.metrics[] |
list |
Daftar metrik analisis. |
query.sort[] |
list |
Daftar metrik atau dimensi tempat data diurutkan. |
query.filters |
string |
Daftar filter metrik atau dimensi yang dipisahkan koma. |
query.samplingLevel |
string |
Requested sampling level. |
query.start-index |
integer |
Indeks awal baris. Nilai defaultnya adalah 1. |
query.max-results |
integer |
Hasil maksimum per halaman. |
startIndex |
integer |
Indeks awal baris yang ditentukan oleh parameter kueri start-index . Nilai defaultnya adalah 1. |
itemsPerPage |
integer |
Jumlah maksimum baris yang dapat ditampung respons, berapa pun jumlah baris sebenarnya yang ditampilkan. Jika parameter kueri max-results ditentukan, nilai itemsPerPage akan lebih kecil dari max-results atau 10.000. Nilai default
itemsPerPage adalah 1000.
|
totalResults |
integer |
Jumlah total baris dalam hasil kueri, berapa pun jumlah baris yang ditampilkan dalam respons. Untuk kueri yang menghasilkan baris dalam jumlah besar, totalResults dapat lebih besar dari itemsPerPage .
Lihat Paging untuk penjelasan lebih lanjut
tentang totalResults dan
itemsPerPage untuk kueri besar.
|
selfLink |
string |
Tautan ke halaman hasil ini untuk kueri data ini. |
previousLink |
string |
Tautkan ke halaman hasil sebelumnya untuk kueri data ini. |
nextLink |
string |
Tautkan ke halaman hasil berikutnya untuk kueri data ini. |
profileInfo |
object |
Informasi tentang tampilan (profil) yang datanya diminta. Data Tampilan (Profil) tersedia melalui Google Analytics Management API. |
profileInfo.profileId |
string |
ID Tampilan (Profil), seperti 1174 . |
profileInfo.accountId |
string |
ID Akun yang memiliki tampilan (profil) ini,
seperti 30481 . |
profileInfo.webPropertyId |
string |
ID Properti Web yang mencakup tampilan (profil) ini,
seperti UA-30481-1 . |
profileInfo.internalWebPropertyId |
string |
ID internal untuk properti web yang memiliki tampilan (profil) ini,
seperti UA-30481-1 . |
profileInfo.profileName |
string |
Nama tampilan (profil). |
profileInfo.tableId |
string |
ID tabel untuk tampilan (profil), terdiri dari "ga:" diikuti dengan ID tampilan (profil). |
containsSampledData |
boolean |
True jika respons berisi data dengan sampel. |
sampleSize |
string |
Jumlah sampel yang digunakan untuk menghitung data dengan sampel. |
sampleSpace |
string |
Total ukuran ruang pengambilan sampel. Ini menunjukkan total ukuran ruang sampel yang tersedia tempat sampel dipilih. |
columnHeaders[] |
list |
Header kolom yang mencantumkan nama dimensi diikuti dengan nama metrik. Urutan dimensi dan metrik sama
dengan yang ditentukan dalam permintaan melalui
parameter
metrics dan dimensions . Jumlah header adalah jumlah dimensi + jumlah metrik. |
columnHeaders[].name |
string |
Nama dimensi atau metrik. |
columnHeaders[].columnType |
string |
Jenis kolom. "DIMENSI" atau "METRIK". |
columnHeaders[].dataType |
string |
Jenis data. Header kolom dimensi hanya memiliki
"STRING" atau "MCF_SEQUENCE" sebagai jenis data.
Header kolom metrik memiliki jenis data untuk nilai metrik seperti "INTEGER" , "DOUBLE" , "CURRENCY" , dll. |
totalsForAllResults |
object |
Nilai total untuk metrik yang diminta sebagai pasangan nilai kunci nama dan nilai metrik. Urutan total metrik sama dengan urutan metrik yang ditentukan dalam permintaan. |
rows[] |
list |
Baris data laporan, yang setiap barisnya berisi daftar objek Objek
{ "primitiveValue": "2183" }
{ "conversionPathValue": [ { "interactionType" : "CLICK", "nodeValue" : "google" }, { "interactionType" : "CLICK", "nodeValue" : "google" } ] } |
Kode Error
Multi-Channel Funnels Reporting API menampilkan kode status HTTP 200
jika permintaan berhasil. Jika terjadi error saat memproses kueri, API akan menampilkan kode error dan deskripsi.
Setiap aplikasi yang menggunakan analytics API harus menerapkan logika penanganan error yang tepat. Untuk mengetahui detail tentang kode error dan cara menanganinya, baca
panduan referensi Respons Error.
Cobalah!
Gunakan APIs Explorer di bawah untuk memanggil metode ini pada data live dan melihat responsnya.
Pengambilan sampel
Google Analytics menghitung kombinasi dimensi dan metrik tertentu dengan cepat. Untuk menampilkan data dalam waktu yang wajar, Google Analytics hanya dapat memproses sampel data.
Anda dapat menentukan tingkat pengambilan sampel yang akan digunakan untuk permintaan dengan menetapkan parameter samplingLevel.
Jika respons Reporting MCF berisi data sampel, maka kolom respons containsSampledData
akan menjadi true
.
Selain itu, 2 properti akan memberikan informasi tentang tingkat pengambilan sampel
untuk kueri: sampleSize
dan sampleSpace
.
Dengan 2 nilai ini, Anda dapat menghitung persentase sesi yang digunakan untuk kueri. Misalnya, jika sampleSize
adalah 201,000
dan sampleSpace
adalah 220,000
,maka laporan didasarkan pada (201.000/220.000) * 100 = 91,36% sesi.
Lihat Pengambilan sampel untuk mengetahui deskripsi umum tentang pengambilan sampel dan cara penggunaannya di Google Analytics.
Menangani Hasil Data Besar
Jika Anda memperkirakan kueri akan menampilkan kumpulan hasil yang besar, gunakan panduan di bawah untuk membantu mengoptimalkan kueri API, menghindari error, dan meminimalkan penggunaan kuota yang berlebih. Perhatikan bahwa kita menetapkan dasar pengukuran performa dengan mengizinkan maksimum 7 dimensi dan 10 metrik dalam satu permintaan API. Meskipun beberapa kueri yang menentukan jumlah metrik dan dimensi yang besar mungkin memerlukan waktu pemrosesan yang lebih lama dibandingkan yang lain, pembatasan jumlah metrik yang diminta mungkin tidak cukup untuk meningkatkan performa kueri. Sebagai gantinya, Anda dapat menggunakan teknik berikut untuk mendapatkan hasil performa terbaik.
Mengurangi Dimensi per Kueri
API ini memungkinkan penetapan hingga 7 dimensi dalam satu permintaan. Sering kali, Google Analytics harus menghitung hasil kueri yang kompleks ini dengan cepat. Tindakan ini dapat sangat memakan waktu jika jumlah baris yang dihasilkan tinggi. Misalnya, membuat kueri untuk kata kunci, menurut kota menurut jam mungkin cocok dengan jutaan baris data. Anda dapat meningkatkan performa dengan mengurangi jumlah baris yang perlu diproses oleh Google Analytics dengan membatasi jumlah dimensi dalam kueri Anda.
Memisahkan Kueri berdasarkan Rentang Tanggal
Daripada mem-paging hasil berdasarkan tanggal dari satu rentang tanggal yang panjang, pertimbangkan untuk membuat kueri terpisah selama satu minggu — atau bahkan satu hari — dalam satu waktu. Tentu saja, untuk set data yang besar, bahkan permintaan untuk data satu hari mungkin menampilkan lebih dari max-results
, sehingga paging tidak dapat dihindari. Namun, jika jumlah baris yang cocok untuk kueri Anda lebih tinggi
dari max-results
, memisahkan rentang tanggal dapat
mengurangi total waktu untuk mengambil hasil tersebut. Pendekatan ini dapat
meningkatkan performa pada kueri thread tunggal dan paralel.
Paging
Paging untuk hasil dapat menjadi cara yang berguna untuk membagi hasil yang besar menjadi beberapa bagian yang dapat dikelola. Kolom totalResults
memberi tahu jumlah baris yang cocok, dan itemsPerPage
memberikan jumlah baris maksimum yang dapat ditampilkan dalam hasil.
Jika ada rasio totalResults
yang tinggi terhadap itemsPerPage
, setiap kueri mungkin memerlukan waktu lebih lama dari yang diperlukan. Jika hanya memerlukan baris dalam jumlah terbatas, seperti untuk tujuan tampilan, Anda dapat menetapkan batas eksplisit ukuran respons melalui parameter max-results
. Namun, jika aplikasi Anda
perlu memproses kumpulan hasil yang besar secara keseluruhan, permintaan untuk baris maksimum yang diizinkan mungkin lebih efisien.
Menggunakan gzip
Cara yang mudah dan nyaman untuk mengurangi bandwidth yang diperlukan untuk setiap permintaan adalah dengan mengaktifkan kompresi gzip. Meskipun diperlukan waktu CPU tambahan untuk membuka hasil, kompromi dengan biaya jaringan biasanya membuatnya sangat bermanfaat. Untuk menerima respons berenkode gzip, Anda harus melakukan dua hal: menetapkan header Accept-Encoding
, dan mengubah agen pengguna agar berisi string gzip
.
Berikut contoh header HTTP yang dibuat dengan benar untuk mengaktifkan
kompresi gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)