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

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