יצירה של ייצוא קהלים

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

אתם יכולים לייצא את הקהלים שלכם, כולל תמונת מצב של המשתמשים בהם, באמצעות Data API.

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

סקירה כללית

כדי ליצור ייצוא של קהל ולשלוח שאילתה לגביו, צריך לשלוח את בקשות ה-API הבאות ל-Data API:

1. מבצעים קריאה לשיטה audienceExports.create כדי ליצור ייצוא של קהל.
2. קוראים לשיטה audienceExports.query כדי לאחזר את המשתמשים בקהל.

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

בחירת ישות לדיווח

בכל השיטות של Data API צריך לציין את מזהה הנכס ב-Google Analytics בנתיב הבקשה של כתובת ה-URL, בתבנית properties/GA_PROPERTY_ID. לדוגמה:

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/audienceExports

הדוח נוצר על סמך נתוני האירועים ב-Google Analytics שנאספו בנכס הספציפי ב-Google Analytics.

אם אתם משתמשים באחת מספריות הלקוח של Data API, אתם לא צריכים לשנות את נתיב כתובת ה-URL של הבקשה. ברוב לקוחות ה-API יש פרמטר property שמצפה למחרוזת בפורמט properties/GA_PROPERTY_ID. דוגמאות לשימוש בספריות הלקוח מופיעות במדריך למתחילים.

יצירת ייצוא של קהל

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

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

הנה דוגמה לבקשה ליצירת ייצוא של קהל:

בקשת HTTP

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

תשובה של method ‏audienceExports.create מכילה את השם של ייצוא קהל היעד בשדה name, לדוגמה properties/1234567/audienceExports/123. דוגמה לתשובה:

תגובת HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceExport",
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "CREATING",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  }
}

אפשר להשתמש ב-name כדי לשלוח שאילתה לגבי המשתמשים מתוך ייצוא הקהל.

שאילתת מצב המוכנות של ייצוא הקהל

יכול להיות שיחלפו כמה דקות עד שייווצר ייצוא הקהל אחרי הקריאה ל-audienceExports.create.

כדי לבדוק את מצב המוכנות של ייצוא קהל, מפעילים את ה-method‏ audienceExports.get.

משתמשים בשם של ייצוא הקהל מתוך תגובה של audienceExports.create כדי לציין את ייצוא הקהל בבקשה.

הנה דוגמה לבקשה:

בקשת HTTP

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

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

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

תגובת HTTP

{
  "name": "properties/1234567/audienceExports/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "state": "CREATING",
  "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
}

כדי לקבל את הסטטוס של כל ייצוא הקהלים, אפשר להתקשר אל השיטה audienceExports.list.

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

אחרי שנוצר ייצוא של הקהל, קוראים לשיטה audienceExports.query ומציינים את name של ייצוא הקהל בבקשה.

הנה דוגמה לבקשה:

בקשת 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
}