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

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

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

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

אחרי שנוצר ייצוא של הקהל, קוראים לשיטה 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
}