بنية طلب البحث وبنوده

يتكون طلب البحث من عدد من العبارات: SELECT وFROM وWHERE وORDER BY وLIMIT وPARAMETERS.

تستخدم البنود أسماء الحقول وأسماء الموارد وعوامل التشغيل والشروط والترتيبات التي يتم دمجها في طلب بحث واحد.

بعبارات أساسية، لإنشاء استعلام، عليك:

  • تحديد مورد لاسترداد البيانات منه.
  • أضِف الحقول والمقاييس لتحديد البيانات التي تريد عرضها.
  • أضِف شرائح لتجميع نتائجك.
  • أضِف موارد محدّدة المصدر لدمج بيانات الموارد ذات الصلة ضمنيًا.
  • يمكنك فلترة النتائج وترتيبها والحد منها.

عبارة SELECT

عبارة SELECT:

  • عبارة مطلوبة في طلب البحث
  • تحدّد هذه السمة مجموعة من الحقول المطلوب استرجاعها في الطلب.
  • تستخدم قائمة مفصولة بفواصل لحقول الموارد والأعمدة المخصّصة ومتغيّرات Floodlight المخصّصة وحقول الشرائح والمقاييس، ثم تعرض القيم في الاستجابة.

يوضح لك نموذج طلب البحث هذا كيفية اختيار سمات مورد campaign:

SELECT
  campaign.id,
  campaign.name
FROM campaign

أنواع حقول متعددة

يمكنك طلب أنواع حقول مختلفة في الطلب نفسه.

يعرض مثال طلب البحث أدناه طلب بحث واحدًا يحتوي على مجموعة من:

  • حقول الموارد: campaign.id وcampaign.name وbidding_strategy.id وbidding_strategy.name.
  • حقلا الشرائح: segments.device وsegments.date
  • حقلا المقاييس: metrics.impressions وmetrics.clicks
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

راجع التصنيف لمعرفة المزيد عن تقسيم تقارير البحث.

حقل الموارد الرئيسي

يمكنك عادةً تضمين حقل المورد الرئيسي في عبارة SELECT ولكن هذا اختياري (غير مطلوب).

يستخدم نموذج طلب البحث هذا حقلاً رئيسيًا للموارد (ad_group.status) لفلترة النتائج فقط.

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

متغيّرات Floodlight المخصّصة

يمكنك تضمين متغيّرات Floodlight المخصّصة في عبارة SELECT باستخدام أرقام تعريفها.

في هذا المثال، يتضمّن طلب البحث متغيرًا مخصّصًا برقم التعريف 123454321 لمورد الحملة.

SELECT
  conversion_custom_metrics.id[123454321]
FROM campaign

SELECT
  conversion_custom_dimensions.id[123454321]
FROM campaign

أعمدة مخصصة

يمكنك تضمين أعمدة مخصّصة في عبارة SELECT باستخدام أرقام تعريفها.

في هذا المثال، يتضمّن طلب البحث عمودًا مخصّصًا برقم التعريف 12345678 لمورد الحملة.

SELECT
  custom_columns.id[12345678]
FROM campaign

اطّلِع على كيفية الحصول على أرقام تعريف الأعمدة المخصّصة.

حقول المقاييس

يمكنك اختيار حقول المقاييس لمورد معيّن بدون تضمين أي حقول أخرى من المورد المدرَج في العبارة SELECT.

يختار نموذج طلب البحث هذا المقياسَين impressions وclicks لمورد campaign.

SELECT
  metrics.impressions,
  metrics.clicks
FROM campaign

انتقِل إلى metrics للاطّلاع على قائمة بحقول المقاييس التي يمكنك استخدامها في طلبات البحث.

حقول الشرائح

يمكنك اختيار حقول الشرائح بدون تحديد حقول أو مقاييس الموارد المصاحبة في عبارة SELECT.

في هذا المثال، يتم تقسيم النتائج حسب الجهاز.

SELECT segments.device
FROM campaign

راجِع segments للاطّلاع على قائمة بحقول الشرائح التي يمكنك استخدامها في طلبات البحث.

الحقول المحظورة

لا يمكنك استخدام الحقول التالية في عبارة SELECT:

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

راجع المستندات المرجعية للحصول على تفاصيل حول مكان العثور على هذه المعلومات لكل مورد.

عبارة FROM

عبارة FROM:

  • هي عبارة مطلوبة في طلبات البحث إلى SearchAds360Service (في كلّ من الطريقتَين Search وSearchStream).
  • يجب عدم تضمين هذه السمة في طلبات البحث التي تؤدي إلى SearchAds360FieldService.
  • تحدد هذه السمة المورد الرئيسي الذي يعرضه طلب البحث.
  • يمكن تحديد مورد واحد فقط.
  • تحدد الحقول التي يمكنك استخدامها في جميع العبارات الأخرى في الاستعلام.

