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

يمكن إرسال طلبات البحث عن حقول الموارد والشرائح والمقاييس إلى الـ GoogleAdsService Search أو SearchStream method. لإنشاء طلب بحث بلغة طلبات البحث في "إعلانات 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
  • طلب البحث عن حقول غير قابلة للاختيار تكون سمة البيانات الوصفية selectable لهذه الحقول مضبوطة على false.
  • اختيار سمات الحقول المتكرّرة تكون سمة البيانات الوصفية is_repeated لهذه الحقول مضبوطة على true.
  • اختيار الحقول غير المتاحة للمورد المحدّد في عبارة 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 الشروط التي يجب تطبيقها عند فلترة البيانات للطلب. عند استخدام عبارة 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

تتيح لك عبارة 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.

قواعد لغوية إضافية

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