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

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

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

بندها از نام فیلدها ، نام منابع ، عملگرها ، شرط‌ها و ترتیب‌ها برای کمک به شما در انتخاب داده‌های صحیح استفاده می‌کنند. وقتی این بندها در یک پرس‌وجوی واحد ترکیب شوند، می‌توان با استفاده از 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
  • پرس‌وجوی فیلدهایی که قابل انتخاب نیستند. این فیلدها دارای ویژگی فراداده Selectable خود هستند که با false علامت‌گذاری شده است.
  • انتخاب ویژگی‌های فیلدهای تکراری. این فیلدها ویژگی فراداده‌ی isRepeated خود را با مقدار true علامت‌گذاری می‌کنند.
  • انتخاب فیلدهایی که برای منبع داده شده در بند FROM در دسترس نیستند. ویژگی‌های برخی از منابع را نمی‌توان با هم انتخاب کرد، همچنین فقط زیرمجموعه‌ای از تمام معیارها و بخش‌ها برای منبع در بند FROM در دسترس خواهد بود.
  • انتخاب بخش‌ها یا معیارهایی که با یکدیگر سازگار نیستند. برای اطلاعات بیشتر در این مورد، به بخش تقسیم‌بندی مراجعه کنید.

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

از

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

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

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

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

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

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

سفارش بر اساس

دستور 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

حذف نام‌های منابع انتخاب نشده

برای جلوگیری از بازگشت نام منبع هر نوع منبع در پاسخ، مگر اینکه صریحاً در بند SELECT درخواست شده باشد، omit_unselected_resource_names روی true تنظیم کنید. مقدار پیش‌فرض 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 درخواست شده است.

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

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

  • لازم نیست فیلد منبع اصلی در عبارت 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'
قبلی
پرس و جو گرامر
بعدی
محدوده تاریخ