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

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

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

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

بندها

ویدیو: سازگاری فیلد 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 مشخص شود.

در حالی که تنها 1 منبع می تواند در عبارت 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 می تواند برای محدود کردن تعداد کل نتایج برای پرس و جو زیر استفاده شود:

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 .

نمونه های omit_unselected_resource_names
SELECT
  campaign.name,
  customer.id
FROM campaign
Returned resources:
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
Returned resources:
هیچ یک.
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
Returned resource:
campaign.resource_name
omit_unselected_resource_names به‌عنوان true مشخص می‌شود و campaign.resource_name به عنوان بخشی از عبارت SELECT درخواست می‌شود.

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

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

  • لازم نیست که فیلد منبع اصلی در عبارت SELECT برای یک پرس و جو باشد. به عنوان مثال، ممکن است بخواهید فقط از یک یا چند فیلد منبع اصلی برای فیلتر کردن داده ها استفاده کنید:

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

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

    SELECT
  metrics.impressions,
  metrics.clicks,
  metrics.costMicros
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'
قبلی
پرس و جو گرامر
بعدی
محدوده تاریخ