במדריך הזה מוסבר איך להשתמש ב-webhooks כדי לקבל התראות אסינכרוניות לגבי הסטטוס של הבקשות לייצוא קהלים. התכונה הזו זמינה רק בגרסת v1alpha של Data API.
התראות על תגובה לפעולה מאתר אחר (webhook) הן תכונה מתקדמת של Data API של Google Analytics. למבוא לתכונה 'ייצוא קהלים', ראו איך יוצרים ייצוא קהלים.
בלי webhooks, תצטרכו לבדוק מדי פעם את ה-API כדי לקבוע מתי הבקשה הושלמה.
יצירת אפליקציית webhook לדוגמה באמצעות Cloud Run
כדי ליצור אפליקציית webhook לדוגמה באמצעות Google Cloud, תוכלו להיעזר במדריך מדריך למתחילים: פריסת שירות לדוגמה ב-Cloud Run.
כדי שהשירות לדוגמה יוכל להאזין לבקשות של התראות POST webhook, צריך להחליף את הקובץ index.js
במדריך למתחילים בקוד הבא:
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}`);
});
בכל התראה נכנסת של webhook שנשלחת כבקשת POST, הקוד מדפיס את גוף ה-JSON של התראת ה-webhook וערך של אסימון ערוץ, ומחזיר את קוד ה-HTTP 200
כדי לציין פעולה תקינה.
בסיום המדריך למתחילים של Cloud Run ופרסתם את אפליקציית webhook באמצעות הפקודה gcloud run deploy
, שומרים את כתובת ה-URL שבה השירות נפרס.
כתובת ה-URL של השירות מוצגת במסוף, לדוגמה:
Service URL: https://webhooks-test-abcdef-uc.a.run.app
זהו ה-URI של התראות השרת, שבו האפליקציה מאזינה להתראות webhook מ-Google Analytics.
יצירת רשימת חברים בקהל והפעלה של התראות webhook
כדי לבקש התראות של תגובה לפעולה מאתר אחר (webhook), מציינים את הערכים הבאים באובייקט webhookNotification
:
ה-URI של השרת שכולל את כתובת האינטרנט שאליה יישלחו התראות webhook.
(אופציונלי) מחרוזת שרירותית
channelToken
כדי להגן מפני ההודעה מזויפת. מציינים אתchannelToken
בכותרת ה-HTTPX-Goog-Channel-Token
של בקשת ה-webhook POST.
לפניכם בקשה לדוגמה באמצעות ה-webhooks:
בקשת 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"
}
]
}
התשובה מ-method audienceLists.create
מכילה את הקוד webhookNotification
, שמאשר שה-webhook שצוין השיב בתוך פחות מ-5 שניות.
תגובה לדוגמה:
תגובת 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"
}
}
}
אם התגובה לפעולה מאתר אחר לא מגיבה או אם תספקו כתובת URL שגויה של השירות, תתקבל הודעת שגיאה במקום זאת.
דוגמה לשגיאה שאתם עשויים לקבל:
{
"error": {
"code": 400,
"message": "Expected response code of 200 from webhook URI but instead
'404' was received.",
"status": "INVALID_ARGUMENT"
}
}
עיבוד ההתראות של התגובה לפעולה מאתר אחר (webhook)
בקשת ה-POST לשירות webhook מכילה גם גרסת JSON של משאב הפעולה הארוך בגוף, וגם את השדה sentTimestamp
. חותמת הזמן שנשלחה מציינת את זמן ההפעלה של יוניקס (Unix epoch) במיליוניות השנייה שבה הבקשה נשלחה. אפשר להשתמש בחותמת הזמן הזו כדי לזהות התראות שהופעלו מחדש.
כשיוצרים רשימת חברים בקהל, המערכת שולחת בקשת POST אחת או שתיים ל-webhook:
- בקשת ה-POST הראשונה נשלחת מיד, ומציגה את רשימת החברים בקהל החדשה שנוצרה במצב
CREATING
שלה. אם הבקשה הראשונה ל-webhook תיכשל, הפעולהaudienceLists.create
תחזיר שגיאה ופרטי הכשל ב-webhook. - בקשת ה-POST השנייה נשלחת בסיום היצירה של רשימת החברים בקהל. היצירה מסתיימת כשרשימת החברים בקהל מגיעה למצב
ACTIVE
אוFAILED
.
דוגמה להתראה הראשונה על רשימת החברים בקהל, במצב 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"
}
}
דוגמה להתראה השנייה על רשימת חברים בקהל, במצב 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"
}
}
ההתראה השנייה מאשרת שרשימת החברים בקהל נוצרה ושהיא מוכנה לשליחת שאילתות באמצעות השיטה audienceLists.query
.
כדי לבדוק את ה-webhooks אחרי קריאה ל-method audienceLists.create
, אפשר לבדוק את היומנים של האפליקציה לדוגמה של Cloud Run webhook, ולראות את גוף ה-JSON של כל התראה שנשלחת מ-Google Analytics.