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

קהלים ב-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}. כדי לקבל את הערך הזה, אתם יכולים להשתמש ב-method‏ 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.

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

אחרי שהייצוא של הקהל נוצר, מפעילים את ה-method‏ 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
}