Panduan ini menjelaskan cara menggunakan webhook untuk menerima notifikasi asinkron untuk mengetahui status permintaan ekspor audiens. Fitur ini hanya tersedia di Data API versi v1alpha.
Notifikasi webhook adalah fitur lanjutan Google Analytics Data API baru. Sebagai pengantar fitur ekspor audiens, lihat membuat ekspor audiens.
Tanpa webhook, Anda harus melakukan polling API secara berkala untuk menentukan kapan permintaan diselesaikan.
Membuat contoh aplikasi webhook menggunakan Cloud Run
Anda dapat membuat contoh aplikasi webhook menggunakan Google Cloud dengan mengikuti tutorial Panduan memulai: Men-deploy layanan contoh ke Cloud Run.
Agar layanan contoh dapat memproses permintaan notifikasi webhook POST,
mengganti file index.js dari tutorial panduan memulai dengan
kode:
import express from 'express';
const app = express();
app.use(express.json());
app.post('/', (req, res) => {
const channelToken = req.get('X-Goog-Channel-Token');
const bodyJson = JSON.stringify(req.body);
console.log(`channel token: ${channelToken}`);
console.log(`notification body: ${bodyJson}`);
res.sendStatus(200);
});
const port = parseInt(process.env.PORT) || 8080;
app.listen(port, () => {
console.log(`helloworld: listening on port ${port}`);
});
Untuk setiap notifikasi webhook masuk yang dikirim sebagai permintaan POST, kode ini akan dicetak
isi JSON notifikasi webhook dan nilai token saluran, dan
menampilkan kode HTTP 200 untuk menunjukkan operasi yang berhasil.
Setelah Anda mencapai akhir tutorial panduan memulai Cloud Run dan men-deploy
aplikasi webhook menggunakan perintah gcloud run deploy, simpan
URL tempat layanan Anda di-deploy.
URL layanan ditampilkan di konsol, misalnya:
Service URL: https://webhooks-test-abcdef-uc.a.run.app
Ini adalah URI notifikasi server tempat aplikasi Anda memproses notifikasi webhook dari di Google Analytics.
Membuat daftar audiens dan mengaktifkan notifikasi webhook
Untuk meminta notifikasi webhook, tentukan nilai berikut di kolom webhookNotification
:
URI notifikasi server berisi alamat web yang akan menerima notifikasi webhook.
(Opsional) String arbitrer
channelTokenuntuk melindungi dari pesan {i>spoofing<i}. TentukanchannelTokendi header HTTPX-Goog-Channel-Tokenpermintaan POST webhook.
Berikut adalah contoh permintaan menggunakan webhook:
Permintaan HTTP
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/audienceLists
{
"webhookNotification": {
"uri": "https://webhooks-test-abcdef-uc.a.run.app",
"channelToken": "123456"
},
"audience": "properties/1234567/audiences/12345",
"dimensions": [
{
"dimensionName": "deviceId"
}
]
}
Respons dari metode audienceLists.create berisi atribut
webhookNotification, yang mengonfirmasi bahwa webhook yang ditentukan berhasil
merespons dalam waktu kurang dari 5 detik.
Berikut adalah contoh respons:
Respons HTTP
{
"response": {
"@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceList",
"name": "properties/1234567/audienceLists/123",
"audience": "properties/1234567/audiences/12345",
"audienceDisplayName": "Purchasers",
"dimensions": [
{
"dimensionName": "deviceId"
}
],
"state": "ACTIVE",
"beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
"creationQuotaTokensCharged": 51,
"rowCount": 13956,
"percentageCompleted": 100,
"webhookNotification": {
"uri": "https://webhooks-test-abcdef-uc.a.run.app",
"channelToken": "123456"
}
}
}
Jika webhook gagal merespons, atau jika Anda memberikan URL layanan yang salah, pesan {i>error<i} akan dimunculkan.
Berikut adalah contoh error yang mungkin Anda terima:
{
"error": {
"code": 400,
"message": "Expected response code of 200 from webhook URI but instead
'404' was received.",
"status": "INVALID_ARGUMENT"
}
}
Memproses notifikasi webhook
Permintaan POST ke layanan webhook berisi versi JSON dari
resource operasi yang berjalan lama
dalam isi, dan kolom sentTimestamp. Stempel waktu yang
dikirim menentukan
waktu Unix {i>epoch<i} dalam
mikrodetik saat permintaan dikirim. Anda dapat menggunakan
untuk mengidentifikasi notifikasi yang diputar ulang.
Satu atau dua permintaan POST dikirim ke webhook selama pembuatan daftar audiens:
- Permintaan POST pertama segera dikirim, menampilkan permintaan POST yang baru dibuat
daftar audiens dalam status
CREATING. Jika permintaan pertama ke webhook gagal, operasiaudienceLists.createakan menampilkan error dan detail kegagalan webhook. - Permintaan POST kedua dikirim setelah daftar audiens selesai
pembuatan konten. Pembuatan selesai saat daftar audiens mencapai
status
ACTIVEatauFAILED.
Berikut adalah contoh notifikasi pertama untuk daftar audiens, dalam
Status CREATING:
{
"sentTimestamp":"1718261355692983",
"name": "properties/1234567/audienceLists/123",
"audience": "properties/1234567/audiences/12345",
"audienceDisplayName":"Purchasers",
"dimensions":[{"dimensionName":"deviceId"}],
"state":"CREATING",
"beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
"creationQuotaTokensCharged":0,
"rowCount":0,
"percentageCompleted":0,
"webhookNotification":
{
"uri": "https://webhooks-test-abcdef-uc.a.run.app",
"channelToken":"123456"
}
}
Berikut adalah contoh notifikasi kedua untuk daftar audiens, pada bagian
Status ACTIVE:
{
"sentTimestamp":"1718261355692983",
"name": "properties/1234567/audienceLists/123",
"audience": "properties/1234567/audiences/12345",
"audienceDisplayName":"Purchasers",
"dimensions":[{"dimensionName":"deviceId"}],
"state":"ACTIVE",
"beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
"creationQuotaTokensCharged":68,
"rowCount":13956,
"percentageCompleted":100,
"webhookNotification":
{
"uri": "https://webhooks-test-abcdef-uc.a.run.app",
"channelToken":"123456"
}
}
Notifikasi kedua mengonfirmasi bahwa daftar audiens telah dibuat dan
siap dikueri menggunakan audienceLists.query
.
Untuk menguji webhook setelah memanggil metode audienceLists.create, Anda dapat
periksa log
aplikasi webhook Cloud Run contoh, dan melihat isi JSON dari setiap
notifikasi yang dikirim oleh Google Analytics.