تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

نقل البيانات إلى الإصدار 1 من Reporting API

يتوفّر إصدار جديد من Reporting API. إنها أكثر خصوصية ومن المرجح أن يتم دعمها عبر المتصفحات.

Maud Nalpas

تُعلمك Reporting API بالأخطاء التي تحدث في موقعك الإلكتروني عندما يستخدمها الزوّار. إنه يعطي إمكانية الاطّلاع على تدخلات المتصفّح وأعطال المتصفّح وانتهاكات سياسة أمان المحتوى انتهاكات COOP/COEP، وتحذيرات الإيقاف والمزيد.

يتوفّر إصدار جديد من Reporting API. تتميز واجهة برمجة التطبيقات الجديدة بأنها أقل كثافة ويُرجح أن تكون المتوافقة مع مختلف المتصفّحات

ملخّص

مطوّرو المواقع الإلكترونية

إذا كانت لديك وظيفة إعداد التقارير في موقعك الإلكتروني: عليك الانتقال إلى الإصدار 1 باستخدام العنوان الجديد. (Reporting-Endpoints)، ولكن عليك الاحتفاظ بالرأس القديم لبعض الوقت (Report-To). يُرجى الاطّلاع على نقل البيانات: نموذج الرمز.

إذا كنت تضيف وظيفة إعداد التقارير إلى موقعك الإلكتروني الآن: استخدِم الرأس الجديد فقط (Reporting-Endpoints).

⚠️ في كلتا الحالتين، يجب ضبط عنوان Reporting-Endpoints على جميع الردود التي قد إنشاء التقارير.

مطوّرو خدمات إعداد التقارير

في حال كنت تستخدم خدمة نقطة نهاية أو كنت تعمل بنفسك، يمكنك توقّع ارتفاع عدد الزيارات بسبب أو للمطوّرين الخارجيين نقل البيانات إلى الإصدار 1 من Reporting API (العنوان Reporting-Endpoints).

استمر في القراءة للحصول على التفاصيل وأمثلة التعليمة البرمجية!

تسجيل أخطاء الشبكة

تنبيه: إذا كنت تستخدم تسجيل أخطاء في الشبكة، عليك مواصلة استخدام Report-To (الإصدار 0) لأنّ ميزة "تسجيل أخطاء الشبكة" غير متاحة في الإصدار 1 من Reporting API.

سيتم تطوير آلية جديدة لتسجيل أخطاء الشبكة. وعندما تصبح هذه الميزة متاحة، يمكنك التبديل من الإصدار 0 من Reporting API إلى الآلية الجديدة.

العرض التوضيحي والرمز البرمجي

الموقع الإلكتروني التجريبي: واجهة برمجة التطبيقات لإعداد التقارير الجديدة (الإصدار 1)
رمز الموقع الإلكتروني التجريبي

الاختلافات بين الإصدار v0 والإصدار 1

التغييرات

يختلف سطح واجهة برمجة التطبيقات عن ذلك.

v0 (قديم)

 Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": ... }, { "url": ... }] }
 Document-Policy: ...; report-to main-endpoint

