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

يتكون طلب البحث من عدد من العبارات: 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. على سبيل المثال: USD أو EUR.

يعرض هذا المثال مقياس "cost_micros" بالعملة المحلية الحساب.

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"

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