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

במדריך הזה מוסבר איך להשתמש ב-webhooks כדי לקבל התראות אסינכרוניות על הסטטוס של בקשות לייצוא קהלים. התכונה הזו זמינה רק בגרסה v1alpha של 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 של בקשת ה-POST של ה-webhook X-Goog-Channel-Token.

הנה דוגמה לבקשה באמצעות 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.