تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

بنية طلب البحث

يمكن إرسال طلبات البحث عن حقول الموارد والشرائح والمقاييس إلى طريقة GoogleAdsService Search أو SearchStream. لإنشاء طلب بحث في لغة طلب البحث في "إعلانات Google"، يمكنك إنشاؤه باستخدام قواعد اللغة. للحصول على نظرة عامة على لغة طلب البحث في "إعلانات Google"، يمكنك الاطّلاع على نظرة عامة على لغة طلب البحث في "إعلانات Google". يتكون الاستعلام من عدد من البنود:

SELECT
FROM
WHERE
ORDER BY
LIMIT
PARAMETERS

تستخدم البنود أسماء الحقول وأسماء الموارد وعوامل التشغيل والشروط والترتيبات لمساعدتك في اختيار البيانات الصحيحة. عند دمجها في طلب بحث واحد، يمكنك إرسال الطلب إلى Google Ads API.

نقطة أساسية: يوفّر GoogleAdsFieldService كتالوجًا لعملاء لغة طلب البحث في "إعلانات Google" يتضمّن بيانات وصفية عن جميع حقول الموارد وحقول الشرائح والمقاييس وعلاقاتها ببعضها ومدى توفّرها في كل عبارة. بما أنّ مجموعة الموارد والحقول والشرائح والمقاييس القابلة للاستعلام تختلف باختلاف الإصدارات الرئيسية من واجهة برمجة التطبيقات، يمكنك الاستعلام عن GoogleAdsFieldService في نقطة النهاية لإصدار واجهة برمجة التطبيقات الذي تستهدفه. لمزيد من التفاصيل، يُرجى الرجوع إلى مستندات GoogleAdsField والاختلافات الخاصة بالإصدار.

البنود

توضّح الأقسام التالية الغرض من كل عبارة في لغة طلب البحث في "إعلانات Google" وبنيتها.

SELECT

تحدّد عبارة 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

يتم الاستعلام عن حقول غير قابلة للاختيار. تم وضع علامة false على سمة البيانات الوصفية selectable لهذه الحقول.
اختيار سمات الحقول المتكرّرة تم وضع علامة true على سمة البيانات الوصفية is_repeated لهذه الحقول.
اختيار حقول غير متاحة للمورد المحدّد في عبارة FROM لا يمكن اختيار سمات بعض الموارد معًا، ولا تتوفّر سوى مجموعة فرعية من جميع المقاييس والشرائح للمورد في عبارة FROM.
اختيار شرائح أو مقاييس غير متوافقة مع بعضها لمزيد من المعلومات، يُرجى الاطّلاع على التقسيم.

يمكن العثور على المعلومات المتعلقة بالشروط السابقة في مستنداتنا المرجعية أو من خلال GoogleAdsFieldService.

FROM

تحدّد عبارة FROM المورد الرئيسي المطلوب عرضه. يحدّد المورد في عبارة FROM الحقول التي يمكن استخدامها في جميع العبارات الأخرى لطلب البحث المحدّد. يمكن تحديد مورد واحد فقط في عبارة FROM. إنّ عبارة FROM مطلوبة في طلب البحث إلى الإجراء GoogleAdsService Search أو SearchStream. ومع ذلك، يجب عدم تحديد عبارة FROM عند استخدام GoogleAdsFieldService.

على الرغم من أنّه يمكن أن يتوفّر مورد واحد فقط في عبارة 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 (أو تستخدم 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

يمكنك الجمع بين شروط متعددة لفلترة البيانات. يطلب هذا المثال عدد النقرات لجميع الحملات التي سجّلت مرات ظهور على الأجهزة الجوّالة في آخر 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

تحدّد عبارة 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

اضبط 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" السلوكيات التالية:

حقل المورد الرئيسي غير مطلوب في عبارة 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'
```

قواعد طلب البحث

النطاقات الزمنية