يمكنك استخدام Reporting API من أجل رصد انتهاكات الأمان وطلبات البيانات من واجهة برمجة التطبيقات المتوقّفة والمزيد.
تحدث بعض الأخطاء في مرحلة الإنتاج فقط. لن تظهر لك محليًا أو أثناء والتطوير لأن المستخدمين الحقيقيين والشبكات الفعلية والأجهزة الحقيقية ستغير اللعبة. تساعد Reporting API في رصد بعض هذه الأخطاء، مثل مثل انتهاكات الأمان أو واجهة برمجة التطبيقات التي سيتم إيقافها نهائيًا أو سيتم إيقافها قريبًا عبر موقعك، وينقلها إلى نقطة نهاية المحددة.
يُتيح لك الإعلان عن ما تريد مراقبته عبر عناوين HTTP، يتم التشغيل بواسطة المتصفِّح.
من خلال إعداد Reporting API، يمكنك ضمان راحة البال عندما يجرّب المستخدمون تجربة هذه الأنواع من الأخطاء، ستعرف ذلك، حتى تتمكن من إصلاحها.
تتناول هذه المشاركة الإجراءات التي يمكن لواجهة برمجة التطبيقات هذه تنفيذها وكيفية استخدامها. لنطّلِع على التفاصيل.
العرض التوضيحي والرمز البرمجي
الاطّلاع على واجهة Reporting API وهي قيد التشغيل بدءًا من Chrome 96 والإصدارات الأحدث (Chrome إصدار تجريبي أو إصدار Canary، اعتبارًا من تشرين الأول (أكتوبر) 2021).
نظرة عامة
![مخطّط بياني يلخّص الخطوات التالية، بدءًا من إنشاء التقارير وصولاً إلى وصول المطوّر إلى التقارير](https://developer.chrome.com/static/docs/capabilities/web-apis/reporting-api/image/diagram-summarizing-step-7115c265c2e02.png?authuser=19&hl=ar)
لنفترض أنّ موقعك الإلكتروني، site.example
، يتّبع سياسة أمان المحتوى وسياسة مستند. ألا تعرف ماذا تفعل هذه؟ لا بأس، ستظل
قادرًا على فهم هذا المثال.
أنك قررت مراقبة موقعك من أجل معرفة متى يتم انتهاك هذه السياسات، ولكن أيضًا لأن إذا كنت تريد مراقبة واجهات برمجة التطبيقات المتوقّفة نهائيًا أو التي سيتم إيقافها قريبًا والتي قد تستخدمها قاعدة الرموز الخاصة بك.
لإجراء ذلك، عليك ضبط عنوان Reporting-Endpoints
وربط نقطة النهاية هذه.
الأسماء من خلال التوجيه report-to
في السياسات عند الحاجة.
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0; report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the `default` endpoint
حدث شيء غير متوقع، ويتم انتهاك هذه السياسات لبعض المستخدمين.
أمثلة على الانتهاكات
index.html
<script src="script.js"></script>
<!-- CSP VIOLATION: Try to load a script that's forbidden as per the Content-Security-Policy -->
<script src="https://example.com/script.js"></script>
تم تحميل script.js
من قِبل index.html
.
// DOCUMENT-POLICY VIOLATION: Attempt to use document.write despite the document policy
try {
document.write('<h1>hi</h1>');
} catch (e) {
console.log(e);
}
// DEPRECATION: Call a deprecated API
const webkitStorageInfo = window.webkitStorageInfo;
ينشئ المتصفِّح تقريرًا بانتهاك سياسة أمان المحتوى (CSP) وتقريرًا عن انتهاك سياسة المستند وعملية إيقاف نهائيًا. تقرير يتضمن هذه المشكلات.
في حال تأخير قصير، قد يصل إلى دقيقة واحدة، يرسل المتصفّح التقارير إلى نقطة نهاية تم ضبطها لنوع الانتهاك هذا. يتم إرسال التقارير خارج الإطار من قِبل المتصفّح نفسه (وليس من خلال خادمك أو موقعك الإلكتروني).
تتلقّى نقاط النهاية هذه التقارير.
يمكنك الآن الوصول إلى التقارير حول نقاط النهاية هذه وتتبُّع الأخطاء التي حدثت. أنت جاهز لبدء تحديد المشكلة التي تؤثِّر في المستخدمين وحلّها.
مثال للتقرير
{
"age": 2,
"body": {
"blockedURL": "https://site2.example/script.js",
"disposition": "enforce",
"documentURL": "https://site.example",
"effectiveDirective": "script-src-elem",
"originalPolicy": "script-src 'self'; object-src 'none'; report-to main-endpoint;",
"referrer": "https://site.example",
"sample": "",
"statusCode": 200
},
"type": "csp-violation",
"url": "https://site.example",
"user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
}
حالات الاستخدام وأنواع التقارير
يمكن ضبط Reporting API لمساعدتك في تتبُّع عدة أنواع من التحذيرات أو المشاكل المثيرة للاهتمام. التي تحدث في جميع أنحاء موقعك الإلكتروني:
نوع التقرير | مثال على موقف سيتم فيه إنشاء تقرير |
---|---|
انتهاك CSP (المستوى 3 فقط) | لقد ضبطت سياسة "Content-Security-Policy " (CSP) على إحدى صفحاتك، ولكن الصفحة تحاول تحميل نص برمجي غير مسموح به من خلال سياسة أمان المحتوى (CSP). |
مخالفة COOP | لقد ضبطت Cross-Origin-Opener-Policy على صفحة، ولكن هناك نافذة متعددة المصادر تحاول التفاعل مباشرةً مع المستند. |
انتهاك COEP | لقد ضبطت Cross-Origin-Embedder-Policy على إحدى الصفحات، ولكنّ المستند يتضمّن إطار iframe من مصادر متعددة لم يتم تفعيل تحميله من خلال المستندات من مصادر متعددة. |
انتهاك سياسة المستندات | تتضمن الصفحة سياسة مستند تمنع استخدام document.write ، إلا أنّ هناك نصًا برمجيًا يحاول استدعاء document.write . |
انتهاك سياسة الأذونات | تتضمّن الصفحة سياسة أذونات تمنع استخدام الميكروفون، ونص برمجي يطلب إدخال الصوت. |
تحذير بشأن الإيقاف النهائي | استخدام الصفحة لواجهة برمجة تطبيقات تم إيقافها نهائيًا أو سيتم إيقافها نهائيًا يقوم باستدعاءه مباشرةً أو عبر نص برمجي لجهة خارجية عالي المستوى. |
تدخل | تحاول الصفحة تنفيذ إجراء يقرر المتصفّح عدم تنفيذه لأسباب تتعلّق بالأمان أو الأداء أو تجربة المستخدِم. مثال في Chrome: تستخدم الصفحة document.write على الشبكات البطيئة أو تطلب navigator.vibrate في إطار من مصادر متعددة لم يتفاعل معها المستخدم بعد. |
حادث سير | يتعطّل المتصفّح عندما يكون موقعك الإلكتروني مفتوحًا. |
التقارير
كيف تبدو التقارير؟
يرسل المتصفّح التقارير إلى نقطة النهاية التي ضبطتها. ويُرسِل الطلبات التي تبدو على النحو التالي:
POST
Content-Type: application/reports+json
وتكون حمولة هذه الطلبات هي قائمة بالتقارير.
أمثلة على قائمة التقارير
[
{
"age": 420,
"body": {
"columnNumber": 12,
"disposition": "enforce",
"lineNumber": 11,
"message": "Document policy violation: document-write is not allowed in this document.",
"policyId": "document-write",
"sourceFile": "https://site.example/script.js"
},
"type": "document-policy-violation",
"url": "https://site.example/",
"user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
},
{
"age": 510,
"body": {
"blockedURL": "https://site.example/img.jpg",
"destination": "image",
"disposition": "enforce",
"type": "corp"
},
"type": "coep",
"url": "https://dummy.example/",
"user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
}
]
إليك البيانات التي يمكنك العثور عليها في كلٍّ من هذه التقارير:
الحقل | الوصف |
---|---|
age |
عدد المللي ثانية بين الطابع الزمني للتقرير والوقت الحالي |
body |
بيانات التقرير الفعلية، متسلسلة في سلسلة JSON. يتمّ تحديد الحقول المضمّنة في body للتقرير من خلال type في التقرير. ⚠️ البلاغات من أنواع مختلفة لها نصوص مختلفة
وللاطّلاع على النص الأساسي لكل نوع تقرير، راجِع نقطة نهاية إعداد التقارير التجريبية واتّبِع التعليمات لإنشاء أمثلة على التقارير. |
type |
نوع تقرير، على سبيل المثال csp-violation أو coep . |
url |
عنوان المستند أو العامل الذي تم إنشاء التقرير منه. تتم إزالة البيانات الحسّاسة من عنوان URL هذا، مثل اسم المستخدم وكلمة المرور والجزء. |
user_agent |
عنوان User-Agent للطلب الذي تم إنشاء التقرير منه. |
التقارير المعتمدة
يتم إرسال بيانات الاعتماد إلى نقاط نهاية إعداد التقارير التي لها المصدر نفسه للصفحة التي تنشئ التقرير. (ملفات تعريف الارتباط) في الطلبات التي تحتوي على التقارير.
قد توفّر بيانات الاعتماد سياقًا إضافيًا مفيدًا حول التقرير. حيث مثلاً، ما إذا كان حساب مستخدم معيّن يعرض الأخطاء بشكل منتظم، أو إذا كان تسلسل معيّن من الإجراءات المتخذة على صفحات أخرى تؤدي إلى ظهور تقرير في هذه الصفحة.
متى وكيف يُرسِل المتصفّح التقارير؟
تقديم التقارير خارج النطاق الزمني من موقعك الإلكتروني: يتحكّم المتصفّح في الوقت الذي يتم إرسالها إلى نقاط النهاية التي تم إعدادها. لا توجد أيضًا طريقة للتحكم في وقت إرسال المتصفِّح للتقارير تلتقطها وتضعها في قائمة الانتظار وترسلها تلقائيًا الوقت المناسب.
يعني ذلك أنّه ما مِن مشاكل ضئيلة أو لا داعي للقلق بشأن الأداء عند استخدام Reporting API.
يتم إرسال التقارير مع تأخير، لمدة تصل إلى دقيقة واحدة، لزيادة فرص إرسال التقارير على دفعات. وهذا يوفر معدل نقل البيانات بما يراعي اتصال الشبكة لدى المستخدم، ولاسيما أهمية على الهاتف المحمول. يمكن أن يؤخر المتصفّح أيضًا التسليم إذا كان مشغولاً بالمعالجة ذات أولوية أعلى. أو إذا كان المستخدم متصلاً بشبكة بطيئة و/أو مزدحمة في ذلك الوقت.
مشاكل الطرف الثالث والطرف الأول
سيتم إرسال التقارير التي يتم إنشاؤها بسبب الانتهاكات أو عمليات الإيقاف التي تحدث على صفحتك. إلى نقاط النهاية التي ضبطتها. يشمل ذلك الانتهاكات التي ترتكبها النصوص البرمجية التابعة لجهات خارجية. قيد التشغيل على صفحتك.
الانتهاكات أو عمليات الإيقاف التي حدثت في إطار iframe من مصادر متعددة مضمّنة في صفحتك عدم إبلاغ نقاط النهاية لديك (على الأقل ليس بشكل تلقائي). يمكن لإطار iframe إعداد وكذلك إعداد التقارير إلى خدمة إعداد التقارير في موقعك الإلكتروني - أي الطرف الأول - لكن الأمر كذلك إلى الموقع المؤطر. تجدر الإشارة أيضًا إلى أنّه لا يتمّ إنشاء معظم البلاغات إلا في حال انتهاك سياسة الصفحة. وأنّ سياسات صفحتك تختلف عن سياسات iframe.
مثال مع عمليات الإيقاف نهائيًا
![إذا تم إعداد عنوان "نقاط النهاية لإعداد التقارير" على صفحتك: سيتم إبلاغ نقطة النهاية عن واجهة برمجة التطبيقات المتوقّفة التي تم إيقافها من خلال نصوص برمجية تابعة لجهة خارجية تعمل على صفحتك. لن يتم إبلاغ نقطة النهاية عن واجهة برمجة التطبيقات المتوقّفة التي تم طلبها باستخدام إطار iframe مضمَّن في صفحتك. لن يتم إنشاء تقرير الإيقاف نهائيًا إلا إذا أعدّ خادم iframe نقاط نهاية إعداد التقارير، وسيتم إرسال هذا التقرير إلى أي نقطة نهاية أعدّها خادم إطار iframe.](https://developer.chrome.com/static/docs/capabilities/web-apis/reporting-api/image/if-reporting-endpoints-h-c4facaee3ba26.png?authuser=19&hl=ar)
دعم المتصفح
يلخّص الجدول التالي توافق المتصفّح للإصدار 1 من Reporting API، والذي يشمل
العنوان Reporting-Endpoints
توافق المتصفّح مع الإصدار 0 من Reporting API (عنوان Report-To
) هو
نفسه، باستثناء نوع تقرير واحد: لا تتوفّر ميزة "تسجيل أخطاء الشبكة" في Reporting API الجديدة.
يُرجى قراءة دليل نقل البيانات للاطّلاع على التفاصيل.
نوع التقرير | Chrome | متصفح Chrome لنظام التشغيل iOS | Safari | Firefox | Edge |
---|---|---|---|---|---|
انتهاك سياسة أمان المحتوى (CSP) (المستوى 3 فقط)* | ✔ نعم | ✔ نعم | ✔ نعم | ✘ لا | ✔ نعم |
تسجيل أخطاء الشبكة | ✘ لا | ✘ لا | ✘ لا | ✘ لا | ✘ لا |
انتهاك سياسة مشاركة المعلومات (COOP/COEP) | ✔ نعم | ✘ لا | ✔ نعم | ✘ لا | ✔ نعم |
جميع الأنواع الأخرى: انتهاك سياسة المستندات، وإيقافها نهائيًا، والتدخل، والتعطُّل | ✔ نعم | ✘ لا | ✘ لا | ✘ لا | ✔ نعم |
يلخّص هذا الجدول فقط الدعم لـ report-to
باستخدام عنوان Reporting-Endpoints
الجديد. اقرأ نصائح حول نقل تقارير CSP إذا كنت تريد نقل البيانات إلى Reporting-Endpoints
.
استخدام Reporting API
تحديد الوجهة التي يجب إرسال التقارير إليها
أمامك خياران:
- إرسال التقارير إلى خدمة حالية لتجميع التقارير
- يمكنك إرسال التقارير إلى جامع التقارير التي تنشئها وتديرها بنفسك.
الخيار 1: استخدام إحدى خدمات تجميع التقارير الحالية
في ما يلي بعض الأمثلة على خدمات تجميع التقارير:
إذا كانت لديك حلول أخرى، يمكنك فتح مشكلة لإعلامنا بذلك، وسنعدّل هذه المشاركة.
بالإضافة إلى الأسعار، يُرجى مراعاة النقاط التالية عند اختيار جهة تجميع التقارير: 🧐
- هل تتيح أداة التجميع هذه استخدام جميع أنواع التقارير؟ على سبيل المثال، قد لا تكون بعض حلول نقاط النهاية في التقارير إتاحة تقارير COOP/COEP.
- هل توافق على مشاركة أي من عناوين URL الخاصة بتطبيقاتك مع جهة تجميع تقارير تابعة لجهات خارجية؟ حتى إذا أزال المتصفح معلومات حساسة من عناوين URL هذه، قد يتم تسريب المعلومات الحساسة بهذه الطريقة. إذا كان هذا يبدو خطرًا جدًا على تطبيقك، تشغيل نقطة نهاية إعداد التقارير الخاصة بك.
الخيار 2: إنشاء أداة تجميع التقارير الخاصة بك وتشغيلها
فإنشاء خادمك الخاص الذي يتلقى التقارير ليس بهذه البساطة. للبدء، يمكنك إجراء نص نموذجي خفيف. تم إنشاء هذه الميزة من خلال Express ويمكنها تلقّي التقارير وعرضها.
انتقِل إلى أداة تجميع تقارير النصوص النموذجية.
انقر على إنشاء ريمكس لتعديل لجعل المشروع قابلاً للتعديل.
لديك الآن استنساخك! ويمكنك تخصيصه لأغراضك الخاصة.
إذا كنت لا تستخدم النص النموذجي وكنت تنشئ خادمك من البداية:
- التحقّق من طلبات
POST
باستخدامContent-Type
منapplication/reports+json
للتعرّف على التقارير الطلبات المرسلة من المتصفح إلى نقطة النهاية. - إذا كانت نقطة النهاية تقع على مصدر مختلف عن موقعك الإلكتروني، تأكَّد من أنّها تتيح طلبات الطلب المبدئي لسياسة مشاركة الموارد المتعددة المصادر (CORS).
الخيار 3: الجمع بين الخيار 1 و2
قد ترغب في السماح لمقدم خدمة معين بالاعتناء ببعض أنواع التقارير، ولكن يكون لديك حساب داخلي للآخرين.
في هذه الحالة، يمكنك ضبط نقاط نهاية متعددة على النحو التالي:
Reporting-Endpoints: endpoint-1="https://reports-collector.example", endpoint-2="https://my-custom-endpoint.example"
ضبط عنوان Reporting-Endpoints
اضبط عنوان استجابة Reporting-Endpoints
. يجب أن تكون قيمتها عبارة عن واحدة أو سلسلة من الفواصل
أزواج المفتاح/القيمة:
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
في حال النقل من واجهة Reporting API القديمة إلى Reporting API الجديدة، يمكنك
ضبط كل من Reporting-Endpoints
وReport-To
. يمكنك الاطّلاع على التفاصيل في دليل نقل البيانات. على وجه الخصوص، إذا كنت تستخدم التقارير
Content-Security-Policy
انتهاكات من خلال توجيه report-uri
فقط، يُرجى الاطّلاع على خطوات نقل البيانات لإعداد تقارير سياسة أمان المحتوى (CSP).
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: ...
المفاتيح (أسماء نقاط النهاية)
يمكن أن يكون كل مفتاح اسمًا من اختيارك، مثل main-endpoint
أو endpoint-1
.
يمكنك اختيار ضبط نقاط نهاية مُسمّاة مختلفة لتقرير مختلف
الأنواع، مثل my-coop-endpoint
وmy-csp-endpoint
. باستخدام هذا،
توجيه التقارير إلى نقاط نهاية مختلفة بناءً على نوعها.
إذا كنت تريد تلقّي تدخل و/أو إيقاف و/أو تعطُّل
التقارير، اضبط نقطة نهاية باسم default
.
إذا لم يحدّد العنوان Reporting-Endpoints
نقطة نهاية default
، لن يتم إرسال تقارير من هذا النوع (على الرغم من أنّه سيتم إنشاؤها).
القيم (عناوين URL)
كل قيمة هي عنوان URL من اختيارك، ليتم إرسال التقارير إليه. عنوان URL تحديدها هنا يعتمد على ما قررته في الخطوة 1.
عنوان URL لنقطة النهاية:
- يجب أن يبدأ بشرطة مائلة (
/
). ولا يتم دعم المسارات النسبية. - يمكن أن يكون من مصادر متعددة. ولكن في هذه الحالة، لا يتم إرسال بيانات الاعتماد مع التقارير.
أمثلة
Reporting-Endpoints: my-coop-endpoint="https://reports.example/coop", my-csp-endpoint="https://reports.example/csp", default="https://reports.example/default"
يمكنك بعد ذلك استخدام كل نقطة نهاية مُسمّاة في السياسة المناسبة، أو استخدام نقطة نهاية واحدة على مستوى جميع السياسات.
أين يمكن ضبط العنوان؟
في Reporting API الجديدة، وهي الواجهة التي
بعد ذلك - يتم تحديد نطاق التقارير على المستندات. وهذا يعني أنه بالنسبة إلى إحدى
الأصل، والمستندات المختلفة، مثل site.example/page1
بإمكان "site.example/page2
" إرسال التقارير إلى نقاط نهاية مختلفة.
لتلقي تقرير عن الانتهاكات أو عمليات الإيقاف التي تحدث في أي صفحة من موقع، يمكنك ضبط العنوان كبرمجية وسيطة على جميع الردود.
إليك مثال على Express:
const REPORTING_ENDPOINT_BASE = 'https://report.example';
const REPORTING_ENDPOINT_MAIN = `${REPORTING_ENDPOINT_BASE}/main`;
const REPORTING_ENDPOINT_DEFAULT = `${REPORTING_ENDPOINT_BASE}/default`;
app.use(function (request, response, next) {
// Set up the Reporting API
response.set(
'Reporting-Endpoints',
`main-endpoint="${REPORTING_ENDPOINT_MAIN}", default="${REPORTING_ENDPOINT_DEFAULT}"`,
);
next();
});
تعديل السياسات
الآن بعد أن تم إعداد عنوان Reporting-Endpoints
، أضِف السمة report-to
لكل عنوان سياسة ترغب في تجنُّب انتهاكها
التقارير. يجب أن تكون قيمة report-to
إحدى نقاط النهاية المسماة التي
تكوينه.
يمكنك استخدام نقاط النهاية المتعددة لسياسات متعددة أو استخدام نقاط النهاية في جميع السياسات.
report-to
غير مطلوب في الإيقاف النهائي والتدخل والعطل
التقارير. هذه التقارير غير مرتبطة بأي سياسة. يتم إنشاؤها طالما
تم إعداد نقطة نهاية default
وإرسالها إلى نقطة النهاية default
هذه.
مثال
# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0;report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the default endpoint
مثال على الرمز
وللاطّلاع على كل ذلك في السياق، إليك مثال على خادم عقدة يستخدم Express. وتجمع كل الأجزاء التي تمت مناقشتها في هذه المقالة. إنه يوضح كيفية إعداد التقارير لعدة أنواع مختلفة من التقارير وعرض النتائج.
تصحيح الأخطاء في إعداد التقارير
إنشاء التقارير عمدًا
عند إعداد Reporting API، من المحتمل أن تنتهك عمدًا سياساتك للتحقّق من إنشاء التقارير وإرسالها على النحو المتوقّع. الاطلاع على مثال للرمز البرمجي الذي ينتهك السياسات ويقوم بأمور سيئة أخرى إنشاء تقارير من جميع الأنواع، راجِع العرض التوضيحي.
توفير الوقت
قد يتم إرسال التقارير مع تأخير - حوالي دقيقة، وهو وقت طويل
عند تصحيح الأخطاء. لحسن الحظ، يمكنك استخدام العلامة عند تصحيح الأخطاء في Chrome
--short-reporting-delay
لتلقّي التقارير فور إنشائها.
نفِّذ الأمر التالي في الوحدة الطرفية لتفعيل هذه العلامة:
YOUR_PATH/TO/EXECUTABLE/Chrome --short-reporting-delay
استخدام أدوات مطوري البرامج
في متصفّح Chrome، استخدِم "أدوات مطوري البرامج" للاطّلاع على التقارير التي تم إرسالها أو إرسالها.
اعتبارًا من تشرين الأول (أكتوبر) 2021، أصبحت هذه الميزة تجريبية. ولاستخدامه، يُرجى اتباع الخطوات التالية:
- استخدام الإصدار 96 من Chrome والإصدارات الأحدث (يمكنك الاطّلاع على النص
chrome://version
في المتصفّح) - اكتب أو ألصِق
chrome://flags/#enable-experimental-web-platform-features
في شريط عناوين URL في متصفِّح Chrome. - انقر على مُفعَّلة.
- إعادة تشغيل المتصفّح
- افتح "أدوات مطوري البرامج في Chrome".
- افتح "الإعدادات" في "أدوات مطوري البرامج في Chrome". ضمن "التجارب"، انقر على تفعيل لوحة Reporting API في لوحة التطبيق.
- أعِد تحميل أدوات مطوري البرامج.
- إعادة تحميل الصفحة ستظهر التقارير التي يتم إنشاؤها من خلال الصفحة التي تفتح فيها "أدوات مطوري البرامج" مدرجة ضمن "أدوات مطوري البرامج في Chrome" التطبيق ضمن Reporting API.
![لقطة شاشة تعرض التقارير في "أدوات مطوري البرامج"](https://developer.chrome.com/static/docs/capabilities/web-apis/reporting-api/image/screenshot-devtools-list-adb1aaa437b6b.png?authuser=19&hl=ar)
حالة التقرير
يُطلعك عمود الحالة على ما إذا تمّ إرسال التقرير بنجاح.
الحالة | الوصف |
---|---|
Success |
أرسل المتصفِّح التقرير وردت نقطة النهاية برمز نجاح (200 أو رمز استجابة نجاح آخر 2xx ). |
Pending |
يحاول المتصفّح حاليًا إرسال التقرير. |
Queued |
تم إنشاء التقرير ولا يحاول المتصفّح إرساله حاليًا. يظهر التقرير على أنّه Queued في إحدى هاتين الحالتَين:
|
MarkedForRemoval |
بعد إعادة المحاولة لبعض الوقت (Queued )، توقّف المتصفّح عن محاولة إرسال التقرير، وستتم إزالته قريبًا من قائمة التقارير لإرساله. |
تتم إزالة التقارير بعد فترة، سواء تم إرسالها بنجاح أم لا.
تحديد المشاكل وحلّها
ألا يتم إنشاء التقارير أو لم يتم إرسالها إلى نقطة النهاية على النحو المتوقع؟ إليك بعض النصائح لتحديد هذه المشكلة وحلّها.
لا يتمّ إنشاء التقارير.
تم إنشاء التقارير التي تظهر في "أدوات مطوري البرامج" بشكل صحيح. إذا لم يظهر التقرير الذي تتوقّعه في هذه القائمة:
- تحقَّق من
report-to
في السياسات. إذا تم إعداد ذلك بشكل خاطئ، لن يتم إنشاء التقرير. انتقِل إلى تعديل السياسات من أجل لإصلاح ذلك. تتوفّر طريقة إضافية لتحديد المشاكل وحلّها من خلال الاطّلاع على "وحدة تحكّم أدوات مطوّري البرامج" في Chrome: إذا الخطأ في وحدة التحكم بسبب الانتهاك الذي توقعته، فهذا يعني أنه من المحتمل بشكل صحيح. - ضع في اعتبارك أن التقارير التي تم إنشاؤها للمستند "أدوات مطوري البرامج" فقط هي التي سيتم فتحها
ستظهر في هذه القائمة. مثال: إذا كان موقعك الإلكتروني
site1.example
يضمِّن إطار iframesite2.example
تنتهك إحدى السياسات وبالتالي تنشئ تقريرًا، لن يظهر هذا التقرير في "أدوات مطوري البرامج" إلا إذا فتحت إطار iframe في نافذته الخاصة وفتح "أدوات مطوري البرامج" لتلك النافذة
يتم إنشاء التقارير ولكن لا يتم إرسالها أو عدم استلامها.
ماذا لو كان بإمكانك الاطّلاع على تقرير في "أدوات مطوري البرامج" ولكنّ نقطة النهاية لم تتلقَّه؟
- احرص على استخدام مهلات قصيرة. ربما يكون السبب في عدم تمكّنك من رؤية تقرير هو لم يتم إرسالها بعد!
تحقَّق من إعدادات عنوان
Reporting-Endpoints
. إذا كانت هناك مشكلة بها، فإن الإبلاغ عن تم إنشاؤها بشكل صحيح لن يتم إرسالها. في "أدوات مطوّري البرامج"، ستظل حالة التقريرQueued
(قد يتم الانتقال مباشرةً إلىPending
، ثم العودة بسرعة إلىQueued
عند محاولة التسليم تنفيذه) في هذه الحالة. إليك بعض الأخطاء الشائعة التي قد تؤدي إلى حدوث ذلك:يتم استخدام نقطة النهاية ولكن لم يتم إعدادها. مثال:
Document-Policy: document-write=?0;report-to=endpoint-1; Reporting-Endpoints: default="https://reports.example/default"
يجب إرسال تقارير انتهاك سياسة المستند إلى endpoint-1
، ولكن لم يتم ضبط اسم نقطة النهاية هذا في
Reporting-Endpoints
نقطة نهاية
default
غير متوفّرة. بعض أنواع التقارير، مثل الإيقاف النهائي والتدخل سيتم إرسال التقارير فقط إلى نقطة النهاية المسماةdefault
. اطّلِع على المزيد من المعلومات في مقالة ضبط عنوان نقاط النهاية لإعداد التقارير.ابحث عن المشاكل في بنية عناوين السياسة، مثل علامات الاقتباس غير المتوفّرة. الاطّلاع على التفاصيل
تأكَّد من أنّ نقطة النهاية يمكنها التعامل مع الطلبات الواردة.
تأكَّد من أنّ نقطة النهاية تتوافق مع طلبات الطلب المبدئي لسياسة CORS. وإذا لم يكن متوفّرًا، لا يمكن تلقّي التقارير.
اختبِر سلوك نقطة النهاية. لإجراء ذلك، بدلاً من إنشاء التقارير يدويًا، يمكنك محاكاة المتصفح عن طريق إرسال طلبات نقاط النهاية التي تبدو ما الذي سيرسله المتصفح. قم بتشغيل ما يلي:
curl --header "Content-Type: application/reports+json" \ --request POST \ --data '[{"age":420,"body":{"columnNumber":12,"disposition":"enforce","lineNumber":11,"message":"Document policy violation: document-write is not allowed in this document.","policyId":"document-write","sourceFile":"https://dummy.example/script.js"},"type":"document-policy-violation","url":"https://dummy.example/","user_agent":"xxx"},{"age":510,"body":{"blockedURL":"https://dummy.example/img.jpg","destination":"image","disposition":"enforce","type":"corp"},"type":"coep","url":"https://dummy.example/","user_agent":"xxx"}]' \ YOUR_ENDPOINT
من المفترض أن تستجيب نقطة النهاية برمز نجاح (
200
أو رمز استجابة نجاح آخر2xx
). إذا لم يحدث ذلك، هناك مشكلة في إعدادها.
آليات الإبلاغ ذات الصلة
إعداد التقارير فقط
يعمل -Report-Only
عنوان سياسة وReporting-Endpoints
معًا.
تم إعداد نقاط النهاية في Reporting-Endpoints
وتحديدها في الحقل report-to
من
Content-Security-Policy
،
Cross-Origin-Embedder-Policy
و
Cross-Origin-Opener-Policy
سنتلقى البلاغات عند انتهاك هذه السياسات.
يمكن أيضًا تحديد نقاط النهاية التي تم ضبطها في Reporting-Endpoints
في
حقل واحد (report-to
) من
Content-Security-Policy-Report-Only
،
Cross-Origin-Embedder-Policy-Report-Only
و
Cross-Origin-Opener-Policy-Report-Only
وسيتلقّون أيضًا تقارير عند انتهاك هذه السياسات.
وعلى الرغم من إرسال التقارير في كلتا الحالتين، لا تفرض عناوين -Report-Only
السياسات: لن يتم إيقاف أي شيء أو سيتم حظره في الواقع، لكنك ستتلقى
تقارير عما كان سيتم اختراقه أو حظره.
ReportingObserver
يمكنك الاستفادة من ReportingObserver
JavaScript API
ومراقبة التحذيرات من جانب العميل.
يُنشئ ReportingObserver
والعنوان Reporting-Endpoints
تقارير
تبدو متشابهة، لكنها تتيح حالات استخدام مختلفة قليلاً.
استخدِم السمة ReportingObserver
في الحالات التالية:
- وتريد فقط مراقبة عمليات الإيقاف و/أو التدخلات في المتصفح.
يعرض
ReportingObserver
التحذيرات من جهة العميل، مثل عمليات الإيقاف نهائيًا. من خلال المتصفح، ولكن بخلافReporting-Endpoints
، لا تسجيل أي أنواع أخرى من التقارير مثل انتهاكات سياسة أمان المحتوى (CSP) أو سياسة COOP/COEP. - عليك التفاعل مع هذه الانتهاكات في الوقت الفعلي. يصنع
ReportingObserver
إمكانية إرفاق معاودة الاتصال بحدث انتهاك. - تريد إرفاق معلومات إضافية بالتقرير للمساعدة في تصحيح الأخطاء، من خلال ميزة معاودة الاتصال المخصّصة.
الفرق الآخر هو أنّه يتم ضبط ReportingObserver
من جهة العميل فقط:
يمكنك استخدامها حتى إذا لم تكن لديك
سيطرة على العناوين من جهة الخادم
المجموعة Reporting-Endpoints
.
محتوى إضافي للقراءة
- دليل نقل البيانات من الإصدار 0 إلى الإصدار 1 من Reporting API
- ReportingObserver
- المواصفات: واجهة Reporting API القديمة (الإصدار 0)
- المواصفات: واجهة Reporting API الجديدة (الإصدار 1)
صورة رئيسية من تصميم Nine Koepfer / @enka80 على الموقع الإلكتروني إلغاء البداية، تم التعديل نشكر "إيان كليلاند" و"إيجي كيتامورا" و"ميليكا ميهاجيليا" على مراجعاتهم واقتراحاتهم لهذه المقالة.