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

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

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

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

סקירה

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

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

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

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

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

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

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

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

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

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

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

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

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. תגובה לדוגמה:

{
  "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.

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

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

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

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

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

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

{
  "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 של ייצוא הקהלים בבקשה.

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

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

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

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

{
  "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
}