نقل البيانات إلى الإصدار 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)
• رمز الموقع الإلكتروني التجريبي

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

جميع الاختلافات بين الإصدار v0 والإصدار 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، انتقِل إلى 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. الخطوة 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. الخطوة 2 (إجراء الآن): تأكَّد من ضبط رأس Reporting-Endpoints على جميع الردود التي إنشاء التقارير.

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

3. الخطوة 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. الخطوة 1 (تنفيذ الآن): إذا لم تكن قد أضفتها بعد، أضِف report-to إلى جانب report-uri. المتصفحات المتوافقة فقط مع report-uri (Firefox) ستستخدم report-uri، بالإضافة إلى المتصفّحات التي تتوافق مع الدعم report-to(Chrome، Edge) سيستخدم report-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)، قد تحتاج إلى تعديل 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)

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