صِفْرْ

يشرح هذا الدليل سبب ظهور الصفوف التي تحتوي على مقاييس صفرية في تقارير Google Ads API وكيفية استبعادها أو التعامل معها في طلبات البحث.

المقاييس الصفرية في نتائج البحث

عند تنفيذ طلب بحث، قد تظهر لك مقاييس للعناصر التي تساوي صفرًا. قد يرجع السبب إلى ما يلي:

• الكيانات غير مؤهَّلة للعرض.
• تم إيقافها مؤقتًا ضمن النطاق الزمني للتقرير.

باستخدام نتائج طلبات البحث، يمكنك غالبًا الحصول على معلومات عن مستوى أداء حملاتك. في هذا السياق، قد لا تكون المقاييس الصفرية مرغوبة. لإنشاء تقرير أكثر فائدة، يمكنك استبعاد المقاييس الصفرية بشكل صريح.

استبعاد المقاييس التي تساوي صفرًا باستخدام دالة منطقية

الخبر هو تعبير يتم تقييمه على أنّه TRUE أو FALSE أو UNKNOWN. تُستخدَم المسندات في شرط البحث لبنود WHERE في لغة طلب البحث في "إعلانات Google".

يوضّح طلب البحث التالي كيفية إزالة المقاييس الصفرية بشكل صريح باستخدام دالة منطقية:

SELECT
  campaign.id,
  metrics.impressions
FROM campaign
WHERE metrics.impressions > 0

استبعاد المقاييس التي تساوي صفرًا من خلال التقسيم

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

يتم تقسيم التقرير من خلال تضمين أي حقل segments في عبارة SELECT لطلب البحث (لا تؤدي الفلترة حسب شريحة تاريخ أساسية في WHERE بدون اختيارها في SELECT إلى تقسيم التقرير). على سبيل المثال، إذا قسّمت تقريرًا حسب segments.date، يتم تقسيم المقاييس مع صف واحد لكل تاريخ. ولا يتم عرض التواريخ التي لا تتضمّن مقاييس في هذا التقرير.

بالنسبة إلى طلب البحث التالي، لن يتضمّن التقرير صفوفًا بمقاييس صفرية:

SELECT
  campaign.name,
  metrics.impressions,
  segments.date
FROM campaign
WHERE segments.date DURING LAST_30_DAYS

ينطبق هذا الاستبعاد أيضًا عند اختيار حقول segments (مثل حقول segments.ad_network_type أو segments.device) بدون اختيار أي حقول metrics. إذا لم يحقّق كيان معيّن أي مرّات ظهور، يتجاهل طلب البحث المقسّم هذا الكيان حتى عند اختيار سمات الموارد فقط، مثل حقل campaign.network_settings.target_search_network. لاسترداد إعدادات الموارد لجميع الكيانات بغض النظر عن عدد مرات الظهور، يجب حذف حقول segments من عبارة SELECT.

الصفوف التي تم عرضها بمقاييس صفرية

لن يتم عرض الصفوف التي تكون جميع مقاييسها المحدّدة صفرًا عند التقسيم. على سبيل المثال، لنفترض أنّ طلب البحث التالي يختار metrics.impressions وmetrics.clicks وmetrics.conversions:

SELECT
  ad_group_criterion.criterion_id,
  metrics.impressions,
  metrics.clicks,
  metrics.conversions,
  segments.date
FROM keyword_view
WHERE segments.date BETWEEN '2026-01-01' AND '2026-01-31'

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

عند طلب بيانات سابقة تتجاوز فترة الاحتفاظ بالبيانات، لن تتوفّر البيانات الدقيقة التي مرّ عليها أكثر من 37 شهرًا ولن يتم عرض أي صفوف. طلبات شرائح التاريخ الدقيقة (segments.date وsegments.week وsegments.hour) التي تغطي نطاقات أقدم من 37 شهرًا تُرجع DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED في الإصدار 24 والإصدارات الأحدث (أو DateRangeError.UNKNOWN في الإصدار 23). يتم الاحتفاظ بالبيانات المجمّعة العامة (segments.month وsegments.quarter وsegments.year) لمدة 11 عامًا، بما يتوافق مع بداية الفترة التقويمية الكاملة التالية. على سبيل المثال، إذا كان تاريخ انتهاء فترة المراجعة التي تبلغ 11 عامًا يقع في 2015-03-22 (أو 2015-03-01)، ستتوفّر البيانات الشهرية بدءًا من أول شهر تقويمي كامل بعد تاريخ الانتهاء (2015-04-01). يُرجى الاطّلاع على النطاقات الزمنية لمزيد من التفاصيل.

إخفاء مقاييس مدى الوصول والقيم الصفرية

