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 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 API Dữ liệu.
Thông báo webhook là một tính năng nâng cao của Data API của 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 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 theo hướng dẫn trong bài viết Bắt đầu nhanh: Triển khai một dịch vụ mẫu cho Cloud Run.
Để dịch vụ mẫu có thể theo dõi 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 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 hoàn tất 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 thông báo webhook.
(Không bắt buộc) Một chuỗi tuỳ ý
channelTokenđể ngăn chặn tin nhắn bị giả mạo. Chỉ địnhchannelTokentrong tiêu đề HTTPX-Goog-Channel-Tokencủa yêu cầu POST webhook.
Dưới đâ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 chưa đầy 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ì thông báo lỗi sẽ được trả về.
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 đến dịch vụ webhook chứa cả phiên bản JSON của
tài nguyên hoạt động chạy trong thời gian dài
trong phần nội dung và trường sentTimestamp. Dấu thời gian đã gửi chỉ định thời gian 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 đượ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, thì 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 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 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 mẫu trên Cloud Run và xem nội dung JSON của mọi thông báo do Google Analytics gửi.