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

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

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

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

العبارات

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