Method: properties.audienceLists.query

מאחזר רשימת חברים בקהל של משתמשים. אחרי שיוצרים קהל, המשתמשים לא זמינים מיידית להצגה ברשימה. קודם צריך לשלוח בקשה אל audienceLists.create כדי ליצור רשימת משתמשים בקהל, ואז משתמשים בשיטה הזו כדי לאחזר את המשתמשים ברשימת הקהלים.

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

קהלים ב-Google Analytics 4 מאפשרים לכם לפלח את המשתמשים בדרכים שחשובות לעסק. מידע נוסף זמין בכתובת https://support.google.com/analytics/answer/9267572.

השיטה הזו זמינה ברמת יציבות בטא ב-audienceExports.query. כדי לשלוח משוב על ה-API הזה, אפשר למלא את הטופס משוב על Google Analytics Audience Export API.

בקשת HTTP

POST https://analyticsdata.googleapis.com/v1alpha/{name=properties/*/audienceLists/*}:query

כתובת ה-URL כתובה בתחביר של gRPC Transcoding.

פרמטרים של נתיב

פרמטרים
name

string

חובה. השם של רשימת החברים בקהל שממנה רוצים לאחזר משתמשים. פורמט: properties/{property}/audienceLists/{audienceList}

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג JSON 
{
  "offset": string,
  "limit": string
}
שדות
offset

string (int64 format)

אופציונלי. מספר השורה של שורת ההתחלה. השורה הראשונה נספרת כשורה 0.

כשמבצעים החלפה בין דפים, הבקשה הראשונה לא מציינת היסט, או שהיא מגדירה את ההיסט ל-0. הבקשה הראשונה מחזירה את limit השורות הראשונות. הבקשה השנייה מגדירה את ההיסט ל-limit של הבקשה הראשונה, והיא מחזירה את limit השורות השני.

מידע נוסף על פרמטר מעבר העמוד זמין במאמר בנושא מעברי עמוד.
limit

string (int64 format)

אופציונלי. מספר השורות שיש להחזיר. אם לא מציינים ערך, מוחזרות 10,000 שורות. ה-API מחזיר עד 250,000 שורות לכל בקשה, לא משנה כמה שורות ביקשתם. הערך של limit חייב להיות חיובי.

בנוסף, ה-API יכול להחזיר פחות שורות מהערך המבוקש של limit, אם אין מספיק ערכים של מאפיינים כמו הערך של limit.

מידע נוסף על פרמטר מעבר העמוד זמין במאמר בנושא מעברי עמוד.

גוף התשובה

רשימת משתמשים ברשימת חברים בקהל.

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל נתונים במבנה הבא:

ייצוג JSON 
{
  "audienceRows": [
    {
      object (AudienceRow)
    }
  ],
  "audienceList": {
    object (AudienceList)
  },
  "rowCount": integer
}
שדות
audienceRows[]

object (AudienceRow)

שורות לכל משתמש ברשימת חברים בקהל. מספר השורות בתגובה הזו יהיה קטן או שווה לגודל הדף של הבקשה.
audienceList

object (AudienceList)

נתוני ההגדרה של AudienceList שנשלחה לגביה שאילתה. חזרתי כדי לעזור לך להבין את השורות של הקהל בתשובה הזו. לדוגמה, המאפיינים ב-AudienceList הזה תואמים לעמודות ב-AudienceRows.
rowCount

integer

המספר הכולל של השורות בתוצאה של AudienceList. הערך של rowCount לא תלוי במספר השורות שמוחזרות בתגובה, בפרמטר הבקשה limit ובפרמטר הבקשה offset. לדוגמה, אם שאילתה מחזירה 175 שורות וכוללת limit מתוך 50 בבקשת ה-API, התשובה תכיל rowCount מתוך 175 אבל רק 50 שורות.

מידע נוסף על פרמטר מעבר העמוד זמין במאמר בנושא מעברי עמוד.

היקפי הרשאות

נדרשת אחת מההרשאות הבאות של OAuth:

  • https://www.googleapis.com/auth/analytics.readonly
  • https://www.googleapis.com/auth/analytics

AudienceRow

מאפיינים של ערכי מאפיינים בשורה של משתמשים בקהל.

ייצוג JSON 
{
  "dimensionValues": [
    {
      object (AudienceDimensionValue)
    }
  ]
}
שדות
dimensionValues[]

object (AudienceDimensionValue)

כל מאפיין של ערך מאפיין של משתמש בקהל. יוסף ערך מאפיין אחד לכל עמודת מאפיין שנדרשה.

AudienceDimensionValue

הערך של מאפיין.

ייצוג JSON 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "value": string
  // End of mutually exclusive fields.
}
שדות
סוג אחד של ערך מאפיין. בהמשך מפורטת רשימה של שדות שאי אפשר להשתמש בהם בו-זמנית. רק אחד מהשדות הבאים יוגדר בתשובה:
value

string

הערך כמחרוזת אם סוג המאפיין הוא מחרוזת.
סוף השדות הבלעדיים.