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

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

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

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

العبارات

فيديو: توافق حقل GAQL

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

قد لا يُسمح ببعض الحقول في البند SELECT بسبب القيود التالية:

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

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

مِن

تحدد العبارة FROM المورد الرئيسي الذي سيتم عرضه. يحدّد المورد في عبارة FROM الحقول التي يمكن استخدامها مع جميع العبارات الأخرى لطلب البحث المعنيّ. يمكن تحديد مورد واحد فقط في الفقرة FROM. إنّ عبارة FROM مطلوبة في طلب البحث إلى طريقة GoogleAdsService البحث أو SearchStream، ولكن يجب عدم تحديدها عند استخدام طريقة 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. عبارة 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

جميع الشرائح التي تستوفي الشرط أعلاه هي: segment.date، وsegment.week، وsegments.month، وsegment.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 لتقييد العدد الإجمالي للنتائج لطلب البحث التالي:

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.

أمثلة على omit_unselected_resource_names
SELECT
  campaign.name,
  customer.id
FROM campaign
Returned resources:
campaign.resource_name
customer.resource_name
يتم ضبط omit_unselected_resource_names تلقائيًا على false، لذلك يتم عرض جميع حقول provider_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.

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

بالإضافة إلى الأمثلة الخاصة بكل عبارة، تتسم لغة طلب البحث في "إعلانات Google" بالسلوكيات التالية التي يمكن استخدامها:

  • ليس من الضروري إدراج حقل المورد الرئيسي في عبارة SELECT لطلب البحث. على سبيل المثال، قد ترغب في استخدام حقل واحد أو أكثر من حقول الموارد الرئيسية لتصفية البيانات:

    SELECT campaign.id
FROM ad_group
WHERE ad_group.status = PAUSED

  • يمكن اختيار المقاييس حصريًا لمورد معيَّن، ولا يلزم ملء حقول أخرى من المورد في طلب البحث:

    SELECT
  metrics.impressions,
  metrics.clicks,
  metrics.costMicros
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'
السابق
قواعد طلب البحث
التالي
النطاقات الزمنية