زبان پرسمان Google Ads

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

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

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

«زبان پُرسمان Google Ads» می‌تواند Google Ads API را برای انواع اطلاعات زیر پُرسمان کند:

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

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

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

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

برای جزئیات بیشتر درباره ساختار پُرسمان، به ساختار پُرسمان و دستور زبان Google Ads Query Language مراجعه کنید.

پرسمان برای مشخصه‌های منبع

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

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 برای بررسی سازگاری فیلد و انواع داده استفاده کنید.
  • توجه داشته باشید که برخی‌از فیلدها، به‌ویژه فیلدهایی که شامل حجم زیادی از داده‌ها یا محاسبات پیچیده هستند، می‌توانند هزینه پُرسمان را افزایش دهند.

جهش براساس نتایج پُرسمان

When querying for a given resource, you can immediately take those returned results as objects, modify them, and send them back to the mutate method in that resource's service. در اینجا یک نمونه گردش کار آورده شده است:

  1. اجرای پُرسمان برای همه PAUSED پویشی که ظهورهای بیشتر از ۱۰۰۰ دارند.
  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 مراجعه کنید.

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

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

  • نمای دارایی گسترش نشانی وب نهایی:
    • پشتیبانی از پویش Shopping (نسخه ۲۶ و جدیدتر): final_url_expansion_asset_view علاوه‌بر پویش‌های «بیشینه‌سازی عملکرد» و «جستجو»، از پویش‌های Shopping (campaign.advertising_channel_type = 'SHOPPING') نیز پشتیبانی می‌کند. برای پویش‌های Shopping، می‌توانید براساس فیلدهای ad_group انتخاب و فیلتر کنید، اما نمی‌توانید فیلدهای asset_group را انتخاب کنید.
    • سنجه‌های قابل‌انتخاب (نسخه ۲۵ و جدیدتر): پُرسمان final_url_expansion_asset_view همه سنجه‌های قابل‌انتخاب را برای نما برمی‌گرداند. در نسخه ۲۴ و نسخه‌های قبلی، پاسخ‌ها فقط شامل metrics.conversions و metrics.conversions_value برای پویش‌های «بیشینه‌سازی عملکرد» و metrics.impressions برای پویش‌های «جستجو» است.
  • منابع هدف چرخه حیات: در نسخه ۲۵ و نسخه‌های جدیدتر، همه اهداف چرخه حیات («جذب مشتری جدید»، «حفظ مشتری»، و «حفظ وفاداری») از منابع یکپارچه goal و campaign_goal_config پرس‌وجو می‌شوند و جایگزین customer_lifecycle_goal و campaign_lifecycle_goal می‌شوند (که برای اهداف «جذب مشتری جدید» در نسخه ۲۴ و نسخه‌های قدیمی‌تر، در کنار goal و campaign_goal_config برای اهداف «حفظ مشتری» استفاده می‌شدند).
  • گزارش‌دهی محصول Shopping برای پویش‌های «برنامه»: در نسخه ۲۴ و جدیدتر، منبع shopping_product علاوه‌بر پویش‌های Shopping، «بیشینه‌سازی عملکرد»، «تولید تقاضا»، و «ویدیویی»، ردیف‌های محصول را برای پویش‌های «برنامه» نیز برمی‌گرداند (در نسخه ۲۳، پویش‌های «برنامه» از نتایج shopping_product مستثنی شده‌اند).
  • منابع، بخش‌ها، و سنجه‌های مختص نسخه:
    • نسخه ۲۶ و جدیدتر: شامل منبع search_lift_keyword_bundle، campaign.lift_measurement_config، local_services_lead.campaign، segments.search_lift_keyword_bundle، segments.search_property، و سنجه‌های «بهینه‌گر جستجو» (مثل metrics.relative_search_lift، metrics.normalized_incremental_searches، metrics.search_lift_cost_micros، و metrics.search_lift_impressions).
    • نسخه ۲۵ و جدیدتر: شامل منابع سنجش بهینه‌گر (مانند lift_measurement_config)، بخش‌هایی مانند segments.ad_sub_format_type و segments.loyalty_membership، و سنجه‌های تعامل YouTube (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 را در نسخه ۲۳) برمی‌گردانند. برای جزئیات، محدوده تاریخ را ببینید.

نمونه‌های کد

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

بعدی
دستور زبان پُرسمان