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 API Dữ liệu.
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. Để 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 thăm dò ý kiến API theo định kỳ để xác định thời điểm một yêu cầu hoàn tất.
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ác yêu cầu thông báo webhook POST, hãy thay thế tệp index.js trong hướng dẫn 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 thao tác đã thành công.
Sau khi bạn hoàn tất hướng dẫn 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 máy chủ nơi ứng dụng của bạn nghe 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 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ệ khỏi việc 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 đã chỉ định đã phản hồi thành công trong vòng chưa đến 5 giây.
Dưới đâ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ì hệ thống sẽ trả về thông báo lỗi.
Dưới đây là 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 dịch vụ webhook chứa cả phiên bản JSON của
tài nguyên thao tác chạy 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 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, 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 đến webhook không thành công, 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 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 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 nội dung JSON của mọi
thông báo do Google Analytics gửi.