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

جميع الاختلافات بين الإصدار 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 لانتهاكات سياسة أمان المحتوى، اطّلِع على خطوات نقل بيانات إعداد تقارير سياسة أمان المحتوى المحدّدة.
• إذا كان موقعك الإلكتروني لا يستخدم 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، وستتحوّل النُسخ غير المتوافقة إلى 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 فقط. الاحتفاظ 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(...)
});

نقل بيانات تقارير "سياسة الخدمات في مراكز البيانات"

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)

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