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

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

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

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

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

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

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

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

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

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

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

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

• שם תקין של קהל בשדה 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"
    }
  ]
}

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

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

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

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

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

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

כדי לאחזר משתמשים בייצוא של קהל, קוראים לשיטה 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
}