بالإضافة إلى الكيانات التي لم تسجّل مرّات ظهور بعد إرسال الإعلان، يمكن أن تظهر مقاييس مدى الوصول (مثل metrics.unique_users ومقاييس مجموعة معدّل التكرار من metrics.unique_users_two_plus إلى metrics.unique_users_ten_plus) كصفر أو يتم حذفها عند حجب بيانات مدى الوصول. يتوفّر مقياس metrics.unique_users (وmetrics.unique_users_info) في "الحملات على الشبكة الإعلانية" و"حملات الفيديو" و"حملات زيادة الطلب" و"حملات التطبيقات"، في حين تنطبق مقاييس مجموعة معدّل تكرار العرض metrics.unique_users_*_plus (وmetrics.unique_users_*_plus_info) على "حملات الفيديو".

يحدث ذلك لعدة أسباب:

• حدود الخصوصية: يتم حجب بيانات مدى الوصول عندما لا يستوفي عدد المستخدمين حدود الخصوصية (مثل k-anonymity) لحماية هوية المستخدم.
• الحدود الدنيا للجودة: قد يتم حجب بيانات مدى الوصول إذا لم تستوفِ معايير الجودة.
• الاحتفاظ بالبيانات: يتم الاحتفاظ ببيانات مدى الوصول السابقة لمدة 3 سنوات (36 شهرًا). لا يمكن لطلبات البحث التي تشمل تواريخ تتجاوز فترة الاحتفاظ بالبيانات هذه التي تبلغ 3 سنوات أن تعرض مقاييس مدى الوصول. على الرغم من أنّ طلبات البحث التي تغطي تواريخ تتراوح بين 36 و37 شهرًا مضت تنجح بدون عرض DateRangeError.REQUESTED_DATE_GRANULARITY_NOT_SUPPORTED الموضّحة في القسم السابق، فإنّها تحذف مقاييس مدى الوصول (وتعرض DATE_RANGE_BEYOND_RETENTION عند اختيار البيانات الوصفية المصاحبة لمدى الوصول).

في الإصدار 26 والإصدارات الأحدث، يتضمّن كل مقياس لمدى وصول المستخدمين الفريدين حقل بيانات وصفية مصاحبًا من النوع ReachMetricInfo (مثل metrics.unique_users_info وmetrics.unique_users_two_plus_info إلى metrics.unique_users_ten_plus_info).

في لغة طلب البحث في "إعلانات Google"‏ (GAQL)، تكون حقول مدى الوصول المصاحب عبارة عن مقاييس MESSAGE يتم اختيارها مباشرةً في عبارة SELECT (على سبيل المثال، metrics.unique_users_info). لا تُلحِق .reach_metric_states في عبارة SELECT، لأنّ اختيار حقول الرسائل المُدمَجة في GAQL يتعذّر باستخدام UNRECOGNIZED_FIELD. بدلاً من ذلك، يؤدي اختيار metrics.unique_users_info إلى عرض رسالة ReachMetricInfo تحتوي على حقل التعداد المتكرر reach_metric_states من النوع ReachMetricState، والذي يوضّح ما إذا تم منع المقياس أو ما إذا كان مكتملاً.

عندما يتم حجب مقياس مدى الوصول أو عندما يكون خارج فترة الاحتفاظ بالبيانات (PRIVACY_SUPPRESSION أو QUALITY_SUPPRESSION أو DATE_RANGE_BEYOND_RETENTION)، لا يتم ضبط حقل optional int64 في Metrics (يتم تقييمه على أنّه 0 إذا لم يتم التحقّق من توفّر الحقل)، في حين يستمر LOW_QUALITY في تعبئة المقياس الرقمي:

• ‫COMPLETE: مقياس مدى الوصول مكتمل بدون أي حجب.
• PRIVACY_SUPPRESSION: تم حجب بيانات مدى الوصول بسبب قيود الخصوصية.
• QUALITY_SUPPRESSION: تم حجب بيانات مدى الوصول لأسباب تتعلق بجودة البيانات.
• ‫LOW_QUALITY: تم احتساب مقياس مدى الوصول، ولكن تم تصنيفه على أنّه منخفض الجودة.
• DATE_RANGE_BEYOND_RETENTION: لا تتوفّر مقاييس مدى الوصول لأنّ النطاق الزمني يقع خارج حدّ الاحتفاظ ببيانات مدى الوصول الذي يبلغ 3 سنوات.

من خلال اختيار كلّ من مقياس مدى الوصول وحقل البيانات الوصفية المصاحب له، يمكن لتطبيقك التمييز بين قيم مدى الوصول التي تساوي صفرًا فعليًا وقيم مدى الوصول التي تم حجبها:

SELECT
  campaign.id,
  campaign.name,
  metrics.unique_users,
  metrics.unique_users_info,
  metrics.unique_users_two_plus,
  metrics.unique_users_two_plus_info,
  metrics.unique_users_ten_plus,
  metrics.unique_users_ten_plus_info
FROM campaign
WHERE campaign.advertising_channel_type = 'VIDEO'
  AND segments.date DURING LAST_30_DAYS