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

يتكوّن طلب البحث من عدد من الجمل: 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.

الموارد التي تمّ تحديد مصدرها

إذا كانت الموارد المنسوبة متاحة، يتمّ ربطها بشكلٍ ضمني بالموارد التي تحدّدها في جملة 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

ملاحظة: إذا كان المورد في عبارة FROM يُدرج موردًا آخر باعتباره segment، يؤدي اختيار أي سمات لهذا المورد إلى العمل كشريحة.

عبارة 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

ملاحظة: لا يمكن استخدام الفاصل AND إلا بين شروط عامل التشغيل (WHERE segments.device != "DESKTOP" AND segments.device != "MOBILE")، وليس ضمن شرط عامل تشغيل واحد (WHERE segments.device != "DESKTOP" AND "MOBILE").

اطّلِع على التصنيف إلى شرائح لمزيد من المعلومات عن تقسيم تقاريرك إلى شرائح.

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

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

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

الحساسية التلقائية لحالة الأحرف
=/!=	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. على سبيل المثال: دولار أمريكي ويورو.

يعرض مثال الاستعلام هذا مقياس 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"

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

• قواعد طلب البحث