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

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

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

ללא 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 של התראת התגובה לפעולה מאתר אחר ואת ערך של אסימון הערוץ, מחזירה את קוד ה-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 object:

• ה-URI של התראות השרת שמכילות את כתובת האינטרנט שאליה יישלחו התראות webhook.

• (אופציונלי) מחרוזת שרירותית channelToken כדי להגן מפני זיוף ההודעה. יש לציין את channelToken בכותרת ה-HTTP X-Goog-Channel-Token של בקשת webhook POST.

לפניכם בקשה לדוגמה באמצעות ה-webhooks:

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 שניות.

תגובה לדוגמה:

{
  "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. חותמת הזמן שנשלחה מציינת זמן Epoch של Unix במיקרו-שניות שבו הבקשה נשלחה. אפשר להשתמש חותמת זמן לזיהוי התראות שהופעלו מחדש.

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