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ộ để biết trạng thái của các yêu cầu xuất đối tượng. Bạn chỉ có thể sử dụng tính năng này 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 Dữ liệu . Để được giới thiệu về tính năng xuất đối tượng, hãy xem bài viết tạo dữ liệu xuất đối tượng.
Nếu không có webhook, bạn cần kiểm tra định kỳ API để 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 ứ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 một 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,
thay thế tệp index.js trong hướng dẫn bắt đầu nhanh bằng tệp sau
mã:
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
loại bỏ nội dung JSON của thông báo webhook và giá trị mã thông báo kênh, đồng thời
sẽ trả về mã HTTP 200 để cho biết thao tác thành công.
Sau khi xem hết phần hướng dẫn bắt đầu nhanh 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 từ webhook 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 webhookNotification
đối tượng:
URI thông báo của máy chủ chứa địa chỉ web sẽ nhận thông báo về webhook.
(Không bắt buộc) Một chuỗi tuỳ ý
channelTokenđể bảo vệ thư bị giả mạo. Chỉ địnhchannelTokentrong tiêu đề HTTPX-Goog-Channel-Tokencủa yêu cầu POST trên 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 thành công
đã trả lời 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ề 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 một 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. Chỉ định dấu thời gian đã gửi
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ể dùng
dấu thời gian để 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 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 yêu cầu mới được tạo
danh sách đối tượng ở 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
sáng tạo. Quá trình tạo hoàn tất khi danh sách đối tượng đạt đến một trong hai
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, trong
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, trong
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à đang
sẵn sàng để truy vấn bằng 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 của bạn và xem nội dung JSON của mọi
do Google Analytics gửi.