زبان جستجوی تبلیغات گوگل

اصطلاحات کلیدی

منبع
یک موجودیت در گوگل ادز، مانند campaign یا ad_group .
بخش
بُعدی که برای گروه‌بندی داده‌ها استفاده می‌شود، مانند segments.date یا segments.device . وقتی سگمنت‌ها در عبارت SELECT به همراه معیارها گنجانده می‌شوند، معیارها بر اساس سگمنت تقسیم می‌شوند.
متریک
معیاری برای سنجش عملکرد، مانند metrics.impressions یا metrics.clicks .
منبع منتسب
منبعی که به طور ضمنی در بند FROM به منبع اصلی متصل شده است و به شما امکان می‌دهد ویژگی‌های آن را به همراه ویژگی‌های منبع اصلی انتخاب کنید.

پرس و جو برای اطلاعات منابع یا فراداده

زبان جستجوی گوگل ادز می‌تواند از API گوگل ادز برای انواع اطلاعات زیر جستجو کند:

  • منابع و ویژگی‌ها، بخش‌ها و معیارهای مرتبط با آنها با استفاده از جستجوی GoogleAdsService یا SearchStream : نتیجه‌ی یک پرس‌وجوی GoogleAdsService فهرستی از نمونه‌های GoogleAdsRow است که هر GoogleAdsRow نشان‌دهنده‌ی یک منبع است.

    اگر هرگونه ویژگی یا معیاری درخواست شود، آن ردیف شامل آن فیلدها نیز می‌شود. اگر هرگونه سگمنتی درخواست شود، پاسخ همچنین یک ردیف اضافی برای هر تاپل سگمنت-منبع نشان می‌دهد.

  • فراداده درباره فیلدها و منابع موجود در GoogleAdsFieldService : این سرویس کاتالوگی از فیلدهای قابل پرس‌وجو به همراه جزئیات مربوط به سازگاری و نوع آنها ارائه می‌دهد.

    نتیجه‌ی حاصل از یک کوئری GoogleAdsFieldService فهرستی از نمونه‌های GoogleAdsField است که هر GoogleAdsField حاوی جزئیاتی در مورد فیلد درخواستی است.

برای جزئیات بیشتر در مورد ساختار پرس‌وجو، به ساختار پرس‌وجو و دستور زبان پرس‌وجوی گوگل ادز مراجعه کنید.

پرس و جو برای ویژگی‌های منابع

در اینجا مثالی از یک پرس‌وجوی ساده برای ویژگی‌های منبع کمپین آورده شده است که نحوه‌ی برگرداندن شناسه، نام و وضعیت کمپین را نشان می‌دهد:

SELECT
  campaign.id,
  campaign.name,
  campaign.status
FROM campaign
ORDER BY campaign.id

این کوئری بر اساس شناسه کمپین مرتب می‌شود. هر GoogleAdsRow حاصل، نشان‌دهنده یک شیء campaign است که با فیلدهای انتخاب شده، از جمله resource_name کمپین، پر شده است.

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

پرس و جو برای معیارها

در کنار ویژگی‌های انتخاب‌شده برای یک منبع مشخص، می‌توانید معیارهای مرتبط را نیز جستجو کنید:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
ORDER BY campaign.id

این کوئری فقط کمپین‌هایی را فیلتر می‌کند که وضعیتشان PAUSED است و بیش از ۱۰۰۰ بازدید داشته‌اند، و بر اساس شناسه کمپین مرتب می‌شوند. هر GoogleAdsRow حاصل، یک فیلد metrics خواهد داشت که با معیارهای انتخاب شده پر شده است.

برای فهرستی از معیارهای قابل استعلام، به مستندات Metrics مراجعه کنید.

پرس و جو برای بخش ها

در کنار ویژگی‌های انتخاب‌شده برای یک منبع مشخص، می‌توانید بخش‌های مرتبط را نیز جستجو کنید:

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  metrics.impressions,
  segments.date
FROM campaign
WHERE campaign.status = 'PAUSED'
  AND metrics.impressions > 1000
  AND segments.date DURING LAST_30_DAYS
ORDER BY campaign.id

