مهاجرت به Reporting API v1

نسخه جدیدی از API گزارش‌دهی (Reporting API) در دسترس است. این نسخه خصوصی‌تر است و احتمال پشتیبانی آن در مرورگرهای مختلف بیشتر است.

Maud Nalpas

API گزارش‌دهی، شما را از خطاهایی که هنگام استفاده بازدیدکنندگان از سایت شما رخ می‌دهد، مطلع می‌کند. این API به شما امکان مشاهده مداخلات مرورگر، خرابی‌های مرورگر، نقض سیاست امنیت محتوا، نقض COOP/COEP، هشدارهای منسوخ شدن و موارد دیگر را می‌دهد.

نسخه جدیدی از Reporting API در دسترس است. این API جدید سبک‌تر است و احتمال پشتیبانی آن در مرورگرهای مختلف بیشتر است.

خلاصه

توسعه‌دهندگان سایت

اگر از قبل قابلیت گزارش‌گیری برای سایت خود دارید : با استفاده از هدر جدید ( Reporting-Endpoints ) به نسخه ۱ مهاجرت کنید، اما هدر قدیمی ( Report-To ) را برای مدتی نگه دارید. به Migration: example code مراجعه کنید.

اگر همین الان قابلیت گزارش‌گیری را به سایت خود اضافه می‌کنید : فقط از سربرگ جدید ( Reporting-Endpoints ) استفاده کنید.

⚠️ در هر دو مورد، مطمئن شوید که هدر Reporting-Endpoints را برای تمام پاسخ‌هایی که ممکن است گزارش ایجاد کنند، تنظیم کرده‌اید.

توسعه‌دهندگان خدمات گزارش‌دهی

اگر در حال نگهداری یک سرویس اندپوینت هستید یا خودتان آن را اداره می‌کنید، انتظار ترافیک بیشتری را داشته باشید، زیرا شما یا توسعه‌دهندگان خارجی به Reporting API نسخه ۱ (سربرگ Reporting-Endpoints ) مهاجرت می‌کنید.

برای جزئیات و نمونه کد به خواندن ادامه دهید!

ثبت خطاهای شبکه

یک مکانیزم جدید برای ثبت خطاهای شبکه توسعه داده خواهد شد. به محض اینکه این مکانیزم در دسترس قرار گرفت، از Reporting API v0 به آن مکانیزم جدید تغییر دهید.

نسخه آزمایشی و کد

• سایت آزمایشی: API گزارش‌دهی جدید (نسخه ۱)
• کد مربوط به سایت آزمایشی

تفاوت‌های بین نسخه ۰ و نسخه ۱

چه چیزی تغییر می‌کند؟

• سطح API متفاوت است.

 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

• دامنه گزارش متفاوت است.

• هر دو API از انواع گزارش‌های یکسانی پشتیبانی می‌کنند، با یک استثنا: نسخه ۱ از گزارش‌های خطای شبکه پشتیبانی نمی‌کند. برای اطلاعات بیشتر به مراحل مهاجرت مراجعه کنید.
• نسخه ۰ در مرورگرها پشتیبانی نمی‌شود و نخواهد شد. نسخه ۱ احتمالاً در آینده در مرورگرهای مختلف پشتیبانی خواهد شد.

آنچه بدون تغییر باقی می‌ماند

• قالب و ساختار گزارش‌ها بدون تغییر باقی می‌ماند.
• درخواست ارسال شده توسط مرورگر به نقطه انتهایی، همچنان یک درخواست POST از Content-type application/reports+json است.
• نگاشت نقاط انتهایی خاص به انواع گزارش‌های خاص، هم در نسخه ۰ و هم در نسخه ۱ پشتیبانی می‌شود.
• نقش نقطه پایانی default بدون تغییر باقی می‌ماند.

• Reporting API نسخه ۱ هیچ تاثیری بر ReportingObserver ندارد. ReportingObserver همچنان به تمام گزارش‌های قابل مشاهده دسترسی دارد و قالب آنها یکسان است.

تمام تفاوت‌های بین نسخه ۰ و نسخه ۱

توسعه‌دهندگان اندپوینت: انتظار ترافیک بیشتری را داشته باشید

اگر سرور خودتان را به عنوان یک نقطه پایانی گزارش‌دهی راه‌اندازی کرده‌اید، یا اگر در حال توسعه یا نگهداری یک سرویس جمع‌آوری گزارش هستید، انتظار ترافیک بیشتری را به آن نقطه پایانی داشته باشید.

