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

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

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

אם לא משתמשים ב-webhooks, צריך לבצע שאילתות ל-API באופן תקופתי כדי לדעת מתי בקשה הושלמה.

יצירת אפליקציית webhook לדוגמה באמצעות Cloud Run

אפשר ליצור אפליקציית webhook לדוגמה באמצעות Google Cloud בעזרת המדריך הפעלה מהירה: פריסת שירות לדוגמה ב-Cloud Run.

כדי ששירות הדוגמה יאזין לבקשות התראות של webhook מסוג POST, צריך להחליף את הקובץ 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"
    }
  ]
}

התשובה מ-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.

כדי לבדוק את ה-webhook אחרי קריאה לשיטה audienceLists.create, אפשר לעיין ביומנים של אפליקציית ה-webhook לדוגמה ב-Cloud Run ולראות את גוף ה-JSON של כל התראה שנשלחת מ-Google Analytics.