{0 يستخدم العنوان Report-To لضبط مجموعات نقاط النهاية المسماة، والتوجيه report-to في العناوين الأخرى للإشارة إلى مجموعات نقاط النهاية هذه.

الإصدار 1 (جديد)

 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

يستخدم الإصدار 1 رأس Reporting-Endpoints لضبط إعدادات والنقاط النهائية. وعلى غرار الإصدار 0، فهو يستخدم التوجيه report-to في العناوين الأخرى للإشارة إلى مجموعات نقاط النهاية هذه.

نطاق التقرير مختلف.

v0 (قديم)

باستخدام الإصدار 0، يمكنك ضبط نقاط نهاية الإبلاغ على بعض الردود فقط. مستندات أخرى (صفحات) على تلك المستندات نقطة النهاية في البيئة المحيطة هذه تلقائيًا.

الإصدار 1 (جديد)

في الإصدار 1، يجب ضبط العنوان Reporting-Endpoints في كل الاستجابات التي قد تؤدي إلى إنشاء التقارير.

تدعم كلتا واجهتَي برمجة التطبيقات أنواع التقارير نفسها، مع استثناء واحد: لا يتوافق الإصدار 1 مع تقارير أخطاء الشبكة. يمكنك الاطّلاع على المزيد من المعلومات في خطوات نقل البيانات.
الإصدار 0 ليس متاحًا ولن يكون متوافقًا مع جميع المتصفحات. ومن المرجح أن يتوافق الإصدار 1 مع متصفحات متعددة في المستقبل.

البيانات التي لم يتم تغييرها

ولم يطرأ أي تغيير على تنسيق التقارير وبنيتها.
يظل الطلب الذي أرسله المتصفّح إلى نقطة النهاية ضمن طلب POST للموقع الإلكتروني Content-type. application/reports+json
يتوفّر ربط نقاط نهاية معيّنة بأنواع تقارير معيّنة في الإصدارَين 0 و1.
لم يتغيَّر دور نقطة النهاية default.
لا يؤثّر الإصدار 1 من Reporting API على ReportingObserver. سيظل بإمكان "ReportingObserver" الوصول إلى كل التقارير القابلة للتتبّع، وتنسيقها هو متطابقة.

جميع الاختلافات بين الإصدار v0 والإصدار 1

	Legacy Reporting API (الإصدار 0) عنوان `Report-To`	Reporting API الجديدة (الإصدار 1) عنوان `Reporting-Endpoints`
دعم المتصفح	Chrome 69 أو Edge 69 أو الإصدارات الأحدث.	Chrome 96+ وEdge 96+ Firefox داعم. لا يعترض Safari. راجِع إشارات المتصفِّح.
نقاط النهاية	يُرسِل التقارير إلى أيّ من أدوات تجميع التقارير المتعدّدة (عناوين URL متعددة محدَّدة لكل مجموعة نقاط نهاية).	تُرسِل التقارير إلى أدوات تجميع التقارير المحدَّدة (يتم تحديد عنوان URL واحد فقط لكل نقطة نهاية).
مساحة عرض واجهة برمجة التطبيقات	يتم استخدام العنوان `Report-To` لضبط مجموعات نقاط النهاية المُسَمّاة.	تستخدم العنوان `Reporting-Endpoints` لضبط نقاط النهاية المُسمّاة.
أنواع التقارير التي يمكن إنشاؤها عبر واجهة برمجة التطبيقات هذه	إيقاف تدخل حادث سير سياسة مشاركة المعلومات (COOP/COEP) المستوى 3 من سياسة أمان المحتوى (CSP المستوى 3) تسجيل أخطاء الشبكة (NEL) _{اطّلِع على مزيد من المعلومات عن أنواع التقارير في مشاركة Reporting API.}	بدون تغيير، باستثناء تسجيل أخطاء الشبكة (NEL): لا تتوفّر هذه الميزة في الإصدار 1 من Reporting API الجديد.
نطاق التقرير	للمصدر. يؤثر عنوان `Report-To` للمستند في مستندات أخرى (صفحات) من ذلك المصدر. يظل الحقل `url` في أي تقرير يختلف من مستند إلى آخر.	مستند. يؤثّر عنوان `Reporting-Endpoints` للمستند في هذا المستند فقط. يظل الحقل `url` في أي تقرير يختلف من مستند إلى آخر.
عزل التقارير (التجميع)	سيتم تجميع المستندات (الصفحات) أو المواقع الإلكترونية/المصادر المختلفة التي تنشئ تقريرًا في الوقت نفسه تقريبًا والتي تحتوي على نقطة نهاية إعداد التقارير نفسها معًا: سيتم إرسالها في الرسالة نفسها إلى نقطة نهاية إعداد التقارير.	لا يتم أبدًا إرسال التقارير من المستندات المختلفة (الصفحات) معًا. حتى إذا كان هناك مستندان (صفحتان) من المصدر نفسه ينشئان تقريرًا في الوقت نفسه لنقطة النهاية نفسها، لن يتم تجميعهما. وهي آلية للحدّ من هجمات الخصوصية. قد يتم إرسال التقارير من المستند نفسه (الصفحة) معًا.
دعم موازنة التحميل / الأولويات	نعم	لا

مطوِّرو نقاط النهاية: ترقّب المزيد من الزيارات

إذا كنت قد أعددت خادمك الخاص كنقطة نهاية لإعداد التقارير، أو إذا كنت تعمل على تطوير أو صيانة أداة تجميع التقارير كخدمة، فتوقع المزيد من حركة البيانات إلى نقطة النهاية هذه.

ويرجع ذلك إلى أنّه لا يتم تجميع التقارير مع الإصدار 1 من Reporting API كما في الإصدار 0 من Reporting API. ولذلك، وعندما يبدأ مطوّرو التطبيقات بالنقل إلى الإصدار 1 من Reporting API، سيظهر عدد التقارير ستظل متشابهة، ولكن سيزداد حجم الطلبات المُرسَلة إلى خادم نقطة النهاية.

مطوّرو التطبيقات: نقل البيانات إلى `Reporting-Endpoints` (الإصدار 1)

ما هي الإجراءات التي عليك اتخاذها؟

استخدام Reporting API (الإصدار 1) الجديد له العديد من المزايا ✅:

إشارات المتصفح إيجابية، وهو ما يعني من المتوقع أن يكون من الممكن توافق الإصدار 1 عبر المتصفح (على عكس الإصدار 0 الذي لا يتوافق إلا مع Chrome Edge).
تتميز واجهة برمجة التطبيقات بأنها أقل كثافة.
يجري تطوير الأدوات استنادًا إلى Reporting API الجديدة (الإصدار 1).

مع أخذ ذلك في الاعتبار:

إذا كان موقعك الإلكتروني يستخدم حاليًا الإصدار 0 من Reporting API مع العنوان Report-To، انتقِل إلى Reporting API v1 (الاطّلاع على خطوات نقل البيانات) إذا كان موقعك الإلكتروني يستخدم حاليًا وظيفة الإبلاغ عن انتهاكات سياسة أمان المحتوى، راجِع خطوات نقل البيانات لإعداد تقارير سياسة أمان المحتوى (CSP).
إذا لم يكن موقعك الإلكتروني يستخدم Reporting API وكنت تريد إضافة وظيفة إعداد التقارير: استخدام واجهة Reporting API الجديدة (الإصدار 1) (عنوان Reporting-Endpoints) هناك استثناء واحد هذا: إذا كنت بحاجة إلى استخدام "تسجيل أخطاء الشبكة"، استخدِم Report-To (الإصدار 0). تسجيل أخطاء الشبكة لا تتوفّر حاليًا في الإصدار 1 من Reporting API. ستتغير آلية جديدة لتسجيل أخطاء الشبكة وتطويرها⏤إلى أن يصبح هذا متاحًا، استخدم الإصدار 0 من Reporting API. في حال كنت بحاجة إلى تسجيل أخطاء الشبكة بجانب أنواع التقارير الأخرى، استخدِم كل من Report-To (الإصدار 0) وReporting-Endpoints (الإصدار 1). v0 تسجيل أخطاء الشبكة ويمنحك الإصدار 1 تقارير حول جميع الأنواع الأخرى.

خطوات نقل البيانات

هدفك من عملية نقل البيانات هذه هو عدم فقدان التقارير التي اعتدت الحصول عليها مع الإصدار 0.

الخطوة 1 (تنفيذ الآن): استخدِم كلا الرأسَين: Report-To (الإصدار 0) وReporting-Endpoints (الإصدار 1).

من خلال ذلك، تحصل على:
- التقارير من عملاء Chrome وEdge الجدد بفضل Reporting-Endpoints (الإصدار 1).
- تقارير من عملاء Chrome وEdge القديم بفضل Report-To (الإصدار 0).
إنّ مثيلات المتصفّح التي ستتوافق مع Reporting-Endpoints ستستخدم Reporting-Endpoints. الحالات التي لا تنتقل إلى Report-To. يتطابق تنسيق الطلب والتقرير مع v0 وv1
الخطوة 2 (إجراء الآن): تأكَّد من ضبط رأس Reporting-Endpoints على جميع الردود التي إنشاء التقارير.

باستخدام الإصدار 0، يمكنك اختيار ضبط نقاط نهاية إعداد التقارير على بعض الردود فقط والمستندات الأخرى. (الصفحات) في هذا المصدر قد تستخدم "وضع الاستراحة" النهائية. مع الإصدار 1، بسبب الاختلاف في لتحديد النطاق، يجب ضبط عنوان Reporting-Endpoints في جميع الردود التي قد تؤدي إلى إنشاء التقارير.
الخطوة 3 (البدء لاحقًا): بعد تحديث جميع المستخدمين أو معظمهم إلى إصدار لاحق من Chrome أو Edge عمليات التثبيت (96 والإصدارات الأحدث)، وإزالة Report-To (الإصدار 0) والاحتفاظ بـ Reporting-Endpoints فقط.

استثناء واحد: إذا كنت تحتاج إلى تقارير تسجيل أخطاء في الشبكة، احتفظ بـ Report-To حتى لتسجيل أخطاء الشبكة.

يمكنك الاطّلاع على أمثلة على الرموز في كتاب الطبخ الخاص بنقل البيانات.

خطوات نقل البيانات لإعداد تقارير سياسة أمان المحتوى (CSP)

تتوفّر Content-Security-Policy بطريقتين. تهيئة تقارير الانتهاك:

استخدام عنوان CSP وحده من خلال توجيه report-uri يدعم هذا العديد من المتصفحات، عبر Chrome وFirefox وSafari وEdge. يتم إرسال البلاغات باستخدام نوع المحتوى application/csp-report. وأن يكون لها تنسيق مخصص لـ CSP. يُطلق على هذه التقارير "تقارير سياسة CSP من المستوى 2". ونفعل عدم الاعتماد على واجهة برمجة التطبيقات Reporting API.
باستخدام Reporting API من خلال عنوان Report-To (الإصدار القديم) أو العنوان الأحدث Reporting-Endpoints (الإصدار 1). لا تتوفّر هذه الميزة إلا في Chrome وEdge. تحتوي طلبات التقارير على بالتنسيق نفسه المستخدَم في طلبات Reporting API الأخرى، ونوع المحتوى نفسه application/reports+json.

لم يعُد يُنصح باستخدام الطريقة الأولى (report-uri فقط)، كما أنّ استخدام الطريقة الثانية له بعض المزايا. وعلى وجه التحديد، تتيح لك هذه الميزة استخدام طريقة واحدة لإعداد التقارير لجميع أنواع التقارير بالإضافة إلى إعداد نقطة نهاية عامة (لأنّ جميع طلبات التقارير التي يتم إنشاؤها من خلال Reporting API⏤CSP وغيرها⏤التنسيق نفسه application/reports+json.

يُرجى العِلم أنّ بعض المتصفّحات فقط تتوافق مع report-to. لهذا السبب، ننصحك بإبقاء السمة report-uri مع طريقة Reporting API (Report-To). أو أفضل، Reporting-Endpoints) للحصول على تقارير انتهاك سياسة CSP من عدة متصفّحات. في متصفّح يتعرّف على report-uri وreport-to، وسيتم تجاهل report-uri في حال استخدام report-to موجودة. في المتصفّح الذي يتعرّف على report-uri فقط، لن يتم اعتبار سوى report-uri.

الخطوة 1 (تنفيذ الآن): إذا لم تكن قد أضفتها بعد، أضِف report-to إلى جانب report-uri. المتصفحات المتوافقة فقط مع report-uri (Firefox) ستستخدم report-uri، بالإضافة إلى المتصفّحات التي تتوافق مع الدعم report-to(Chrome، Edge) سيستخدم report-to. لتحديد نقاط النهاية المسماة التي ستستخدمها في report-to، استخدِم كلا العنوانين Report-To وReporting-Endpoints. يضمن ذلك حصولك على التقارير من عملاء Chrome وEdge القديم والأحدث.
الخطوة 3 (البدء لاحقًا): بعد تحديث جميع المستخدمين أو معظمهم إلى إصدار لاحق من Chrome أو Edge عمليات التثبيت (96 والإصدارات الأحدث)، وإزالة Report-To (الإصدار 0) والاحتفاظ بـ Reporting-Endpoints فقط. عدم الحذف report-uri حتى يظل بإمكانك الحصول على تقارير للمتصفّحات التي تتوافق مع هذا الإعداد فقط.

يمكنك الاطّلاع على أمثلة الرموز لهذه الخطوات في نقل تقارير CSP.

النقل: مثال على الرمز

نظرة عامة

في حال استخدام واجهة Reporting API القديمة (الإصدار 0) للحصول على تقارير الانتهاكات المتعلّقة بسياسة COOP (عنوان Cross-Origin-Opener-Policy) أو سياسة COEP (Cross-Origin-Embedder-Policy) أو سياسة مستندات (عنوان Document-Policy): لا تحتاج إلى تغيير عناوين السياسات هذه بنفسها أثناء نقل البيانات. إلى الإصدار 1 من Reporting API عليك نقل البيانات من عنوان Report-To القديم إلى العنوان الجديد. عنوان Reporting-Endpoints

في حال استخدام واجهة Reporting API القديمة (الإصدار 0) للحصول على تقارير عن انتهاكات سياسة CSP (عنوان Content-Security-Policy)، قد تحتاج إلى تعديل Content-Security-Policy كجزء من نقل البيانات إلى واجهة Reporting API الجديدة (الإصدار 1)

نقل البيانات الأساسي

رمز برمجي قديم (باستخدام الإصدار 0)

Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }

