صِفْرْ

يشرح هذا الدليل سبب ظهور الصفوف التي تحتوي على مقاييس صفرية في تقارير 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

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

لن يتم عرض الصفوف التي تكون مقاييسها المحدّدة كلها صفرًا عند التقسيم. على سبيل المثال، لنفترض أنّ طلب البحث التالي يختار 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 سنوات.

By selecting both the reach metric and its companion metadata field, your application can distinguish between genuine zero reach and reach values that were suppressed:

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

ملاحظة: حقول البيانات الوصفية لمدى الوصول المصاحب (metrics.unique_users*_info) هي مقاييس MESSAGE مع filterable: false وsortable: false، لذا لا يمكن استخدامها في عبارات WHERE أو ORDER BY. بالإضافة إلى ذلك، لا يمكن تجميع مقاييس مدى الوصول على مستوى الصفوف. يمكن طلب مقياس metrics.unique_users فقط للنطاقات الزمنية التي تبلغ 92 يومًا أو أقل، في حين يمكن طلب مقاييس مجموعة معدّل التكرار unique_users_*_plus فقط للنطاقات الزمنية التي تبلغ 31 يومًا أو أقل. يمكنك الاطّلاع على تقارير مدى الوصول وعدد مرات الظهور للحملات للحصول على القائمة الكاملة لمقاييس مدى الوصول وعدد مرات الظهور في "حملات الفيديو".