Hướng dẫn này giải thích cách sử dụng webhook để nhận thông báo không đồng bộ về trạng thái của các yêu cầu xuất đối tượng. Tính năng này chỉ có trong phiên bản v1alpha của Data API.
Thông báo webhook là một tính năng nâng cao của Data API Google Analytics. Để xem phần giới thiệu về tính năng xuất đối tượng, hãy xem bài viết tạo tệp xuất đối tượng.
Nếu không có webhook, bạn sẽ cần định kỳ thăm dò API để xác định thời điểm hoàn tất một yêu cầu.
Tạo một ứng dụng webhook mẫu bằng Cloud Run
Bạn có thể tạo một ứng dụng webhook mẫu bằng Google Cloud bằng cách làm theo hướng dẫn Hướng dẫn nhanh: Triển khai một dịch vụ mẫu vào Cloud Run.
Để dịch vụ mẫu lắng nghe các yêu cầu thông báo webhook POST, hãy thay thế tệp index.js trong hướng dẫn bắt đầu nhanh bằng mã sau:
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}`);
});
Đối với mỗi thông báo webhook đến được gửi dưới dạng yêu cầu POST, mã này sẽ in nội dung JSON của thông báo webhook và giá trị mã thông báo kênh, đồng thời trả về mã HTTP 200 để cho biết hoạt động thành công.
Sau khi bạn hoàn thành hướng dẫn bắt đầu nhanh về Cloud Run và triển khai ứng dụng webhook bằng lệnh gcloud run deploy, hãy lưu URL nơi dịch vụ của bạn được triển khai.
URL dịch vụ sẽ xuất hiện trong bảng điều khiển, ví dụ:
Service URL: https://webhooks-test-abcdef-uc.a.run.app
Đây là URI thông báo của máy chủ nơi ứng dụng của bạn nhận thông báo webhook từ Google Analytics.
Tạo danh sách đối tượng và bật thông báo webhook
Để yêu cầu thông báo webhook, hãy chỉ định các giá trị sau trong đối tượng webhookNotification:
URI thông báo của máy chủ chứa địa chỉ web sẽ nhận được thông báo webhook.
(Không bắt buộc) Một chuỗi tuỳ ý
channelTokenđể ngăn chặn việc giả mạo thông báo. Chỉ địnhchannelTokentrong tiêu đề HTTPX-Goog-Channel-Tokencủa yêu cầu POST webhook.
Sau đây là một yêu cầu mẫu sử dụng webhook:
Yêu cầu 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"
}
]
}
Phản hồi từ phương thức audienceLists.create chứa webhookNotification, xác nhận rằng webhook được chỉ định đã phản hồi thành công trong vòng 5 giây.
Sau đây là một phản hồi mẫu:
Phản hồi 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"
}
}
}
Nếu webhook không phản hồi hoặc nếu bạn cung cấp URL dịch vụ không chính xác, thì thay vào đó, một thông báo lỗi sẽ được trả về.
Sau đây là một ví dụ về lỗi mà bạn có thể gặp phải:
{
"error": {
"code": 400,
"message": "Expected response code of 200 from webhook URI but instead
'404' was received.",
"status": "INVALID_ARGUMENT"
}
}
Xử lý thông báo webhook
Yêu cầu POST đến một dịch vụ webhook chứa cả phiên bản JSON của tài nguyên thao tác diễn ra trong thời gian dài trong nội dung và trường sentTimestamp. Dấu thời gian đã gửi chỉ định thời gian bắt đầu của hệ thống Unix tính bằng micrô giây mà yêu cầu được gửi. Bạn có thể sử dụng dấu thời gian này để xác định các thông báo được phát lại.
Một hoặc hai yêu cầu POST sẽ được gửi đến webhook trong quá trình tạo danh sách đối tượng:
- Yêu cầu POST đầu tiên được gửi ngay lập tức, cho thấy danh sách đối tượng mới tạo ở trạng thái
CREATING. Nếu yêu cầu đầu tiên đến webhook không thành công, thao tácaudienceLists.createsẽ trả về lỗi và thông tin chi tiết về lỗi webhook. - Yêu cầu POST thứ hai được gửi sau khi danh sách đối tượng hoàn tất quá trình tạo. Quá trình tạo hoàn tất khi danh sách đối tượng đạt đến trạng thái
ACTIVEhoặcFAILED.
Dưới đây là ví dụ về thông báo đầu tiên cho một danh sách đối tượng, ở trạng thái 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"
}
}
Dưới đây là ví dụ về thông báo thứ hai cho danh sách đối tượng, ở trạng thái 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"
}
}
Thông báo thứ hai xác nhận rằng danh sách đối tượng đã được tạo và sẵn sàng được truy vấn bằng phương thức audienceLists.query.
Để kiểm thử webhook sau khi gọi phương thức audienceLists.create, bạn có thể kiểm tra nhật ký của ứng dụng webhook Cloud Run mẫu và xem phần nội dung JSON của mọi thông báo do Google Analytics gửi.