คู่มือนี้จะอธิบายวิธีใช้เว็บฮุคเพื่อรับการแจ้งเตือนแบบอะซิงโครนัสสำหรับสถานะคำขอส่งออกกลุ่มเป้าหมาย ฟีเจอร์นี้ใช้ได้เฉพาะใน 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
นี่คือ URI การแจ้งเตือนของเซิร์ฟเวอร์ที่แอปพลิเคชันของคุณคอยฟังการแจ้งเตือนเว็บฮุคจาก Google Analytics
สร้างรายการกลุ่มเป้าหมายและเปิดการแจ้งเตือน Webhook
หากต้องการขอการแจ้งเตือนเว็บฮุค ให้ระบุค่าต่อไปนี้ในออบเจ็กต์ webhookNotification
URI การแจ้งเตือนของเซิร์ฟเวอร์ที่มีที่อยู่เว็บซึ่งจะได้รับการแจ้งเตือนจากเว็บฮุค
(ไม่บังคับ) สตริงที่กำหนดเอง
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"
}
}
ประมวลผลการแจ้งเตือน Webhook
คำขอ 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 ส่งได้