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

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

Maud Nalpas

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

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

ملخّص

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

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

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

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

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

إذا كنت تدير خدمة نقاط نهاية أو تشغّل خدمتك الخاصة، توقّع زيادة في عدد الزيارات عندما تنقل أنت أو المطوّرون الخارجيون بياناتك إلى Reporting API v1 (عنوان 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" في الوصول إلى جميع التقارير القابلة للتتبّع، وسيظلّ تنسيقها متطابقًا.

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

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

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

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

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

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

خطوات نقل البيانات لإعداد تقارير "خدمة إدارة المحتوى"

هناك طريقتان لضبط تقارير Content-Security-Policy الانتهاكات:

• باستخدام عنوان CSP فقط من خلال التوجيه report-uri تتوفّر هذه الميزة على نطاق واسع في المتصفّحات Chrome وFirefox وSafari وEdge. يتم إرسال التقارير باستخدام نوع المحتوى application/csp-report ولها تنسيق خاص بخدمة "إدارة الخدمات في السحابة". تُعرف هذه التقارير باسم "تقارير المستوى 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 فقط. Keep report-uri حتى يظل بإمكانك الحصول على تقارير للمتصفّحات التي تتوافق معه فقط.

يمكنك الاطّلاع على أمثلة على الرموز البرمجية لهذه الخطوات في مقالة نقل تقارير "شركاء المحتوى في خرائط Google".

نقل البيانات: مثال على الرمز البرمجي

نظرة عامة

إذا كنت تستخدم Reporting API القديمة (الإصدار 0) للحصول على تقارير الانتهاكات المتعلّقة بسياسة تعاون المعلِنين (Cross-Origin-Opener-Policy header) أو سياسة موافقة المستخدِم (Cross-Origin-Embedder-Policy) أو سياسة المستند (Document-Policy header)، لن تحتاج إلى تغيير رؤوس السياسات هذه أثناء نقل بياناتك إلى Reporting API الإصدار 1. ما عليك سوى نقل البيانات من عنوان 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)

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