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

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

אפשר לייצא את הקהלים, כולל קובץ snapshot של המשתמשים שלהם, באמצעות Data 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.

כדי לבדוק את סטטוס הנכונות של ייצוא קהל, אפשר להפעיל את השיטה 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
}