Panduan ini menjelaskan cara menggunakan webhook untuk menerima notifikasi asinkron untuk status permintaan ekspor audiens. Fitur ini hanya tersedia di Data API versi v1alpha.
Notifikasi webhook adalah fitur lanjutan dari Data API Google Analytics. Untuk pengenalan fitur ekspor audiens, lihat membuat ekspor audiens.
Tanpa webhook, Anda harus melakukan polling API secara berkala untuk menentukan kapan permintaan selesai.
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, ganti file index.js dari tutorial panduan memulai dengan kode berikut:
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 mencetak isi JSON notifikasi webhook dan nilai token saluran, serta menampilkan kode HTTP 200 untuk menunjukkan operasi yang berhasil.
Setelah 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 Google Analytics.
Membuat daftar audiens dan mengaktifkan notifikasi webhook
Untuk meminta notifikasi webhook, tentukan nilai berikut dalam objek webhookNotification:
URI notifikasi server yang berisi alamat web yang akan menerima notifikasi webhook.
(Opsional) String arbitrer
channelTokenuntuk mencegah pesan yang di-spoofing. TentukanchannelTokendi header HTTPX-Goog-Channel-Tokendari permintaan 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 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 error akan ditampilkan.
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 di bagian isi, dan kolom sentTimestamp. Stempel waktu yang dikirim menentukan
waktu Unix epoch dalam mikrodetik saat permintaan dikirim. Anda dapat menggunakan
stempel waktu ini untuk mengidentifikasi notifikasi yang diputar ulang.
Satu atau dua permintaan POST dikirim ke webhook selama pembuatan daftar audiens:
- Permintaan POST pertama segera dikirim, yang menampilkan daftar audiens
yang baru dibuat dalam status
CREATING. Jika permintaan pertama ke webhook gagal, operasiaudienceLists.createakan menampilkan error dan detail kegagalan webhook. - Permintaan POST kedua dikirim setelah daftar audiens menyelesaikan
pembuatan. 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, dalam
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 metode
audienceLists.query.
Untuk menguji webhook setelah memanggil metode audienceLists.create, Anda dapat memeriksa log contoh aplikasi webhook Cloud Run, dan melihat isi JSON dari setiap notifikasi yang dikirim oleh Google Analytics.