نقل البيانات إلى الإصدار 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).

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

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

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

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

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

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

التغييرات

• تختلف مساحة واجهة برمجة التطبيقات.

 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

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

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

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

ما لن يتغيّر

• لم يطرأ أي تغيير على تنسيق التقارير وبنيتها.
• يبقى الطلب الذي يرسله المتصفّح إلى نقطة النهاية طلب POST من Content-type application/reports+json.
• تتوفّر إمكانية ربط نقاط نهاية معيّنة بأنواع تقارير معيّنة في كلّ من الإصدار 0 والإصدار 1.
• لم يتغيّر دور نقطة النهاية default.

• لا يؤثر الإصدار 1 من Reporting API في ReportingObserver. سيظل بإمكان ReportingObserver الوصول إلى جميع التقارير القابلة للملاحظة، وسيكون تنسيقها متطابقًا.

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

على مطوّري نقاط النهاية توقُّع المزيد من الزيارات

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

ويرجع ذلك إلى أنّ التقارير لا يتم تجميعها مع الإصدار 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، عليك الانتقال إلى الإصدار 1 من Reporting API (اطّلِع على خطوات نقل البيانات). إذا كان موقعك الإلكتروني يستخدم حاليًا وظيفة إعداد التقارير بشأن انتهاكات سياسة أمان المحتوى، راجِع خطوات نقل البيانات الخاصة بإعداد التقارير بشأن سياسة أمان المحتوى.
• إذا كان موقعك الإلكتروني لا يستخدم Reporting API حاليًا وكنت بصدد إضافة وظيفة إعداد التقارير، استخدِم Reporting API الجديدة (الإصدار 1) (العنوان Reporting-Endpoints). هناك استثناء واحد لهذه القاعدة: إذا كنت بحاجة إلى استخدام Network Error Logging، استخدِم Report-To (الإصدار 0). لا تتوافق ميزة Network Error Logging حاليًا مع الإصدار 1 من Reporting API. سيتم تطوير آلية جديدة لتسجيل أخطاء الشبكة، ولكن إلى أن تصبح متاحة، يمكنك استخدام الإصدار 0 من Reporting API. إذا كنت بحاجة إلى ميزة "تسجيل أخطاء الشبكة" إلى جانب أنواع التقارير الأخرى، استخدِم كلاً من Report-To (الإصدار 0) وReporting-Endpoints (الإصدار 1)، إذ يوفّر لك الإصدار 0 ميزة "تسجيل أخطاء الشبكة"، بينما يوفّر لك الإصدار 1 تقارير عن جميع الأنواع الأخرى.

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

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

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

   من خلال ذلك، يمكنك الاستفادة مما يلي:

   • تقارير من إصدارات أحدث من متصفّحَي Chrome وEdge بفضل Reporting-Endpoints (الإصدار 1)
   • تقارير من إصدارات قديمة من متصفّحَي Chrome وEdge بفضل Report-To (الإصدار 0)

   ستستخدم مثيلات المتصفّح المتوافقة مع Reporting-Endpoints هذه الميزة، وستستخدم المثيلات غير المتوافقة معها Report-To.Reporting-Endpoints يكون تنسيق الطلب والتقرير هو نفسه في الإصدارَين 0 و1.

2. الخطوة 2 (يجب تنفيذها الآن): تأكَّد من ضبط العنوان Reporting-Endpoints على جميع الردود التي قد تنشئ تقارير.

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

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

   هناك استثناء واحد: إذا كنت بحاجة إلى تقارير Network Error Logging، احتفِظ بـ Report-To إلى أن يتوفّر آلية جديدة لخدمة Network Error Logging.

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

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

هناك طريقتان يمكن من خلالهما ضبط تقارير انتهاك سياسة أمان المحتوى:

• باستخدام عنوان CSP وحده من خلال التوجيه report-uri وهي متوافقة مع مجموعة كبيرة من المتصفّحات، بما في ذلك Chrome وFirefox وSafari وEdge. يتم إرسال التقارير مع نوع المحتوى application/csp-report ويكون لها تنسيق خاص بسياسة أمان المحتوى (CSP). يُطلق على هذه التقارير اسم "تقارير المستوى 2 من CSP" وهي لا تعتمد على 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. الخطوة 1 (يجب تنفيذها الآن): إذا لم تضِف report-to بعد، أضِفها بجانب report-uri. ستستخدم المتصفحات التي تتوافق مع report-uri فقط (Firefox) هذا التنسيق، بينما ستستخدم المتصفحات التي تتوافق أيضًا مع report-to(Chrome وEdge) هذا التنسيق.report-urireport-to لتحديد نقاط النهاية المسماة التي ستستخدمها في report-to، استخدِم كلا العنوانين Report-To وReporting-Endpoints. يضمن ذلك حصولك على تقارير من كل من إصدارات Chrome وEdge القديمة والجديدة.

2. الخطوة 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 header)، قد تحتاج إلى تعديل Content-Security-Policy كجزء من عملية نقل البيانات إلى الإصدار الجديد من Reporting API (الإصدار 1).

عملية النقل الأساسية

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

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" }] }

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

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

مراقبة جميع الصفحات

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

// 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(...)
});

نقل بيانات تقارير CSP

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

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

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

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

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

نتقدّم بالشكر الجزيل إلى "إيان كللاند" و"إيجي كيتامورا" و"ميليكا ميهايليا" على مراجعاتهم واقتراحاتهم بشأن هذه المقالة.