רשימות קהלים חוזרות

במסמך הזה מתוארות רשימות קהלים חוזרות, שהן תכונה מתקדמת של Google Analytics Data API v1. במדריך בנושא ייצוא קהלים מוסבר על התכונה לייצוא רשימות של קהלים.

רשימות קהלים חוזרות נוצרות מדי יום כשהחברות בקהלים משתנה, כדי לוודא שאתם עובדים עם הנתונים העדכניים ביותר.

רשימות קהלים רגילות (חד-פעמיות) הן רשימות סטטיות של משתמשים בקהל בזמן יצירת הרשימה.

יצירה של רשימת קהלים חדשה מדי יום

הזמן שלוקח לעבד את נתוני הקהל של יום אחד ולעדכן את החברות בקהל משתנה. אין דרך לוודא שנתוני רשימת הקהלים מתעדכנים תוך 24 שעות.

לדוגמה, גם אם תבקשו רשימת קהלים באותה שעה בכל יום, בימים מסוימים רשימת הקהלים תהיה זהה לזו של היום הקודם, ובימים אחרים היא תהיה שונה ותכלול שינויים בחברות של יום נוסף.

רשימות של קהלים מבוססות על נתוני אירועים מיום אחד לפני השינויים האחרונים בחברות. אם יוצרים רשימת חברים בקהל לפני שהעדכונים היומיים של החברות בקהל מתבצעים, המערכת תשתמש בנתונים מיומיים לפני כן. אם תיצרו רשימת קהלים אחרי שהעדכונים היומיים של החברות יתבצעו, המערכת תשתמש בנתונים מאתמול.

שליחת שאילתות מעת לעת לרשימת חברים בקהל חוזר

רשימות קהלים חוזרות יוצרות רשימות קהלים רק כשנתונים של יום נוסף זמינים. כך לא צריך לנחש מתי כדאי ליצור רשימות חדשות של קהלים. במקום זאת, אפשר לבצע סקר זול של רשימת החברים בקהל החוזרת לאורך היום כדי לראות אם יש נתונים נוספים.

יצירה של רשימת קהלים חוזרת

כדי ליצור רשימת חברים בקהל שמתעדכנת באופן קבוע, שולחים בקשה עם קריאה ל-method‏ recurringAudienceLists.create באמצעות האובייקט RecurringAudienceList. חובה לציין את הפרמטרים הבאים:

• שם תקין של קהל היעד בשדה audience, בפורמט properties/{propertyId}/audiences/{audienceId}. אפשר להשתמש בשיטה audiences.list של Google Analytics Admin API v1 כדי לקבל את הערך הזה. השדה Audience.name בתגובת audiences.list מכיל את שם הקהל.
• רשימה תקינה של מאפיינים בשדה dimensions. רשימת המאפיינים שנתמכים בשיטה הזו מופיעה במאמרי העזרה בנושא סכימת ייצוא של קהלים. רק הנתונים של המאפיינים שמוזכרים בשדה הזה נכללים ברשימת הקהלים.

דוגמה לבקשה חוזרת ליצירת רשימת קהלים:

בקשת HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

תשובה של ה-method‏ recurringAudienceLists.create מכילה את השם בשדה name (למשל properties/1234567/recurringAudienceLists/123), שאפשר להשתמש בו בשאילתות הבאות כדי לאחזר את המטא-נתונים של ההגדרה של רשימת הקהלים החוזרת הזו. בנוסף, המטא-נתונים של ההגדרות מכילים שמות משאבים של מקרים של רשימות קהלים שנוצרו עבור רשימת הקהלים החוזרת הזו.

תגובת HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

מטא-נתונים של הגדרת הסקר

משתמשים בשיטה recurringAudienceLists.get כדי לאחזר מטא-נתונים של הגדרות לגבי רשימת חברים בקהל ספציפית שמתעדכנת באופן קבוע. המטא-נתונים של ההגדרות מכילים שמות משאבים של מופעים של רשימת קהלים שנוצרו עבור רשימת הקהלים החוזרת הזו.

לדוגמה:

בקשת HTTP

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists/123

מוחזר מופע של RecurringAudienceList בתגובה. הוא מכיל את המטא-נתונים של ההגדרות, כולל שמות המשאבים של מופעים של רשימת קהלים שנוצרו עבור רשימת הקהלים החוזרת הזו.

תגובת HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

אפשר להשתמש בפקודה recurringAudienceLists.list כדי להציג רשימה של כל רשימות החברים בקהל שמתעדכנות באופן קבוע בנכס.

שימוש ב-webhook כדי לקבל התראות אסינכרוניות על רשימות חדשות של חברים בקהל

במקום לבצע מדי פעם שאילתות לגבי המטא-נתונים של ההגדרות של רשימת קהלים ספציפית שמתעדכנת באופן קבוע באמצעות השיטה recurringAudienceLists.get, אתם יכולים לקבל באופן אסינכרוני התראות Webhook כשמתעדכנת רשימת קהלים.

כדי להגדיר התראות Webhook, צריך לציין את השדה webhookNotification כשיוצרים רשימה חדשה של חברים בקהל שמתעדכנת באופן קבוע.

מידע נוסף על שימוש ב-Webhooks ב-Google Analytics Data API v1 זמין במדריך Async audience lists with webhooks.

אחזור משתמשים בייצוא קהל

כדי לאחזר משתמשים בייצוא של קהל, קוראים לשיטה audienceExports.query ומציינים את השם של ייצוא הקהל שאוחזר ממטא-נתוני ההגדרה שסופקו על ידי recurringAudienceLists.get או recurringAudienceLists.list.

בקשת HTTP

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

אם הייצוא של הקהל מוכן, מוחזרת תגובה שמכילה את רשימת המשתמשים בקהל:

תגובת HTTP

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}