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

במדריך הזה מוסבר איך להשתמש ב-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 בכותרת ה-HTTP X-Goog-Channel-Token של בקשת ה-POST ל-webhook.

זוהי דוגמה לבקשה באמצעות 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"
    }
  ]
}

התשובה מהשיטה 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) במיקרו-שניות שבו נשלחה הבקשה. אפשר להשתמש בחותמת הזמן הזו כדי לזהות התראות שהופעלה בהן הפעלה חוזרת.

במהלך יצירת רשימת משתמשים, נשלחת ל-webhook בקשת POST אחת או שתיים:

  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.