Method: properties.audienceLists.query

فهرست مخاطبان کاربران را بازیابی می‌کند. پس از ایجاد مخاطب، کاربران بلافاصله برای فهرست‌بندی در دسترس نیستند. اولاً، درخواستی به audienceLists.create برای ایجاد فهرست مخاطبان کاربران ضروری است و ثانیاً، این متد برای بازیابی کاربران موجود در فهرست مخاطبان استفاده می‌شود.

برای آشنایی با فهرست‌های مخاطبان به همراه مثال، به بخش «ایجاد فهرست مخاطبان» مراجعه کنید.

مخاطبان در گوگل آنالیتیکس ۴ به شما این امکان را می‌دهند که کاربران خود را بر اساس اهمیت کسب و کارتان دسته‌بندی کنید. برای کسب اطلاعات بیشتر، به https://support.google.com/analytics/answer/9267572 مراجعه کنید.

این روش در نسخه بتا و در آدرس audienceExports.query در دسترس است. برای ارائه بازخورد خود در مورد این API، فرم بازخورد API Export Audience در گوگل آنالیتیکس را تکمیل کنید.

درخواست HTTP

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

این URL از سینتکس Transcoding در gRPC استفاده می‌کند.

پارامترهای مسیر

پارامترها
name

string

الزامی. نام فهرست مخاطبانی که قرار است کاربران از آن بازیابی شوند. قالب: properties/{property}/audienceLists/{audienceList}

درخواست بدنه

بدنه درخواست شامل داده‌هایی با ساختار زیر است:

نمایش JSON 
{
  "offset": string,
  "limit": string
}
فیلدها
offset

string ( int64 format)

اختیاری. تعداد ردیف ردیف شروع. ردیف اول به عنوان ردیف ۰ شمرده می‌شود.

هنگام صفحه‌بندی، درخواست اول آفست را مشخص نمی‌کند؛ یا به طور معادل، آفست را روی ۰ تنظیم می‌کند؛ درخواست اول limit اول ردیف‌ها را برمی‌گرداند. درخواست دوم آفست را روی limit درخواست اول تنظیم می‌کند؛ درخواست دوم limit دوم ردیف‌ها را برمی‌گرداند.

برای کسب اطلاعات بیشتر در مورد این پارامتر صفحه‌بندی، به صفحه‌بندی مراجعه کنید.

limit

string ( int64 format)

اختیاری. تعداد ردیف‌هایی که باید برگردانده شوند. اگر مشخص نشود، ۱۰۰۰۰ ردیف برگردانده می‌شود. API حداکثر ۲۵۰۰۰۰ ردیف را در هر درخواست برمی‌گرداند، مهم نیست چند ردیف درخواست کنید. limit باید مثبت باشد.

اگر تعداد مقادیر بُعد به اندازه‌ی limit نباشد، API می‌تواند ردیف‌های کمتری نسبت به 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 است. برای مثال، اگر یک پرس‌وجو ۱۷۵ ردیف برگرداند و limit 50 را در درخواست API لحاظ کند، پاسخ شامل rowCount 175 اما فقط ۵۰ ردیف خواهد بود.

برای کسب اطلاعات بیشتر در مورد این پارامتر صفحه‌بندی، به صفحه‌بندی مراجعه کنید.

دامنه‌های مجوز

به یکی از حوزه‌های OAuth زیر نیاز دارد:

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

ردیف مخاطبان

ویژگی‌های مقدار بُعد برای ردیف کاربر مخاطب.

نمایش JSON 
{
  "dimensionValues": [
    {
      object (AudienceDimensionValue)
    }
  ]
}
فیلدها
dimensionValues[]

object ( 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

اگر نوع بُعد رشته‌ای باشد، به عنوان یک رشته مقداردهی می‌شود.

پایان میدان‌های ناسازگار.