تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

تحذير: إذا كنت تستخدم تسجيل أخطاء الشبكة، يمكنك مواصلة استخدام Report-To (الإصدار 0) لأنّ ميزة "تسجيل أخطاء الشبكة" غير متاحة في الإصدار 1 من Reporting API.

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

العرض التجريبي والرمز

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

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

التغييرات

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

الإصدار 0 (قديم)

 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

يستخدم {0 العنوان Report-To لضبط مجموعات نقاط النهاية المُسمّاة، وتوجيه report-to في العناوين الأخرى للإشارة إلى مجموعات نقاط النهاية هذه.

الإصدار 1 (جديد)

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

يستخدم الإصدار 1 العنوان Reporting-Endpoints لضبط نقاط نهاية مُسمّاة. مثل الإصدار 0، يستخدم الإصدار 1 توجيه report-to في رؤوس أخرى للإشارة إلى مجموعات نقاط النهاية هذه.

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

الإصدار 0 (قديم)

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

الإصدار 1 (جديد)

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

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

الإجراءات التي لن تتغيّر

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

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

	Reporting API القديمة (الإصدار 0) `Report-To` العنوان	واجهة Reporting API الجديدة (الإصدار 1) `Reporting-Endpoints` العنوان
دعم المتصفح	الإصدار 69 من Chrome والإصدارات الأحدث والإصدار 69 من Edge والإصدارات الأحدث	الإصدار 96 من Chrome والإصدار 96 من Edge. يتوافق Firefox مع هذه الميزة. لا يعترض Safari على ذلك. اطّلِع على إشارات المتصفّح.
نقاط النهاية	إرسال التقارير إلى أيّ من أدوات جمع التقارير المتعدّدة (عناوين URL متعدّدة محدّدة لكل مجموعة نقاط نهاية)	تُرسِل التقارير إلى مجمعي تقارير محدّدين (عنوان URL واحد فقط محدّد لكل نقطة نهاية).
واجهة برمجة التطبيقات	يستخدم العنوان `Report-To` لضبط مجموعات نقاط النهاية المُسمّاة.	يستخدم الرأس `Reporting-Endpoints` لضبط نقاط نهاية مُسمّاة.
أنواع التقارير التي يمكن إنشاؤها من خلال واجهة برمجة التطبيقات هذه	الإيقاف النهائي التدخل حادث سير سياسة مشاركة المعلومات (COOP/COEP) المستوى 3 من Content-Security-Policy (المستوى 3 من سياسة أمان المحتوى) تسجيل أخطاء الشبكة (NEL) _{يمكنك الاطّلاع على مزيد من المعلومات عن أنواع التقارير في مقالة Reporting API.}	لم يتم إجراء أي تغييرات، باستثناء تسجيل أخطاء الشبكة (NEL): لا تتوفّر هذه الوظيفة في Reporting API الجديدة (الإصدار 1).
نطاق التقرير	للمصدر. يؤثر رأس `Report-To` للمستند في المستندات (الصفحات) الأخرى من هذا المصدر. لا يزال حقل `url` في التقرير يختلف حسب المستند.	مستند. لا يؤثر عنوان `Reporting-Endpoints` للمستند إلا في هذا المستند. لا يزال حقل `url` في التقرير يختلف حسب المستند.
عزل التقارير (التجميع)	سيتم تجميع المستندات (الصفحات) أو المواقع الإلكترونية/المصادر المختلفة التي تنشئ تقريرًا في الوقت نفسه تقريبًا والتي لها نقطة نهاية إعداد التقارير نفسها معًا: سيتم إرسالها في الرسالة نفسها إلى نقطة نهاية إعداد التقارير.	لا يتم أبدًا إرسال تقارير من مستندات (صفحات) مختلفة معًا. حتى إذا أنشأ مستندان (صفحتان) من المصدر نفسه تقريرًا في الوقت نفسه لنقطة النهاية نفسها، لن يتم تجميعهما في حزمة. هذه آلية للحدّ من هجمات الخصوصية. قد يتم إرسال التقارير من المستند (الصفحة) نفسه معًا.
توفير ميزة موازنة الحمل أو الأولويات	نعم	لا

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

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

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

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

نقل البيانات الأساسية

الرمز القديم (مع الإصدار 0)

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

الرمز الجديد (رمز الانتقال مع الإصدار 0 إلى جانب الإصدار 1)

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

إذا كانت لديك وظائف إعداد التقارير في موقعك الإلكتروني، احتفظ بـ Report-To بشكل مؤقت فقط (إلى أن يتم تحديث معظم عملاء Chrome وEdge) لتجنُّب فقدان التقارير.

إذا كنت بحاجة إلى ميزة "تسجيل أخطاء الشبكة"، احتفظ بالإصدار Report-To إلى أن يصبح البديل لميزة "تسجيل أخطاء الشبكة" متاحًا.

رمز جديد (مع الإصدار 1 فقط)

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

هذا هو الشكل الذي يمكن أن يبدو عليه الرمز البرمجي في المستقبل، بعد تحديث معظم عملاء Chrome وEdge وتوافقهم مع الإصدار 1 من واجهة برمجة التطبيقات.

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

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

الرمز القديم (مع الإصدار 0)، مثلاً مع Express

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

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

رمز جديد (مع الإصدار 1)، مثلاً مع Express

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

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

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

الرمز القديم الذي يتضمّن report-uri فقط

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

لم يعُد استخدام report-uri فقط مُقترَحًا. إذا كان الرمز يبدو على النحو الموضّح أعلاه، عليك نقل البيانات. اطّلِع على أمثلة الرموز الجديدة أدناه (باللون الأخضر).

رمز قديم أفضل، مع report-uri وتوجيه report-to مع عنوان Report-To (v0)

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

هذا الرمز أفضل: يستخدم هذا الرمز report-to، وهو البديل الجديد لمحاولة report-uri. لا يزال التنسيق report-uri متاحًا للحفاظ على التوافق مع الإصدارات القديمة، لأنّ العديد من المتصفّحات لا تتوافق مع التنسيق report-to ولكنها تتوافق مع التنسيق report-uri.

ومع ذلك، يمكن تحسين ذلك: تستخدِم هذه الرموز الإصدار 0 من Reporting API (عنوان Report-To). نقل البيانات إلى الإصدار 1: اطّلِع على مثال "الرمز الجديد" أدناه (باللون الأخضر).

رمز جديد يتضمّن report-uri وتوجيه report-to مع عنوان Reporting-Endpoints (الإصدار 1)

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

يجب إبقاء التوجيه report-uri بجانب التوجيه report-to إلى أن يصبح التوجيه report-to متاحًا في جميع المتصفّحات. اطّلِع على جدول توافق المتصفّحات.

يُرجى إبقاء Report-To بجانب Reporting-Endpoints مؤقتًا. بعد ترقية معظم مستخدمي Chrome وEdge إلى إصدارات المتصفّح 96 والإصدارات الأحدث، أزِل Report-To.

مراجع إضافية

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

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