رمز جديد (رمز نقل مع الإصدار 0 إلى جانب الإصدار 1)

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Report-To: { group: "main-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "max_age": 86400, "endpoints": [ { "url": "https://reports.example/default" }] }

إذا كانت لديك وظيفة إعداد تقارير في موقعك الإلكتروني، يُرجى الاحتفاظ بخدمة Report-To مؤقتًا فقط (إلى أن يتم تحديث معظم عملاء Chrome وEdge) لتجنُّب فقدان التقارير.

إذا كنت بحاجة إلى تسجيل أخطاء في الشبكة، احتفظ بـ Report-To حتى يتم استبدال تسجيل الخطأ في الشبكة متاحة.

رمز جديد (مع الإصدار 1 فقط)

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

هذا هو الشكل الذي يمكن أن تبدو عليه التعليمات البرمجية في المستقبل، بعد تحديث معظم عملاء Chrome وEdge والتوافق مع الإصدار 1 من واجهة برمجة التطبيقات.

تجدر الإشارة إلى أنّه باستخدام الإصدار 1، سيظل بإمكانك إرسال أنواع محدّدة من التقارير إلى نقاط نهاية محدّدة. لكنك يمكن أن يحتوي على عنوان URL واحد فقط لكل نقطة نهاية.

تتبُّع جميع الصفحات

رمز قديم (مع الإصدار 0)، على سبيل المثال مع Express

app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

باستخدام الإصدار 0، يمكنك ضبط نقاط نهاية الإبلاغ على بعض الردود فقط. مشاكل أخرى المستندات (الصفحات) على هذا المصدر تلقائيًا نقاط النهاية في البيئة المحيطة هذه. هنا، تم تعيين نقاط النهاية لـ "/"، يتم استخدامها لجميع الردود، على سبيل المثال لـ page1.

رمز جديد (مع الإصدار 1)، على سبيل المثال باستخدام Express

// Use a middleware to set the reporting endpoint(s) for *all* requests.
app.use(function(request, response, next) {
  response.set("Reporting-Endpoints", …);
  next();
});

app.get("/", (request, response) => {
  response.render(...)
});

app.get("/page1", (request, response) => {
  response.render(...)
});

في الإصدار 1، يجب ضبط عنوان Reporting-Endpoints على جميع الردود التي قد تؤدي إلى إنشاء التقارير.

نقل تقارير سياسة أمان المحتوى (CSP)

رمز قديم، يتضمّن report-uri فقط

Content-Security-Policy: ...; report-uri https://reports.example/main

لم يعد استخدام report-uri فقط بعد التي ننصح بها. إذا كان الرمز يظهر على النحو الموضّح أعلاه، عليك نقل البيانات. يمكنك الاطّلاع على أمثلة الرموز الجديدة أدناه (باللون الأخضر).

رمز قديم أفضل، مع report-uri والتوجيه report-to مع عنوان تقرير إلى (الإصدار 0)

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

هذا أفضل: تستخدم هذه التعليمة البرمجية "report-to"، الاستبدال الأحدث report-uri. ولا يزال يحافظ على تنسيق report-uri من أجل التوافق مع الأنظمة القديمة؛ several fixed لا تتوافق المتصفحات مع report-to ولكن هل تدعمون report-uri

ومع ذلك، قد يكون هذا أفضل: تستخدم هذه الرموز الإصدار 0 من Reporting API (العنوان Report-To). الانتقال إلى الإصدار 1: اطّلِع على "رمز جديد" الأمثلة أدناه (باللون الأخضر).

رمز جديد، مع report-uri و report-to مع العنوان Reporting-Endpoints (v1)

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Reporting-Endpoints: main-endpoint="https://reports.example/main"
Report-To: ...

يجب مواصلة استخدام التوجيه report-uri في التوجيه report-to إلى أن يتم إصدار التوجيه report-to. عبر جميع المتصفحات. عرض توافق المتصفح الجدول.

الاحتفاظ بـ "Report-To" إلى جانب "Reporting-Endpoints" مؤقتًا بعد تشغيل كل من Chrome وEdge أجرى الزائرون ترقية إلى أكثر من 96 إصدارًا للمتصفح، لذا عليك إزالة Report-To.

محتوى إضافي للقراءة

مراقبة تطبيق الويب باستخدام Reporting API (المشاركة الرئيسية على Reporting API)
المواصفات: واجهة Reporting API القديمة (الإصدار 0)
المواصفات: واجهة Reporting API الجديدة (الإصدار 1)

صورة رئيسية من تصميم Nine Koepfer / @enka80 على الموقع الإلكتروني إلغاء البداية، تم التعديل مع جزيل الشكر لإيان "كللاند" و"إيجي كيتامورا" و"ميليكا ميهاجيليا" على آرائهم واقتراحاتهم حول هذا الموضوع .