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 alpha của Data API.
Thông báo webhook là một tính năng nâng cao của API dữ liệu của Google Analytics. Để tìm hiểu giới thiệu về tính năng xuất đối tượng, hãy xem bài viết tạo đối tượng xuất.
Nếu không có webhook, bạn sẽ cần thăm dò API theo định kỳ để xác định thời điểm hoàn tất một yêu cầu.
Tạo ứ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 Bắt đầu nhanh: Triển khai dịch vụ mẫu cho Cloud Run.
Để dịch vụ mẫu nghe được yêu cầu thông báo webhook POST, hãy thay thế tệp index.js trong phần 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 ra 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 thao tác thành công.
Sau khi bạn xem hết phần hướng dẫn bắt đầu nhanh trên Cloud Run và triển khai ứng dụng webhook bằng lệnh gcloud run deploy, hãy lưu URL của trang đích triển khai dịch vụ.
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 tiếp 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 thông báo webhook.
(Không bắt buộc) Một chuỗi tuỳ ý
channelTokenđể bảo vệ thông báo bị giả mạo. Hãy chỉ địnhchannelTokentrong tiêu đề HTTPX-Goog-Channel-Tokencủa yêu cầu POST webhook.
Dưới đây là 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 chưa đầy 5 giây.
Dưới đây là 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ì hệ thống sẽ trả về một thông báo lỗi.
Dưới đây là ví dụ về lỗi 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 tới dịch vụ webhook chứa cả phiên bản JSON của tài nguyên hoạt động hoạt động trong thời gian dài trong phần nội dung và trường sentTimestamp. Dấu thời gian được 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 đã phát lại.
Một hoặc hai yêu cầu POST đượ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, hiển thị danh sách đối tượng mới tạo ở trạng thái
CREATING. Nếu yêu cầu đầu tiên đối với webhook không thành công, thì thao tácaudienceLists.createsẽ trả về một 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 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 một 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 truy vấn bằng phương thức audienceLists.query.
Để kiểm tra 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.