نسخه جدیدی از Reporting API در دسترس است. خصوصی تر است و به احتمال زیاد در مرورگرها پشتیبانی می شود.
گزارش API شما را در مورد خطاهایی که در سایت شما هنگام استفاده بازدیدکنندگان از آن رخ می دهد، آگاه می کند. این به شما امکان مشاهده مداخلات مرورگر، خرابی مرورگر، نقض خطمشی محتوا-امنیت، نقض COOP/COEP، هشدارهای منسوخ شدن و موارد دیگر را میدهد.
نسخه جدیدی از Reporting API در دسترس است. API جدید کمتر است و به احتمال زیاد در مرورگرها پشتیبانی می شود.
خلاصه
توسعه دهندگان سایت
اگر از قبل قابلیت گزارش دهی برای سایت خود دارید : با استفاده از هدر جدید ( Reporting-Endpoints
) به نسخه 1 مهاجرت کنید، اما هدر قدیمی را برای مدتی نگه دارید ( Report-To
). به مهاجرت مراجعه کنید: کد نمونه .
اگر همین الان در حال اضافه کردن عملکرد گزارش به سایت خود هستید : فقط از سربرگ جدید ( Reporting-Endpoints
) استفاده کنید.
⚠️ در هر دو مورد، مطمئن شوید که هدر Reporting-Endpoints
را روی همه پاسخ هایی که ممکن است گزارش ایجاد کنند، تنظیم کنید.
توسعه دهندگان خدمات گزارش
اگر یک سرویس نقطه پایانی را حفظ می کنید یا خدمات خود را اجرا می کنید، با مهاجرت شما یا توسعه دهندگان خارجی به Reporting API v1 (سرصفحه Reporting-Endpoints
) انتظار ترافیک بیشتری را داشته باشید.
برای جزئیات و کد نمونه به خواندن ادامه دهید!
ثبت خطای شبکه
مکانیزم جدیدی برای ثبت خطاهای شبکه ایجاد خواهد شد. پس از در دسترس قرار گرفتن، از Reporting API v0 به مکانیسم جدید تغییر دهید.
نسخه ی نمایشی و کد
- سایت آزمایشی: API گزارش جدید (v1)
- کد برای سایت دمو
تفاوت بین v0 و v1
چه چیزی در حال تغییر است
- سطح 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
- دامنه گزارش متفاوت است.
با v0، میتوانید نقاط پایانی گزارش را فقط برای برخی از پاسخها تنظیم کنید. سایر اسناد (صفحات) در آن مبدا به طور خودکار از این نقاط پایانی محیطی استفاده می کنند.
با v1، باید سرصفحه Reporting-Endpoints
را روی تمام پاسخ هایی که ممکن است گزارش ایجاد کنند، تنظیم کنید.
- هر دو API از یک نوع گزارش پشتیبانی میکنند، با یک استثنا: v1 از گزارشهای خطای شبکه پشتیبانی نمیکند. در مراحل مهاجرت بیشتر بخوانید.
- v0 در مرورگرها پشتیبانی نمی شود و نخواهد بود. v1 به احتمال زیاد در آینده در چندین مرورگر پشتیبانی می شود.
چیزی که بدون تغییر باقی می ماند
- قالب و ساختار گزارش ها بدون تغییر است.
- درخواست ارسال شده توسط مرورگر به نقطه پایانی یک درخواست
POST
ازContent-type
application/reports+json
باقی می ماند. - نگاشت نقاط پایانی خاص به انواع گزارش های خاص در هر دو نسخه v0 و v1 پشتیبانی می شود.
- نقش نقطه پایانی
default
بدون تغییر است. Reporting API v1 هیچ تاثیری بر
ReportingObserver
ندارد.ReportingObserver
همچنان به همه گزارش های قابل مشاهده دسترسی پیدا می کند و قالب آنها یکسان است.
تمام تفاوت های بین v0 و v1
API گزارش قدیمی (نسخه 0)Report-To سربرگ | API گزارش جدید (نسخه 1) هدر Reporting-Endpoints | |
---|---|---|
پشتیبانی از مرورگر | Chrome 69+ و Edge 69+. | Chrome 96+ و Edge 96+. فایرفاکس پشتیبانی می کند. سافاری مخالفتی ندارد. سیگنال های مرورگر را ببینید. |
نقاط پایانی | گزارشها را به هر یک از چندین گردآورنده گزارش ارسال میکند (چند URL تعریف شده در هر گروه نقطه پایانی). | گزارشها را به جمعآوران گزارش خاص ارسال میکند (فقط یک URL در هر نقطه پایانی تعریف شده است). |
سطح API | از هدر `Report-To` برای پیکربندی گروههای نقطه پایانی نامگذاری شده استفاده میکند. | از سرصفحه `Reporting-Endpoints` برای پیکربندی نقاط انتهایی نامگذاری شده استفاده میکند. |
انواع گزارشی که می توان از طریق این API ایجاد کرد |
| بدون تغییر، به جز گزارش خطای شبکه (NEL): این مورد در گزارش API جدید (v1) پشتیبانی نمیشود . |
دامنه گزارش | مبدا.Report-To یک سند روی سایر اسناد (صفحات) از آن مبدا تأثیر می گذارد. فیلد url گزارش همچنان در هر سند متفاوت است. | سند. هدر Reporting-Endpoints یک سند فقط روی آن سند تأثیر می گذارد. فیلد url گزارش همچنان در هر سند متفاوت است. |
گزارش جداسازی (بچینگ) | اسناد (صفحات) یا سایتها/منشأهای مختلف که گزارشی را تقریباً در یک زمان تولید میکنند و نقطه پایانی گزارش یکسانی دارند با هم جمع میشوند: آنها در یک پیام به نقطه پایانی گزارش ارسال میشوند. |
|
پشتیبانی از تعادل بار / اولویت ها | بله | خیر |
توسعه دهندگان نقطه پایانی: انتظار ترافیک بیشتری داشته باشید
اگر سرور خود را بهعنوان نقطه پایانی گزارشدهی راهاندازی کردهاید، یا اگر در حال توسعه یا نگهداری یک جمعآورنده گزارش بهعنوان یک سرویس هستید، انتظار ترافیک بیشتری به آن نقطه پایانی داشته باشید.
این به این دلیل است که گزارشها با Reporting API v1 مانند Reporting API v0 دستهبندی نمیشوند. بنابراین، با شروع مهاجرت توسعه دهندگان برنامه به Reporting API v1، تعداد گزارش ها مشابه باقی می ماند، اما حجم درخواست ها به سرور نقطه پایانی افزایش می یابد.
توسعه دهندگان برنامه: مهاجرت به Reporting-Endpoints
(v1)
چه کاری باید انجام دهید؟
استفاده از Reporting API جدید (v1) چندین مزیت دارد:
- سیگنالهای مرورگر مثبت هستند، به این معنی که برای نسخه 1 میتوان از بین مرورگرها پشتیبانی کرد (برخلاف نسخه 0 که فقط در کروم و اج پشتیبانی میشود).
- API لاغرتر است.
- Tooling حول API جدید Reporting (v1) در حال توسعه است.
با این حساب:
- اگر سایت شما قبلاً از Reporting API v0 با هدر
Report-To
استفاده میکند، به Reporting API v1 بروید ( مراحل انتقال را ببینید). اگر سایت شما قبلاً از عملکرد گزارش برای نقض سیاست محتوا-امنیت-استفاده میکند، مراحل انتقال خاص برای گزارش CSP را بررسی کنید. - اگر سایت شما قبلاً از Reporting API استفاده نمیکند و اکنون عملکرد گزارش را اضافه میکنید: از Reporting API جدید (v1) (هدر
Reporting-Endpoints
) استفاده کنید. یک استثنا برای این وجود دارد : اگر نیاز به استفاده از گزارش خطای شبکه دارید، ازReport-To
(v0) استفاده کنید. ثبت خطای شبکه در حال حاضر در Reporting API v1 پشتیبانی نمیشود. مکانیزم جدیدی برای ثبت خطاهای شبکه ایجاد خواهد شد⏤تا زمانی که در دسترس باشد، از Reporting API v0 استفاده کنید. اگر به ثبت خطاهای شبکه در کنار انواع دیگر گزارش نیاز دارید، ازReport-To
(v0) وReporting-Endpoints
(v1) استفاده کنید. v0 به شما گزارش خطای شبکه و v1 گزارش انواع دیگر را به شما می دهد.
مراحل مهاجرت
هدف شما در این مهاجرت این است که گزارش هایی را که قبلاً با v0 دریافت می کردید از دست ندهید .
مرحله 1 (اکنون انجام دهید) : از هر دو عنوان استفاده کنید:
Report-To
(v0) وReporting-Endpoints
(v1).با این، شما دریافت می کنید:
- گزارشهای مشتریان جدیدتر Chrome و Edge به لطف
Reporting-Endpoints
(v1). - گزارشهای مشتریان قدیمی Chrome و Edge به لطف
Report-To
(v0).
نمونههای مرورگری که از
Reporting-Endpoints
پشتیبانی میکنندReporting-Endpoints
استفاده میکنند و نمونههایی که از آن پشتیبانی نمیکنند بهReport-To
بازگشت میدهند. فرمت درخواست و گزارش برای v0 و v1 یکسان است.- گزارشهای مشتریان جدیدتر Chrome و Edge به لطف
مرحله 2 (اکنون انجام دهید): اطمینان حاصل کنید که هدر
Reporting-Endpoints
روی همه پاسخ هایی که ممکن است گزارش ایجاد کنند تنظیم شده باشد.با v0، میتوانید نقطههای پایانی گزارشدهی را فقط برای برخی از پاسخها تنظیم کنید، و سایر اسناد (صفحات) در آن مبدا از این نقطه پایانی «محیطی» استفاده کنند. با v1، به دلیل تفاوت در محدوده، باید سرصفحه
Reporting-Endpoints
روی همه پاسخ هایی که ممکن است گزارش ایجاد کنند، تنظیم کنید.مرحله 3 (زمان شروع): هنگامی که همه یا بیشتر کاربران شما به نصب های بعدی Chrome یا Edge (96 و بالاتر) به روز شدند،
Report-To
(v0) را حذف کنید و فقطReporting-Endpoints
نگه دارید.یک استثنا: اگر به گزارشهای ثبت خطای شبکه نیاز دارید،
Report-To
نگه دارید تا مکانیزم جدیدی برای ثبت خطاهای شبکه ایجاد شود.
نمونه کد را در کتاب آشپزی مهاجرت ببینید.
مراحل مهاجرت برای گزارش CSP
به دو روش میتوان گزارشهای نقض Content-Security-Policy را پیکربندی کرد:
- تنها با هدر CSP از طریق دستورالعمل
report-uri
. این از مرورگر گسترده ای در کروم، فایرفاکس، سافاری و اج پشتیبانی می کند. گزارشها باapplication/csp-report
نوع محتوا ارسال میشوند و فرمتی دارند که مختص CSP است. این گزارش ها "گزارش های سطح 2 CSP" نامیده می شوند و به گزارش API متکی نیستند . - با گزارش API، از طریق هدر
Report-To
(میراث) یاReporting-Endpoints
جدیدتر (v1). این فقط در Chrome و Edge پشتیبانی میشود. فرمت درخواستهای گزارش مانند سایر درخواستهای Reporting API و همان نوع محتواapplication/reports+json
است.
استفاده از رویکرد اول (فقط report-uri
) دیگر توصیه نمی شود و استفاده از رویکرد دوم مزایای کمی دارد. به طور خاص، به شما امکان میدهد از یک راه واحد برای تنظیم گزارش برای همه انواع گزارش و همچنین تنظیم یک نقطه پایانی عمومی استفاده کنید (زیرا همه درخواستهای گزارش ایجاد شده از طریق Reporting API⏤CSP و موارد دیگر⏤با فرمت یکسان application/reports+json
هستند. 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
(Firefox) پشتیبانی میکنند، ازreport-uri
استفاده میکنند و مرورگرهایی کهreport-to
(Chrome، Edge) نیز پشتیبانی میکنند،report-to
استفاده میکنند. برای مشخص کردن نقاط پایانی نامگذاری شدهای که درreport-to
استفاده میکنید، از هر دو سرصفحهReport-To
وReporting-Endpoints
استفاده کنید. این تضمین میکند که گزارشهایی را از مشتریان قدیمیتر و جدیدتر Chrome و Edge دریافت میکنید.مرحله 3 (زمان شروع): هنگامی که همه یا بیشتر کاربران شما به نصب های بعدی Chrome یا Edge (96 و بالاتر) به روز شدند،
Report-To
(v0) را حذف کنید و فقطReporting-Endpoints
نگه دارید.report-uri
نگه دارید تا همچنان گزارش هایی برای مرورگرهایی که فقط از آن پشتیبانی می کنند دریافت کنید.
نمونه کد این مراحل را در انتقال گزارش CSP ببینید.
مهاجرت: کد نمونه
نمای کلی
اگر از API گزارشدهی قدیمی (v0) برای دریافت گزارشهای نقض برای aa COOP (سرصفحه Cross-Origin-Opener-Policy
)، COEP ( Cross-Origin-Embedder-Policy
) یا خطمشی سند (سرصفحه Document-Policy
استفاده میکنید. ): با انتقال به Reporting API v1، نیازی به تغییر این سرصفحه های خط مشی ندارید. آنچه شما نیاز دارید این است که از هدر قدیمی Report-To
به سربرگ جدید Reporting-Endpoints
مهاجرت کنید.
اگر از API قدیمی Reporting (v0) برای دریافت گزارش تخلف برای یک CSP (سربرگ Content-Security-Policy
) استفاده می کنید، ممکن است لازم باشد Content-Security-Policy
خود را به عنوان بخشی از انتقال خود به API گزارش جدید تغییر دهید ( v1).
مهاجرت اولیه
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"
توجه داشته باشید که با v1، همچنان میتوانید انواع گزارشهای خاص را به نقاط پایانی خاص ارسال کنید. اما شما می توانید تنها یک 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: ...
در ادامه مطلب
- برنامه وب خود را با گزارش API (پست اصلی در گزارش API) نظارت کنید
- مشخصات: API گزارش قدیمی (v0)
- مشخصات: New Reporting API (v1)
تصویر قهرمان توسط Nine Koepfer / @enka80 در Unsplash ، ویرایش شده است. با تشکر فراوان از Ian Clelland، Eiji Kitamura و Milica Mihajlija برای نظرات و پیشنهاداتشان در مورد این مقاله.