الموارد المنسوبة

في حال توفّر المراجع التي تم تحديد مصدرها، يتم دمجها ضمنيًا مع المورد الذي تحدّده في البند FROM. ما عليك سوى إضافة سماتها إلى عبارة SELECT لإرجاع قيمها.

يعرض نموذج طلب البحث هذا كلاً من رقم تعريف المجموعة الإعلانية ورقم تعريف الحملة، لأنّ campaign هو مورد منسوب لمورد ad_group.

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

حقل resource_name

يتم دائمًا عرض الحقل resource_name للمورد الرئيسي في عبارة FROM.

في نموذج طلب البحث هذا، سيتم تضمين ad_group.resource_name في الرد على الرغم من أنه لم يتم تحديده بشكل صريح في الاستعلام:

SELECT ad_group.id
FROM ad_group

يتم عرض الحقل resource_name لمورد مرتبط عند اختيار حقل واحد على الأقل.

في نموذج الطلب هذا، سيتم تضمين campaign.resource_name في الرد لأنه تم تحديد campaign.id:

SELECT
  campaign.id,
  ad_group.id
FROM ad_group

عبارة WHERE

عبارة WHERE:

  • عبارة عن عبارة اختيارية في طلب البحث.
  • تحدِّد شروط فلترة البيانات وتقسيمها للطلب. تتّبع الشروط النمط التالي: FIELD_NAME OPERATOR VALUE (مفصولة بمسافات فارغة).
  • يمكن أن يتضمّن شروطًا متعددة مفصولة بفاصل AND.

يوضح مثال طلب البحث هذا كيفية استخدام عبارة WHERE لعرض مقاييس impressions لفترة زمنية معيّنة:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

راجع التصنيف لمعرفة المزيد عن تقسيم تقارير البحث.

راجِع النطاقات الزمنية للاطّلاع على مزيد من المعلومات حول تحديد النطاقات الزمنية في طلبات البحث.

الفلترة حسب الحقل "resource_name"

ويمكنك استخدام الحقل resource_name لفلترة البيانات أو ترتيبها.

يستخدم نموذج طلب البحث هذا الحقل campaign.resource_name لفلترة النتائج حسب حملة معيّنة:

SELECT
  campaign.id,
  campaign.name
FROM campaign
WHERE campaign.resource_name = 'customers/1234567/campaigns/987654'

شروط متعدّدة

يمكنك الجمع بين شروط متعددة لفلترة بياناتك.

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

راجع التصنيف لمعرفة المزيد عن تقسيم التقارير.

الحساسية لحالة الأحرف

عند الفلترة حسب قيم السلسلة، تلعب الحساسية التلقائية لحالة الأحرف لكل عامل دورًا مهمًا في فلترة النتائج بشكل صحيح.

يعرض الجدول التالي الحساسية التلقائية لحالة الأحرف لكل عامل تشغيل.

الحساسية التلقائية لحالة الأحرف
=/!= Case sensitive
IN/NOT IN Case sensitive
LIKE/NOT LIKE Case insensitive
CONTAINS (...) Case sensitive
REGEXP_MATCH/NOT REGEXP_MATCH Case sensitive

يمكنك استخدام المعدِّل (?i) لتغيير قيمة الحساسية التلقائية لـ REGEXP_MATCH وNOT REGEXP_MATCH إلى غير حساسة لحالة الأحرف، على سبيل المثال:

SELECT campaign.id
FROM campaign
WHERE campaign.name REGEXP_MATCH "(?i).*test.*"

راجِع مرجع القواعد النحوية لطلب البحث للحصول على قائمة كاملة بعوامل التشغيل التي يمكنك استخدامها لفلترة بياناتك.

شرائح التاريخ الأساسية

تُعرَف حقول الشرائح التالية باسم شرائح التاريخ الأساسي: segments.date وsegments.week وsegments.month وsegments.quarter وsegments.year.

يمكنك استخدام شرائح التاريخ الأساسية في عبارة WHERE لتحديد تاريخ أو فترة زمنية.

يحدّد نموذج طلب البحث هذا DURING LAST_30_DAYS للحقل segments.date في عبارة WHERE:

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  metrics.clicks
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

راجِع التقسيم > شرائح التاريخ الأساسي للحصول على معلومات تفصيلية عن استخدام شرائح التاريخ الأساسي.

الفلترة المحظورة

الفلترة غير مسموح بها:

  • في حقول الشرائح غير المحدّدة، باستثناء شرائح التاريخ الأساسية
  • في الحقول من أي نوع من أنواع الرسائل، باستثناء الرسائل الأساسية (على سبيل المثال، Int64Value وStringValue وما إلى ذلك).
  • في سمات الحقول المتكرّرة من أي نوع رسالة، باستثناء القيم الأساسية (على سبيل المثال، Int64Value وStringValue وما إلى ذلك)