دلیل این امر این است که گزارش‌ها با Reporting API v1 مانند Reporting API v0 دسته‌بندی نمی‌شوند. بنابراین، با شروع مهاجرت توسعه‌دهندگان برنامه به Reporting API v1، تعداد گزارش‌ها مشابه باقی خواهد ماند، اما حجم درخواست‌ها به سرور نقطه پایانی افزایش خواهد یافت.

توسعه‌دهندگان برنامه: مهاجرت به Reporting-Endpoints (نسخه ۱)

چه باید بکنید؟

استفاده از API گزارش‌دهی جدید (نسخه ۱) مزایای متعددی دارد ✅:

• سیگنال‌های مرورگر مثبت هستند، به این معنی که می‌توان انتظار داشت نسخه ۱ از پشتیبانی بین مرورگرها برخوردار باشد (برخلاف نسخه ۰ که فقط در کروم و اج پشتیبانی می‌شود).
• API کم‌حجم‌تر است.
• ابزارها پیرامون API گزارش‌دهی جدید (نسخه ۱) در حال توسعه هستند.

با در نظر گرفتن این نکته:

• اگر سایت شما از قبل از Reporting API نسخه ۰ با سربرگ Report-To استفاده می‌کند، به Reporting API نسخه ۱ مهاجرت کنید ( مراحل مهاجرت را ببینید). اگر سایت شما از قبل از قابلیت گزارش‌دهی برای نقض سیاست امنیتی محتوا (CSP) استفاده می‌کند، مراحل مهاجرت خاص برای گزارش‌دهی CSP را بررسی کنید.
• اگر سایت شما از قبل از Reporting API استفاده نمی‌کند و اکنون در حال اضافه کردن قابلیت گزارش‌دهی هستید: از Reporting API جدید (نسخه ۱) (سربرگ Reporting-Endpoints ) استفاده کنید. یک استثنا در این مورد وجود دارد : اگر نیاز به استفاده از گزارش‌گیری خطای شبکه دارید، Report-To (نسخه ۰) استفاده کنید. گزارش‌گیری خطای شبکه در حال حاضر در Reporting API نسخه ۱ پشتیبانی نمی‌شود. تا زمانی که این امکان فراهم شود، مکانیزم جدیدی برای گزارش‌گیری خطای شبکه توسعه داده خواهد شد. از Reporting API نسخه ۰ استفاده کنید. اگر در کنار سایر انواع گزارش‌ها به گزارش‌گیری خطای شبکه نیاز دارید، از Report-To (نسخه ۰) و Reporting-Endpoints (نسخه ۱) استفاده کنید. نسخه ۰ گزارش‌گیری خطای شبکه و نسخه ۱ گزارش‌هایی از سایر انواع گزارش‌ها را در اختیار شما قرار می‌دهد.

مراحل مهاجرت

هدف شما در این مهاجرت این است که گزارش‌هایی را که قبلاً با نسخه ۰ دریافت می‌کردید، از دست ندهید .

1. مرحله ۱ (همین حالا انجام دهید) : از هر دو سربرگ استفاده کنید: Report-To (نسخه ۰) و Reporting-Endpoints (نسخه ۱).

   با این، شما دریافت می‌کنید:

   • گزارش‌ها از کلاینت‌های جدیدتر کروم و اج به لطف Reporting-Endpoints (نسخه ۱).
   • گزارش‌هایی از کلاینت‌های قدیمی‌تر کروم و اج به لطف Report-To (نسخه ۰).

   نمونه‌های مرورگری که Reporting-Endpoints پشتیبانی می‌کنند، Reporting-Endpoints استفاده خواهند کرد و نمونه‌هایی که این قابلیت را ندارند، از Report-To استفاده خواهند کرد. قالب درخواست و گزارش برای نسخه‌های v0 و v1 یکسان است.

2. مرحله ۲ (همین حالا انجام دهید): مطمئن شوید که هدر Reporting-Endpoints برای تمام پاسخ‌هایی که ممکن است گزارش تولید کنند، تنظیم شده است.

   با نسخه ۰، می‌توانید نقاط پایانی گزارش‌دهی را فقط روی برخی از پاسخ‌ها تنظیم کنید و سایر اسناد (صفحات) در آن مبدا از این نقطه پایانی «محیطی» استفاده کنند. با نسخه ۱، به دلیل تفاوت در محدوده، باید سربرگ Reporting-Endpoints را روی تمام پاسخ‌هایی که ممکن است گزارش تولید کنند، تنظیم کنید.

