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

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

Maud Nalpas

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

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

ملخّص

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

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

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

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

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

إذا كنت تحتفظ بخدمة نقطة نهاية أو تدير خدمة خاصة بك، يمكنك توقّع عدد أكبر من الزيارات عند نقل بياناتك أو المطوّرين الخارجيين إلى الإصدار الأول من 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 تقارير أخطاء الشبكة. اطّلِع على مزيد من المعلومات في خطوات نقل البيانات.
• لن يتم دعم الإصدار v0 ولن يتم دعمه عبر المتصفحات. من المرجح أن يتم دعم الإصدار 1 عبر متصفحات متعددة في المستقبل.

العناصر التي لن تتغير

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

• لن يؤثر الإصدار الأول من Reporting API في ReportingObserver. تواصل ميزة "ReportingObserver" الوصول إلى جميع التقارير القابلة للتتبّع، ويُعدّ تنسيقها مطابقًا.

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

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

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

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

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

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

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

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

مع وضع ذلك في الاعتبار:

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

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

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

1. الخطوة 1 (افعلها الآن): استخدِم كلا العنوانين: Report-To (v0) وReporting-Endpoints (v1).

   وبذلك ستحصل على:

   • تقارير من عملاء Chrome وEdge الجدد بفضل Reporting-Endpoints (الإصدار 1)
   • تقارير من عملاء Chrome وEdge القديمين بفضل Report-To (الإصدار 0)

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

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

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

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

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

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

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

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

• باستخدام عنوان سياسة أمان المحتوى (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)
• المواصفات: واجهة برمجة التطبيقات القديمة لإعداد التقارير (الإصدار 0)
• المواصفات: Reporting API الجديدة (الإصدار 1)

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