קבלת התראות על תגובה לפעולה מאתר אחר (webhook) לרשימות הקהלים

במדריך הזה מוסבר איך להשתמש ב-webhooks כדי לקבל התראות אסינכרוניות לגבי הסטטוס של בקשות הייצוא של הקהלים. התכונה הזו זמינה רק בגרסה v1alpha של Data API.

התראות של תגובה לפעולה מאתר אחר (webhook) הן תכונה מתקדמת של Google Analytics Data API. כדי לקבל מידע כללי על התכונה "ייצוא קהלים", עיינו במאמר יצירת ייצוא של קהל.

בלי לפעול עם תגובות לפעילות אינטרנט, תצטרכו לדגום את ה-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 בכותרת ה-HTTP‏ X-Goog-Channel-Token של בקשת ה-POST של ה-webhook.

הנה דוגמה לבקשה באמצעות webhook:

בקשת 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"
    }
  }
}

אם ה-webhook לא מגיב או אם כתובת ה-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:

  1. בקשת ה-POST הראשונה נשלחת מיד, ומציגה את רשימת הקהלים החדשה שנוצרה במצב CREATING. אם הבקשה הראשונה ל-webhook נכשלת, הפעולה audienceLists.create מחזירה שגיאה ואת פרטי הכישלון של ה-webhook.
  2. בקשת ה-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, אתם יכולים לבדוק את היומנים של אפליקציית ה-webhook לדוגמה ב-Cloud Run, ולראות את גוף ה-JSON של כל התראה שנשלחה על ידי Google Analytics.