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