ساختار پُرسمان

پرس‌وجوهای مربوط به فیلدهای منبع، بخش، و سنجه را می‌توان به روش GoogleAdsService Search یا SearchStream ارسال کرد. برای ساختن پُرسمان در «زبان پُرسمان Google Ads»، آن را بااستفاده از دستور زبان بسازید. برای نمای کلی «زبان پُرسمان Google Ads»، نمای کلی «زبان پُرسمان Google Ads» را ببینید. پُرسمان از تعدادی بند تشکیل شده است:

  • SELECT
  • FROM
  • WHERE
  • ORDER BY
  • LIMIT
  • PARAMETERS

بندها از نام فیلد، نام منبع، عامل‌ها، شرایط، و ترتیب‌ها استفاده می‌کنند تا به شما کمک کنند داده‌های صحیح را انتخاب کنید. وقتی در یک پُرسمان ترکیب شد، می‌توانید درخواست را به Google Ads API ارسال کنید.

عبارت‌ها

بخش‌های زیر هدف و دستور زبان هریک از بندهای «زبان پُرسمان Google Ads» را شرح می‌دهد.

انتخاب

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

نمونه پُرسمان زیر مثالی از انتخاب مشخصه‌ها برای یک منبع معین را نشان می‌دهد:

SELECT
  campaign.id,
  campaign.name
FROM campaign

می‌توانید انواع مختلف فیلد را در یک درخواست درخواست کنید، برای مثال:

SELECT
  campaign.id,
  campaign.name,
  bidding_strategy.id,
  bidding_strategy.name,
  segments.device,
  segments.date,
  metrics.impressions,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
  • فیلدهای منبع اصلی
    • campaign.id
    • campaign.name
  • فیلدهای منبع منسوب
    • bidding_strategy.id
    • bidding_strategy.name
  • فیلدهای بخش
    • segments.device
    • segments.date
  • سنجه‌ها
    • metrics.impressions
    • metrics.clicks
  • فیلدهایی که قابل‌انتخاب نیستند پُرسمان می‌شوند. این فیلدها دارای مشخصه فراداده selectable هستند که به‌عنوان false علامت‌گذاری شده است.
  • انتخاب مشخصه‌های فیلدهای تکراری. این فیلدها دارای مشخصه فراداده is_repeated هستند که به‌عنوان true علامت‌گذاری شده است.
  • انتخاب فیلدهایی که برای منبع ارائه‌شده در عبارت FROM دردسترس نیستند. مشخصه‌های برخی‌از منابع را نمی‌توان با هم انتخاب کرد و فقط زیرمجموعه‌ای از همه سنجه‌ها و بخش‌ها برای منبع در بند FROM دردسترس است.
  • انتخاب بخش‌ها یا سنجه‌هایی که با یکدیگر سازگار نیستند. برای اطلاعات بیشتر، بخش‌بندی را ببینید.

اطلاعات مربوط به شرایط قبلی را می‌توانید در اسناد مرجع ما یا از GoogleAdsFieldService پیدا کنید.

فرستنده

بند FROM منبع اصلی را برای برگرداندن مشخص می‌کند. منبع در عبارت FROM مشخص می‌کند که از چه فیلدهایی می‌توان در همه عبارت‌های دیگر برای پُرسمان داده‌شده استفاده کرد. فقط یک منبع را می‌توانید در بند FROM مشخص کنید. بند FROM در پُرسمان برای GoogleAdsService Search یا SearchStream الزامی است. بااین‌حال، هنگام استفاده از GoogleAdsFieldService، عبارت FROM نباید مشخص شود.

درحالی‌که فقط یک منبع می‌تواند در عبارت FROM برای پُرسمان داده‌شده وجود داشته باشد، فیلدهای منابع منسوب نیز ممکن است دردسترس باشند. این منابع به‌طور ضمنی با منبع در عبارت FROM پیوند داده می‌شوند، بنابراین فقط باید مشخصه‌های آن‌ها را به عبارت SELECT اضافه کنید تا مقادیر آن‌ها برگردانده شود. همه منابع دارای منبع منسوب نیستند. در مثال زیر، می‌توانید هم شناسه گروه آگهی و هم شناسه پویش را از گروه‌های آگهی درخواست کنید:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

فیلد resource_name منبع اصلی همیشه برگردانده می‌شود. در مثال زیر، ad_group.resource_name در پاسخ گنجانده شده است، هرچند به‌طور صریح در پُرسمان انتخاب نشده است:

SELECT ad_group.id
FROM ad_group

همین امر برای منابع منسوب‌شده نیز صادق است، وقتی حداقل یک فیلد انتخاب شده باشد. برای مثال، campaign.resource_name در پاسخ به پرسمان زیر گنجانده شده است:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

WHERE

بند WHERE شرایطی را مشخص می‌کند که باید هنگام فیلتر کردن داده‌ها برای درخواست اعمال شود. هنگام استفاده از عبارت WHERE، یک یا چند شرط را مشخص کنید که با AND از هم جدا شده باشند. شرایط معمولاً از الگوی field_name Operator value پیروی می‌کنند (یا از BETWEEN value AND value، IS NULL، یا IS NOT NULL استفاده می‌کنند). عبارت WHERE در پرسمان اختیاری است.

مثال زیر از WHERE برای برگرداندن سنجه‌ها از یک دوره زمانی معین استفاده می‌کند:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