3. مرحله ۳ (بعداً شروع کنید): به محض اینکه همه یا اکثر کاربران شما به نسخه‌های جدیدتر کروم یا اج (۹۶ و بالاتر) به‌روزرسانی کردند، Report-To (نسخه ۰) را حذف کنید و فقط Reporting-Endpoints نگه دارید.

   یک استثنا: اگر به گزارش‌های ثبت خطای شبکه نیاز دارید، Report-To تا زمانی که مکانیسم جدیدی برای ثبت خطای شبکه ایجاد شود، نگه دارید.

نمونه‌های کد را در کتاب آشپزی مهاجرت ببینید.

مراحل مهاجرت برای گزارش‌دهی CSP

دو روش برای پیکربندی گزارش‌های نقض سیاست امنیت محتوا وجود دارد:

• فقط با هدر CSP از طریق دستورالعمل report-uri . این مورد پشتیبانی گسترده‌ای از مرورگرها، در سراسر Chrome، Firefox، Safari و Edge دارد. گزارش‌ها با content-type application/csp-report ارسال می‌شوند و فرمتی دارند که مختص CSP است. این گزارش‌ها "گزارش‌های سطح 2 CSP" نامیده می‌شوند و به Reporting API متکی نیستند .
• With the Reporting API, that is via Report-To header (legacy) or the newer Reporting-Endpoints (v1). This is supported in Chrome and Edge only. Report requests have the same format as other Reporting API requests, and the same content-type 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-to ، report-uri نادیده گرفته می‌شود. در مرورگری که فقط report-uri تشخیص می‌دهد، فقط report-uri در نظر گرفته می‌شود.

1. مرحله ۱ (همین حالا انجام دهید) : اگر هنوز آن را اضافه نکرده‌اید، report-to در کنار report-uri اضافه کنید. مرورگرهایی که فقط report-uri پشتیبانی می‌کنند (فایرفاکس) report-uri استفاده می‌کنند و مرورگرهایی که report-to نیز پشتیبانی می‌کنند (کروم، اج) از report-to استفاده می‌کنند. برای مشخص کردن نقاط پایانی نامگذاری شده که در report-to استفاده خواهید کرد، از هر دو سربرگ Report-To و Reporting-Endpoints استفاده کنید. این تضمین می‌کند که گزارش‌ها را از هر دو کلاینت قدیمی‌تر و جدیدتر کروم و اج دریافت خواهید کرد.

2. مرحله ۳ (بعداً شروع کنید): به محض اینکه همه یا اکثر کاربران شما به نسخه‌های جدیدتر کروم یا اج (۹۶ و بالاتر) به‌روزرسانی کردند، Report-To (نسخه ۰) را حذف کنید و فقط Reporting-Endpoints نگه دارید. report-uri را نگه دارید تا همچنان گزارش‌هایی را برای مرورگرهایی که فقط از آن پشتیبانی می‌کنند، دریافت کنید.

برای این مراحل به نمونه‌های کد در مهاجرت گزارش‌دهی CSP مراجعه کنید.

مهاجرت: کد نمونه

نمای کلی

اگر از API گزارش‌دهی قدیمی (نسخه ۰) برای دریافت گزارش‌های تخلف برای یک COOP (سربرگ Cross-Origin-Opener-Policy )، یک COEP (سربرگ Cross-Origin-Embedder-Policy ) یا یک سیاست سند (سربرگ Document-Policy ) استفاده می‌کنید: هنگام مهاجرت به Reporting API نسخه ۱، نیازی به تغییر خود سربرگ‌های این سیاست‌ها ندارید. آنچه نیاز دارید، مهاجرت از سربرگ Report-To قدیمی به سربرگ جدید Reporting-Endpoints است.

اگر از API گزارش‌دهی قدیمی (نسخه ۰) برای دریافت گزارش‌های تخلف برای CSP (سربرگ Content-Security-Policy ) استفاده می‌کنید، ممکن است لازم باشد Content-Security-Policy خود را به عنوان بخشی از مهاجرت به API گزارش‌دهی جدید (نسخه ۱) تغییر دهید.

مهاجرت پایه

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"

توجه داشته باشید که با نسخه ۱، همچنان می‌توانید انواع گزارش‌های خاص را به نقاط انتهایی خاص ارسال کنید. اما می‌توانید فقط یک 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)
• مشخصات: API گزارش‌دهی قدیمی (نسخه ۰)
• مشخصات: API گزارش‌دهی جدید (نسخه ۱)

با تشکر فراوان از ایان کللند، ایجی کیتامورا و میلیکا میهاجلیا برای نقدها و پیشنهادهایشان در مورد این مقاله.