انتخابگرها

انتخابگرها به برنامه‌نویس کمک می‌کنند تا کوئری‌ای بسازد که موجودیت‌های درخواستی گوگل ادز را واکشی کند. با انتخابگرها، می‌توان لیست موجودیت‌های بازیابی شده را محدود کرد و آنها را مرتب کرد. اکثر انتخابگرها روش‌های زیر را دارند:

withCondition()

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

withIds()

مجموعه‌ای از شناسه‌ها را به عنوان یک شرط اضافه می‌کند. یک شرط مبتنی بر شناسه به همراه سایر شرط‌ها با عملگر AND بررسی می‌شود.

forDateRange()

زمانی مورد نیاز است که یک شرط یا بند ترتیب به یک فیلد آماری مانند Ctr یا Impressions اشاره کند. اگر درخواست همه کمپین‌ها با بیش از ۱۰۰ impressions را دارید، اسکریپت‌های Google Ads باید محدوده تاریخ را برای بررسی بدانند.

orderBy()

ترتیب قرارگیری موجودیت‌های برگردانده شده را مشخص می‌کند.

withLimit()

تعداد موجودیت‌های برگردانده شده را به مقدار مشخص شده محدود می‌کند. این تابع به ویژه در ترکیب با orderBy() برای دریافت مواردی مانند "10 کلمه کلیدی با بیشترین تعداد نمایش دیروز" مفید است. به طور پیش‌فرض، همه انتخابگرها این محدودیت را روی 50000 تنظیم می‌کنند. می‌توانید با تعیین دستی یک محدودیت، این محدودیت را افزایش دهید.

این متدها را می‌توان به هر ترتیبی فراخوانی کرد. یک استثنا orderBy() است که در آن ترتیب فراخوانی‌ها واقعاً مهم است: چندین فراخوانی به این متد، چندین بند ترتیب را مشخص می‌کند و آنها به ترتیب اعمال می‌شوند. قطعه کد زیر را در نظر بگیرید:

selector = selector.forDateRange("LAST_14_DAYS")
    .orderBy("metrics.clicks DESC")
    .orderBy("metrics.ctr ASC");

نتایج بر اساس تعداد کلیک‌ها به صورت نزولی مرتب می‌شوند. نتایجی که تعداد کلیک‌هایشان برابر است، بر اساس Ctr به صورت صعودی مرتب می‌شوند.

فراخوانی متدهای یک انتخابگر می‌تواند به صورت زنجیره‌ای انجام شود. کد زیر

var campaignSelector = AdsApp.campaigns();
campaignSelector.withCondition("metrics.clicks > 10");
campaignSelector.withCondition("metrics.impressions > 1000");
campaignSelector.orderBy("metrics.impressions DESC");
campaignSelector.forDateRange("YESTERDAY");

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

var campaignSelector = AdsApp.campaigns()
  .withCondition("metrics.clicks > 10")
  .withCondition("metrics.impressions > 1000")
  .orderBy("metrics.impressions DESC")
  .forDateRange("YESTERDAY");

پس از ساخت سلکتور، می‌توان با فراخوانی selector.get() یک Iterator از آن دریافت کرد.

نکته: برخی از انتخابگرها (برای مثال AdParamSelector و LabelSelector ) متدهای کمتری را نمایش می‌دهند، زیرا روی موجودیت‌هایی عمل می‌کنند که محدودتر هستند (هیچ آمار یا فیلد معناداری برای مرتب‌سازی ندارند).

برای نکات و ترفندهای مربوط به استفاده کارآمد از selector، بخش «بهترین شیوه‌ها» (Best Practices) را مطالعه کنید.