عبارة ORDER BY

عبارة ORDER BY:

  • عبارة عن عبارة اختيارية في طلب البحث.
  • تحدِّد هذه السياسة الترتيب الذي تُعرَض النتائج به. يتّبع الترتيب النمط التالي: FIELD_NAME ORDERING_OPTION (مفصولة بمسافة فارغة).
  • يسمح بخيارَين: ASC (ترتيب تصاعدي) أو DESC (ترتيب تنازلي). الإعداد التلقائي ترتيب تصاعدي.

في هذا المثال، يتم ترتيب الحملات حسب عدد النقرات بترتيب تنازلي (من الأعلى إلى الأدنى):

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

الجمع بين الترتيب والحد

يمكنك استخدام عبارة ORDER BY مع عبارة LIMIT لتحسين النتائج.

يعرض نموذج طلب البحث هذا الحملات الخمس التي حققت أعلى مرات ظهور خلال آخر 30 يومًا:

SELECT
  campaign.id,
  campaign.name,
  metrics.impressions
FROM campaign
WHERE segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 5

الطلب المحظور

غير مسموح بالطلب:

  • حسب سمات الموارد التي لم يتم اختيارها
  • حسب المقاييس غير المحدّدة.
  • حسب الشرائح غير المحدّدة.
  • بالنسبة إلى أنواع الحقول التالية:
    • MESSAGE
    • الحقول المتكرّرة
    • سمات الحقول المتكرّرة

عبارة LIMIT

عبارة LIMIT:

  • عبارة عن عبارة اختيارية في طلب البحث.
  • يتيح لك الحد من عدد النتائج التي يعرضها الاستعلام.

هذه العبارة مفيدة، على سبيل المثال، إذا كنت مهتمًا فقط بعيّنة أو ملخص للنتائج.

يحد مثال طلب البحث هذا من إجمالي عدد النتائج إلى 50:

SELECT
  campaign.name,
  ad_group.name,
  segments.device,
  metrics.impressions
FROM ad_group
ORDER BY metrics.impressions DESC
LIMIT 50

عبارة PARAMETERS

تتيح لك العبارة PARAMETERS تحديد معلَمات وصفية للطلب.

تضمين المسودات

تتحكّم المعلَمة include_drafts في ما إذا كان سيتم تضمين مسودة الكيانات في النتائج. والقيمة التلقائية هي false. ويجب ضبطها على true لتضمين مسودة الكيانات.

يعرض نموذج طلب البحث هذا كلاً من الحملات الاختبارية والحملات العادية:

SELECT campaign.name
FROM campaign
PARAMETERS include_drafts=true

حذف resource_name التي تم اختيارها

تتيح لك المعلَمة omit_unselected_resource_names إمكانية استبعاد الحقل resource_name من جميع الموارد التي لم يتم طلبها صراحةً في عبارة SELECT. والقيمة التلقائية هي false. في حال ضبط هذه المعلمة على true، ننصحك بطلب اسم المورد الأساسي بشكل صريح وأي موارد منسوبة إلى موقعك في عبارة SELECT.

لا يعرض نموذج طلب البحث هذا الحقل campaign.resource_name أو الحقل customer.resource_name لأنّهما غير مضمّنَين في العبارة SELECT:

SELECT
  campaign.name,
  customer.id
FROM campaign
PARAMETERS omit_unselected_resource_names = true

يعرض نموذج طلب البحث هذا الحقل campaign.resource_name، لأنّه تم طلبه صراحةً في عبارة SELECT:

SELECT
  campaign.name,
  campaign.resource_name
FROM campaign
PARAMETERS omit_unselected_resource_names = true

تغيير العملة المستخدَمة في المقاييس

تتيح لك المعلمة metrics_currency تحديد العملة التي سيتم استخدامها عند احتساب مقياس مضمّن في عبارة SELECT. يكون الوضع التلقائي هو استخدام العملة المحلية للحساب. في حال ضبط هذه المَعلمة، عليك استخدام رمز العملة المكوَّن من 3 أحرف ISO 4217. على سبيل المثال: SAR أو EUR.

يعرض نموذج طلب البحث هذا مقياس Cost_micros بالعملة المحلية للحساب.

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"

يعرض نموذج طلب البحث هذا مقياس التكلفة_الإجمالية بالبيزو التشيلي (CLP).

SELECT
  campaign.name,
  metrics.cost_micros
FROM campaign
WHERE segments.date >= "2018-08-15"
AND segments.date < "2018-08-16"
PARAMETERS metrics_currency = "CLP"

مزيد من المعلومات