می‌توانید چند شرط را برای فیلتر کردن داده‌ها ترکیب کنید. این مثال تعداد کلیک‌ها را برای همه کمپین‌های دارای ظهور در تلفن همراه در ۳۰ روز گذشته درخواست می‌کند:

SELECT
  campaign.id,
  campaign.name,
  segments.device,
  metrics.clicks
FROM campaign
WHERE metrics.impressions > 0
  AND segments.device = 'MOBILE'
  AND segments.date DURING LAST_30_DAYS

بخش‌های موجود در عبارت WHERE باید در عبارت SELECT نیز وجود داشته باشند، به‌جز بخش‌های تاریخ زیر که به آن‌ها بخش‌های تاریخ پایه گفته می‌شود:

  • segments.date
  • segments.week
  • segments.month
  • segments.quarter
  • segments.year

در پُرسمان زیر، segments.date انتخاب شده است. چون این بخش یک بخش تاریخ پایه است، باید یک محدوده تاریخ محدود در عبارت WHERE متشکل از بخش‌های تاریخ پایه ارائه دهید:

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

همه بخش‌هایی که شرط قبلی را برآورده می‌کنند عبارت‌اند از segments.date، segments.week، segments.month، segments.quarter، و segments.year. اگر هرکدام از این بخش‌ها انتخاب شود، حداقل یکی از آن‌ها باید در عبارت WHERE استفاده شود.

برای جزئیات بیشتر درباره فیلتر کردن تاریخ، محدوده تاریخ را ببینید.

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

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

مرتب‌سازی براساس

جمله ORDER BY ترتیب بازگرداندن نتایج را مشخص می‌کند. این کار به شما امکان می‌دهد داده‌ها را براساس نام فیلد به‌ترتیب صعودی یا نزولی مرتب کنید. هر ترتیب به‌صورت field_name و به‌دنبال آن ASC یا DESC مشخص می‌شود. اگر هیچ‌کدام از ASC یا DESC مشخص نشده باشد، ترتیب به‌طور پیش‌فرض روی ASC قرار می‌گیرد. بند ORDER BY در پُرسمان اختیاری است.

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

SELECT
  campaign.name,
  metrics.clicks
FROM campaign
ORDER BY metrics.clicks DESC

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

SELECT
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks
FROM ad_group
ORDER BY
  campaign.name,
  metrics.impressions DESC,
  metrics.clicks DESC

حد

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

برای مثال، LIMIT می‌تواند تعداد کل نتایج را برای پُرسمان زیر محدود کند:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

پارامترها

بند PARAMETERS به شما امکان می‌دهد پارامترهای فراداده را برای درخواست مشخص کنید. این پارامترها ممکن است بر انواع ردیف‌هایی که برگردانده می‌شوند تأثیر بگذارند.

پارامترهای متا زیر پشتیبانی می‌شوند:

include_drafts

برای برگرداندن نهادهای پیش‌نویس، include_drafts را روی true تنظیم کنید. پیش‌فرض false است.

برای مثال، پُرسمان زیر پویش‌های پیش‌نویس را همراه با پویش‌های معمولی واکشی می‌کند:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts = true

omit_unselected_resource_names

omit_unselected_resource_names را روی true تنظیم کنید تا نام منبع هر نوع منبع در پاسخ حذف شود، مگراینکه صریحاً در بند SELECT درخواست شده باشد. پیش‌فرض false است.

پُرسمان منابع برگردانده‌شده 
SELECT
  campaign.name,
  customer.id
FROM campaign
  • campaign.resource_name
  • customer.resource_name

omit_unselected_resource_names به‌طور پیش‌فرض روی false تنظیم شده است، بنابراین همه فیلدهای resource_name برگردانده می‌شوند.

 
SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

هیچ‌کدام

omit_unselected_resource_names به‌عنوان true مشخص شده است، و نه campaign.resource_name و نه customer.resource_name بخشی از عبارت SELECT نیستند.

 
SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true
  • campaign.resource_name

omit_unselected_resource_names به‌عنوان true مشخص شده است و campaign.resource_name به‌عنوان بخشی از عبارت SELECT درخواست شده است.

قوانین زبان اضافی

علاوه‌بر مثال‌های مربوط به هر عبارت، «زبان پُرسمان Google Ads» از رفتارهای زیر نیز پشتیبانی می‌کند:

  • فیلد منبع اصلی در بند SELECT برای پُرسمان الزامی نیست. برای مثال، می‌توانید از یک یا چند فیلد منبع اصلی برای فیلتر کردن داده‌ها بدون انتخاب آن‌ها استفاده کنید:

    SELECT campaign.id
FROM ad_group
WHERE ad_group.status = 'PAUSED'

  • سنجه‌ها را می‌توان منحصراً برای منبعی مشخص انتخاب کرد؛ هیچ فیلد دیگری از منبع در پُرسمان لازم نیست:

    SELECT
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros
FROM campaign

  • فیلدهای بخش‌بندی را می‌توان بدون هیچ‌گونه فیلد منبع همراه یا سنجه‌ای انتخاب کرد:

    SELECT segments.device FROM campaign

  • از فیلد resource_name (برای مثال campaign.resource_name) می‌توان برای فیلتر کردن یا مرتب کردن داده‌ها استفاده کرد:

    SELECT
  campaign.id,
  campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'
قبلی
دستور زبان پُرسمان
بعدی
محدوده تاریخ