‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

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

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

SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS

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

بندها

بخش‌های زیر هدف و نحو هر عبارت Google Ads Query Language را شرح می‌دهند.

انتخاب

بند 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` درخواست شده است.

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'
```