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

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

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

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

العبارات

توضّح الأقسام التالية الغرض من كل عبارة في "لغة طلبات البحث في إعلانات 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

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" السلوكيات التالية التي يمكن الاستفادة منها:

• ليس من الضروري أن يكون حقل المورد الرئيسي في عبارة 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'