REST Resource: properties.audienceLists

منبع: فهرست مخاطبان

فهرست مخاطبان، فهرستی از کاربران یک مخاطب در زمان ایجاد فهرست است. یک مخاطب ممکن است چندین فهرست مخاطب برای روزهای مختلف داشته باشد.

نمایش JSON 
{
  "name": string,
  "audience": string,
  "audienceDisplayName": string,
  "dimensions": [
    {
      object (AudienceDimension)
    }
  ],
  "creationQuotaTokensCharged": integer,
  "state": enum (State),
  "beginCreatingTime": string,
  "rowCount": integer,
  "errorMessage": string,
  "percentageCompleted": number,
  "recurringAudienceList": string,
  "webhookNotification": {
    object (WebhookNotification)
  }
}
فیلدها
name

string

فقط خروجی. شناسه. نام منبع فهرست مخاطبان که هنگام ایجاد اختصاص داده شده است. این نام منبع، این AudienceList را مشخص می‌کند.

قالب: properties/{property}/audienceLists/{audienceList}

audience

string

الزامی. نام منبع مخاطب. این نام منبع، مخاطبی را که فهرست شده است مشخص می‌کند و بین APIهای Analytics Data و Admin به اشتراک گذاشته می‌شود.

قالب: properties/{property}/audiences/{audience}

audienceDisplayName

string

فقط خروجی. نام نمایشی توصیفی برای این مخاطب. به عنوان مثال، "خریداران".

dimensions[]

object ( AudienceDimension )

الزامی. ابعاد درخواست شده و نمایش داده شده در پاسخ پرس و جو.

creationQuotaTokensCharged

integer

فقط خروجی. کل توکن‌های سهمیه‌ای که هنگام ایجاد AudienceList شارژ شده‌اند. از آنجا که این تعداد توکن بر اساس فعالیت از حالت CREATING محاسبه می‌شود، این توکن‌های شارژ شده پس از ورود AudienceList به حالت‌های ACTIVE یا FAILED ثابت خواهند شد.

state

enum ( State )

فقط خروجی. وضعیت فعلی این فهرست مخاطبان.

beginCreatingTime

string ( Timestamp format)

فقط خروجی. زمانی که audienceLists.create فراخوانی شده و AudienceList حالت CREATING را آغاز کرده است.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "Z" نیز پذیرفته می‌شوند. مثال‌ها: "2014-10-02T15:01:23Z" ، "2014-10-02T15:01:23.045123456Z" یا "2014-10-02T15:01:23+05:30" .

rowCount

integer

فقط خروجی. تعداد کل ردیف‌ها در نتیجه‌ی AudienceList.

errorMessage

string

فقط خروجی. پیام خطا زمانی نمایش داده می‌شود که لیست مخاطبان در حین ایجاد با شکست مواجه شود. یکی از دلایل رایج چنین شکستی، اتمام سهمیه است.

percentageCompleted

number

فقط خروجی. درصد تکمیل‌شده برای این خروجی مخاطب بین ۰ تا ۱۰۰ است.

recurringAudienceList

string

فقط خروجی. فهرست مخاطبان تکراری که این فهرست مخاطبان را ایجاد کرده‌اند. فهرست‌های مخاطبان تکراری روزانه فهرست مخاطبان ایجاد می‌کنند.

اگر فهرست مخاطبان مستقیماً ایجاد شود، هیچ فهرست مخاطب تکراری مرتبطی نخواهد داشت و این فیلد خالی خواهد بود.

webhookNotification

object ( WebhookNotification )

اختیاری. اعلان‌های وب‌هوک را برای ارسال از API داده‌های گوگل آنالیتیکس به سرور وب‌هوک شما پیکربندی می‌کند. استفاده از وب‌هوک‌ها اختیاری است. در صورت عدم استفاده، باید از این API نظرسنجی کنید تا مشخص شود چه زمانی لیست مخاطبان آماده استفاده است. وب‌هوک‌ها امکان ارسال اعلان به سرورهای شما را فراهم می‌کنند و از نیاز به نظرسنجی جلوگیری می‌کنند.

یک یا دو درخواست POST به وب‌هوک ارسال می‌شود. اولین درخواست POST بلافاصله ارسال می‌شود و لیست مخاطبان تازه ایجاد شده را در حالت CREATING نشان می‌دهد. درخواست POST دوم پس از تکمیل ایجاد لیست مخاطبان (چه در حالت ACTIVE و چه در حالت FAILED) ارسال می‌شود.

اگر لیست‌های مخاطبان یکسان پشت سر هم درخواست شوند، لیست‌های مخاطبان دوم و بعدی می‌توانند از حافظه پنهان (cache) ارائه شوند. در این صورت، متد create list audience می‌تواند لیستی از مخاطبان را که از قبل فعال است، برگرداند. در این سناریو، فقط یک درخواست POST به webhook ارسال می‌شود.

ایالت

فهرست مخاطبان (AudienceList) در حال حاضر در این حالت وجود دارد.

انوم‌ها
STATE_UNSPECIFIED حالت نامشخص هرگز استفاده نخواهد شد.
CREATING AudienceList در حال حاضر در حال ایجاد است و در آینده در دسترس خواهد بود. ایجاد بلافاصله پس از فراخوانی audienceLists.create رخ می‌دهد.
ACTIVE فهرست مخاطبان (AudienceList) به طور کامل ایجاد شده و آماده‌ی پرس‌وجو است. فهرست مخاطبان (AudienceList) به صورت غیرهمزمان از طریق یک درخواست به‌روزرسانی می‌شود تا فعال شود؛ این اتفاق مدتی (برای مثال ۱۵ دقیقه) پس از فراخوانی اولیه‌ی ایجاد رخ می‌دهد.
FAILED ایجاد فهرست مخاطبان ناموفق بود. ممکن است درخواست مجدد این فهرست مخاطبان موفقیت‌آمیز باشد.

روش‌ها

create

 فهرستی از مخاطبان برای بازیابی بعدی ایجاد می‌کند.

get

 فراداده‌های پیکربندی مربوط به یک لیست مخاطب خاص را دریافت می‌کند.

list

 تمام فهرست‌های مخاطبان یک ملک را فهرست می‌کند.

query

 فهرستی از کاربران مخاطب را بازیابی می‌کند.