مشابه جستجوی معیارها، این جستجو فقط کمپین‌هایی را فیلتر می‌کند که وضعیت PAUSED دارند و بیش از ۱۰۰۰ بازدید داشته‌اند. با این حال، این جستجو داده‌ها را بر اساس تاریخ بخش‌بندی می‌کند. این منجر به این می‌شود که هر GoogleAdsRow حاصل، یک تاپل از یک کمپین و بخش تاریخ را نشان دهد. بخش‌بندی، معیارهای انتخاب شده را تقسیم می‌کند و بر اساس هر بخش در عبارت SELECT گروه‌بندی می‌کند.

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

در یک پرس‌وجو برای یک منبع مشخص، در صورت وجود، می‌توانید در مقابل منابع مرتبط دیگر به هم بپیوندید. این منابع مرتبط به عنوان "منابع نسبت داده شده" شناخته می‌شوند. می‌توانید با انتخاب یک ویژگی در پرس‌وجوی خود، به طور ضمنی در مقابل منابع نسبت داده شده به هم بپیوندید.

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  bidding_strategy.name
FROM campaign
ORDER BY campaign.id

این کوئری نه تنها ویژگی‌های کمپین را انتخاب می‌کند، بلکه ویژگی‌های مرتبط را نیز از هر کمپین انتخاب شده استخراج می‌کند. هر GoogleAdsRow حاصل، نشان دهنده یک شیء campaign است که با ویژگی‌های کمپین انتخاب شده و همچنین ویژگی استراتژی پیشنهاد قیمت انتخاب شده bidding_strategy.name پر شده است.

برای اطلاع از منابع ارجاعی موجود برای کوئری‌های کمپین، به مستندات مرجع Campaign مراجعه کنید.

بهترین شیوه‌ها

  • فقط فیلدهای مورد نیاز خود را انتخاب کنید تا از زمان پاسخ طولانی و وقفه‌ها جلوگیری شود.
  • برای جلوگیری از پردازش مجموعه نتایج بزرگ، LIMIT در طول توسعه و آزمایش استفاده کنید.
  • برای به حداقل رساندن انتقال داده و اندازه پاسخ، فیلترها را در عبارت WHERE اعمال کنید.
  • قبل از ساخت کوئری‌های پیچیده، از GoogleAdsFieldService برای بررسی سازگاری فیلدها و انواع داده‌ها استفاده کنید.
  • توجه داشته باشید که برخی از فیلدها، به ویژه آنهایی که شامل حجم زیادی از داده‌ها یا محاسبات پیچیده هستند، می‌توانند هزینه پرس و جو را افزایش دهند.

تغییر بر اساس نتایج پرس و جو

هنگام جستجوی یک منبع مشخص، می‌توانید بلافاصله آن نتایج برگشتی را به عنوان اشیاء در نظر بگیرید، آنها را تغییر دهید و به متد mutate در سرویس آن منبع ارسال کنید. در اینجا یک نمونه گردش کار آمده است:

  1. برای همه کمپین‌های PAUSED که تعداد نمایش (impressions) آنها بیش از ۱۰۰۰ است، یک کوئری اجرا کنید.
  2. شیء Campaign را از فیلد campaign هر GoogleAdsRow در پاسخ دریافت کنید.
  3. وضعیت هر کمپین را از PAUSED به ENABLED تغییر دهید.
  4. تابع CampaignService.MutateCampaigns به همراه کمپین‌های اصلاح‌شده و یک FieldMask متناظر برای به‌روزرسانی آنها فراخوانی کنید.

فراداده فیلد

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

SELECT
  name,
  category,
  selectable,
  filterable,
  sortable,
  selectable_with,
  data_type,
  is_repeated
WHERE name = "<INSERT_RESOURCE_OR_FIELD>"

شما می‌توانید در این کوئری <INSERT_RESOURCE_OR_FIELD> با یک منبع (مانند customer یا campaign ) یا فیلد (مانند campaign.id ، metrics.impressions یا ad_group.id ) جایگزین کنید.

برای مشاهده فهرست فیلدهای قابل جستجو، به مستندات GoogleAdsField مراجعه کنید.

تفاوت‌های خاص نسخه

