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

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

اطّلِع على التصنيف > شرائح البيانات الأساسية للحصول على معلومات detailed عن استخدام شرائح البيانات الأساسية.

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

لا يُسمح بالفلترة في الحالات التالية:

• في حقول الشرائح غير المحدّدة، باستثناء شرائح التواريخ الأساسية.
• في حقول أي نوع من الرسائل، باستثناء العناصر الأساسية (مثل 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"

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

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