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

يتألف طلب البحث من عدد من العبارات: 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:

  • الحقول غير القابلة للاختيار، أي الحقول التي تم وضع علامة false على السمة Selectable للبيانات الوصفية فيها

  • الحقول المتكرّرة، أي الحقول التي تتضمّن سمة البيانات الوصفية 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. القيمة التلقائية هي استخدام عملة الحساب المحدّد بواسطة customer_id. في حال ضبط هذه المَعلمة، عليك استخدام رمز العملة المكوّن من 3 أحرف وفقًا لمعيار ISO 4217. على سبيل المثال: USD, EUR.

يعرض طلب البحث هذا مقياس cost_micros بعملة الحساب المحدّد بواسطة customer_id.

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

يعرض طلب البحث هذا مقياس cost_micros بالبيزو التشيلي (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"

تفعيل ميزة "توسيع نطاق الجمهور المشابه"

تتيح لك المَعلمة enable_mcc_expansion، عند ضبطها على "صحيح"، تضمين المقاييس والحقول والأقسام من جميع الحسابات الجذرية في customer_id، وذلك للمورد في عبارة FROM. سيتم استخدام عملة customer_id في الردّ، ما لم يتم تحديدها بشكل صريح في المَعلمة metrics_currency.

يعرض طلب البحث النموذجي هذا bidding_strategy.name وbidding_strategy.type وmetrics.cost_micros من جميع الحسابات في التسلسل الهرمي للحسابات الذي يبدأ من customer_id، لأنّ المَعلمة enable_mcc_expansion مضبوطة على true.

SELECT
  bidding_strategy.name,
  bidding_strategy.type,
  metrics.cost_micros
FROM bidding_strategy
WHERE segments.date DURING LAST_14_DAYS
PARAMETERS enable_mcc_expansion = true

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