קבלת התראות על תגובה לפעולה מאתר אחר (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 של בקשת ה-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:

  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, אפשר לבדוק את היומנים של האפליקציה לדוגמה של Cloud Run webhook, ולראות את גוף ה-JSON של כל התראה שנשלחת מ-Google Analytics.