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

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

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

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

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

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

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

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

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

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

יצירת רשימת קהלים קבועה

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

• שם קהל חוקי בשדה audience, בפורמט properties/{propertyId}/audiences/{audienceId}. אפשר להשתמש ב-method‏ 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"
    }
  ]
}

התגובה של השיטה 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"
  ]
}

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

משתמשים ב-method‏ 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 כדי להציג רשימה של כל רשימות הקהלים הקבועות של נכס.

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

במקום לבצע מדי פעם סקרים של המטא-נתונים של ההגדרות לגבי רשימת קהלים ספציפית שחוזרת על עצמה באמצעות השיטה 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
}