ساختار پرس و جو

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

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

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

بندها

ondemand_video ویدیو: سازگاری فیلد GAQL

انتخاب کنید

عبارت 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

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

• پرس و جو فیلدهایی که قابل انتخاب نیستند. این فیلدها دارای ویژگی فوق داده Selectable آنها به عنوان false علامت گذاری می شوند.
• انتخاب ویژگی های فیلدهای تکراری این فیلدها دارای ویژگی metadata isRepeated آنها به عنوان true علامت گذاری شده است.
• انتخاب فیلدهایی که برای منبع داده شده در عبارت FROM در دسترس نیستند. ویژگی‌های برخی منابع را نمی‌توان با هم انتخاب کرد، همچنین تنها زیرمجموعه‌ای از تمام معیارها و بخش‌ها برای منبع در عبارت FROM در دسترس خواهد بود.
• انتخاب بخش ها یا معیارهایی که با یکدیگر سازگار نیستند. برای اطلاعات بیشتر در این مورد، بخش تقسیم بندی را ببینید.

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

از

عبارت FROM منبع اصلی را مشخص می کند که برگردانده می شود. منبع موجود در عبارت FROM مشخص می کند که چه فیلدهایی را می توان از همه بندهای دیگر برای پرس و جو داده شده استفاده کرد. فقط یک منبع را می توان در عبارت FROM مشخص کرد. عبارت FROM در پرس و جو به روش های جستجوی GoogleAdsService یا 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 ، یک یا چند شرط را می توان با استفاده از AND برای جدا کردن آنها مشخص کرد. هر شرط باید از الگوی field_name Operator value پیروی کند. عبارت WHERE در یک پرس و جو اختیاری است.

در زیر نمونه ای از استفاده از WHERE برای برگرداندن معیارها از یک دوره زمانی مشخص است:

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

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

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 استفاده شود.

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

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

سفارش توسط

بند 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 به شما امکان می دهد تعداد نتایجی که باید برگردانده شوند را مشخص کنید. اگر فقط به یک خلاصه علاقه دارید این کار مفید است.

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

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

پارامترها

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

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

شامل_پیش نویس ها

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

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

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

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

علاوه بر مثال‌هایی برای هر بند، Google Ads Query Language رفتارهای زیر را دارد که می‌توان از آنها استفاده کرد:

• لازم نیست که فیلد منبع اصلی در عبارت 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'