คู่มือนี้จะอธิบายวิธีใช้เว็บฮุคเพื่อรับการแจ้งเตือนแบบไม่พร้อมกันสำหรับสถานะคำขอส่งออกกลุ่มเป้าหมาย ฟีเจอร์นี้ใช้ได้เฉพาะใน Data API เวอร์ชัน v1alpha เท่านั้น
การแจ้งเตือนเว็บฮุคคือฟีเจอร์ขั้นสูงของ Data API ของ Google Analytics สำหรับข้อมูลเบื้องต้นเกี่ยวกับฟีเจอร์การส่งออกกลุ่มเป้าหมาย โปรดดูสร้างการส่งออกกลุ่มเป้าหมาย
หากไม่มีเว็บฮุค คุณจะต้องสำรวจ API เป็นระยะๆ เพื่อตัดสินว่าคำขอจะเสร็จสมบูรณ์เมื่อใด
สร้างตัวอย่างแอปพลิเคชันเว็บฮุคโดยใช้ Cloud Run
คุณสร้างตัวอย่างแอปพลิเคชันเว็บฮุคได้โดยใช้ Google Cloud โดยทำตามบทแนะนำ การเริ่มต้นอย่างรวดเร็ว: ทำให้บริการตัวอย่างใช้งานได้กับ Cloud Run
หากต้องการให้บริการตัวอย่างฟังคำขอการแจ้งเตือนเว็บฮุค POST ให้แทนที่ไฟล์ index.js
จากบทแนะนำการเริ่มต้นอย่างรวดเร็วด้วยโค้ดต่อไปนี้
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}`);
});
สำหรับการแจ้งเตือนเว็บฮุคขาเข้าทุกรายการที่ส่งเป็นคำขอ POST โค้ดนี้จะพิมพ์เนื้อหา JSON ของการแจ้งเตือนเว็บฮุคและค่าโทเค็นช่องทาง และแสดงผลรหัส HTTP 200
เพื่อบ่งบอกว่าการดำเนินการสำเร็จ
เมื่ออ่านบทแนะนำการเริ่มต้นอย่างรวดเร็วของ Cloud Run จนสุดแล้วและทำให้แอปพลิเคชันเว็บฮุคใช้งานได้โดยใช้คำสั่ง gcloud run deploy
ให้บันทึก URL ที่มีการทำให้บริการใช้งานได้
URL ของบริการจะปรากฏในคอนโซล เช่น
Service URL: https://webhooks-test-abcdef-uc.a.run.app
นี่คือ URL การแจ้งเตือนของเซิร์ฟเวอร์ ที่แอปพลิเคชันจะฟังการแจ้งเตือนเว็บฮุคจาก Google Analytics
สร้างรายการกลุ่มเป้าหมายและเปิดการแจ้งเตือนเว็บฮุค
หากต้องการขอการแจ้งเตือนเว็บฮุค ให้ระบุค่าต่อไปนี้ในออบเจ็กต์ webhookNotification
URL การแจ้งเตือนของเซิร์ฟเวอร์ ที่มีที่อยู่เว็บที่จะได้รับการแจ้งเตือนเว็บฮุค
(ไม่บังคับ) สตริงที่กำหนดเอง
channelToken
เพื่อป้องกันข้อความที่มีการปลอมแปลง ระบุchannelToken
ในส่วนหัว HTTPX-Goog-Channel-Token
ของคำขอ POST ของเว็บฮุค
ตัวอย่างคำขอที่ใช้เว็บฮุคมีดังนี้
คำขอ 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"
}
]
}
การตอบกลับจากเมธอด audienceLists.create
มี webhookNotification
ซึ่งยืนยันว่าเว็บฮุคที่ระบุตอบสนองสำเร็จภายใน 5 วินาที
ตัวอย่างการตอบกลับมีดังนี้
การตอบสนองของ 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"
}
}
}
หากเว็บฮุคไม่ตอบสนองหรือหากคุณระบุ URL บริการที่ไม่ถูกต้อง ระบบจะแสดงข้อความแสดงข้อผิดพลาดแทน
ตัวอย่างข้อผิดพลาดที่คุณอาจได้รับมีดังนี้
{
"error": {
"code": 400,
"message": "Expected response code of 200 from webhook URI but instead
'404' was received.",
"status": "INVALID_ARGUMENT"
}
}
ประมวลผลการแจ้งเตือนเว็บฮุค
คำขอ POST ไปยังบริการเว็บฮุคจะมีทั้งเวอร์ชัน JSON ของทรัพยากรการดำเนินการที่ใช้เวลานานในตัวเนื้อหา และช่อง sentTimestamp
การประทับเวลาที่ส่งจะระบุเวลา Unix Epoch ในหน่วยไมโครวินาทีที่ส่งคำขอ โดยคุณใช้การประทับเวลานี้เพื่อระบุการแจ้งเตือนที่เล่นซ้ำได้
ระบบจะส่งคำขอ POST 1 หรือ 2 รายการไปยังเว็บฮุคในระหว่างการสร้างรายการกลุ่มเป้าหมาย ดังนี้
- ระบบจะส่งคำขอ POST แรกทันทีโดยแสดงรายการกลุ่มเป้าหมายที่สร้างขึ้นใหม่ในสถานะ
CREATING
หากคำขอแรกไปยังเว็บฮุคไม่สำเร็จ การดำเนินการaudienceLists.create
จะแสดงข้อผิดพลาดและรายละเอียดความล้มเหลวของเว็บฮุค - ระบบจะส่งคำขอ POST รายการที่ 2 หลังจากสร้างรายการกลุ่มเป้าหมายเสร็จแล้ว การสร้างจะเสร็จสมบูรณ์เมื่อรายการกลุ่มเป้าหมายอยู่ในสถานะ
ACTIVE
หรือFAILED
ต่อไปนี้คือตัวอย่างการแจ้งเตือนครั้งแรกสำหรับรายการกลุ่มเป้าหมายในสถานะ 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"
}
}
ต่อไปนี้คือตัวอย่างการแจ้งเตือนครั้งที่ 2 สำหรับรายการกลุ่มเป้าหมายที่อยู่ในสถานะ 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"
}
}
การแจ้งเตือนครั้งที่ 2 จะยืนยันว่าได้สร้างรายการกลุ่มเป้าหมายแล้วและพร้อมที่จะค้นหาโดยใช้เมธอด audienceLists.query
หากต้องการทดสอบเว็บฮุคหลังจากเรียกใช้เมธอด audienceLists.create
คุณสามารถตรวจสอบบันทึกของแอปพลิเคชันเว็บฮุค Cloud Run ตัวอย่าง และดูส่วนเนื้อหา JSON ของการแจ้งเตือนทุกรายการที่ Google Analytics ส่งได้