اگرچه سینتکس، بندها و عملگرهای زبان پرس‌وجوی گوگل ادز در تمام نسخه‌های پشتیبانی‌شده‌ی API گوگل ادز (نسخه‌های ۲۳، ۲۴ و ۲۵) یکسان هستند، اما فهرست منابع قابل پرس‌وجو، بخش‌ها، معیارها و رفتارهای گزارش‌دهی در نسخه‌های اصلی متفاوت است. برای بررسی فیلدها و قوانین سازگاری برای آن نسخه، GoogleAdsFieldService در نقطه پایانی نسخه API هدف پرس‌وجو کنید:

  • منابع هدف چرخه عمر: در نسخه ۲۵ و بعد از آن، تمام اهداف چرخه عمر (جذب مشتری جدید، حفظ مشتری و حفظ وفاداری) از منابع یکپارچه goal و campaign_goal_config جستجو می‌شوند و جایگزین customer_lifecycle_goal و campaign_lifecycle_goal می‌شوند (که برای اهداف جذب مشتری جدید در نسخه ۲۴ و قبل از آن، در کنار goal و campaign_goal_config برای اهداف حفظ مشتری استفاده می‌شدند).
  • معیارهای نمای دارایی گسترش نهایی URL: در نسخه ۲۵ و بالاتر، کوئری final_url_expansion_asset_view تمام معیارهای قابل انتخاب برای نما را برمی‌گرداند. در نسخه ۲۴ و قبل از آن، پاسخ‌ها فقط شامل metrics.conversions و metrics.conversions_value برای کمپین‌های Performance Max و metrics.impressions برای کمپین‌های Search می‌شوند.
  • گزارش محصول خرید برای کمپین‌های اپلیکیشن: در نسخه ۲۴ و بعد از آن، منبع shopping_product علاوه بر کمپین‌های Shopping، Performance Max، Demand Gen و Video، ردیف‌های محصول را برای کمپین‌های اپلیکیشن نیز برمی‌گرداند (در نسخه ۲۳، کمپین‌های اپلیکیشن از نتایج shopping_product حذف می‌شوند).
  • منابع، بخش‌ها و معیارهای خاص نسخه:
    • نسخه ۲۵ و بالاتر: شامل منابع اندازه‌گیری افزایش بازدید (مانند lift_measurement_config )، بخش‌هایی مانند segments.ad_sub_format_type و segments.loyalty_membership و معیارهای تعامل یوتیوب ( metrics.youtube_likes ، metrics.youtube_comments و metrics.youtube_shares ) می‌شود. local_services_lead.contact_details.email را حذف می‌کند (که در نسخه ۲۴ و قبل از آن قابل انتخاب است).
    • نسخه ۲۴ و بالاتر: شامل منبع cart_data_sales_view ، segments.conversion_attribution_event_type در shopping_performance_view ، segments.mobile_device_platform و segments.ad_network_type در performance_max_placement_view می‌شود. campaign.video_brand_safety_suitability (که با customer.video_brand_safety_suitability جایگزین شده است)، segments.ad_sub_network_type در campaign_budget و segments.click_type در ad_group_asset ، campaign_asset و customer_asset (که فقط در نسخه ۲۳ قابل انتخاب هستند) را حذف می‌کند.
  • کد خطای نگاه به تاریخ جزئی: کوئری‌هایی که بر اساس segments.date ، segments.week یا segments.hour (یا فیلتر روی یک محدوده تاریخی زیرماهانه) فراتر از پنجره نگاه به تاریخ ۳۷ ماهه، بخش‌بندی می‌شوند، در نسخه ۲۴ و بالاتر DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED (یا در نسخه ۲۳ DateRangeError.UNKNOWN ) را برمی‌گردانند. برای جزئیات بیشتر به Date ranges مراجعه کنید.

مثال‌های کد

کتابخانه‌های کلاینت نمونه‌هایی از استفاده از زبان جستجوی گوگل ادز در GoogleAdsService دارند. پوشه عملیات پایه نمونه‌هایی مانند GetCampaigns ، GetKeywords و SearchForGoogleAdsFields را دارد.

بعدی
پرس و جو گرامر