مهاجرت به Reporting API v1

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

Maud Nalpas

گزارش 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

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

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

چیزی که بدون تغییر باقی می ماند

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

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

تمام تفاوت های بین v0 و v1

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

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

این به این دلیل است که گزارش‌ها با 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. مرحله 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 یکسان است.

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

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

3. مرحله 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

با این حال، فقط تعداد کمی از مرورگرها report-to پشتیبانی می کنند . بنابراین توصیه می‌شود report-uri در کنار رویکرد Reporting API ( Report-To یا بهتر، Reporting-Endpoints ) نگه دارید تا گزارش‌های نقض CSP را از چندین مرورگر دریافت کنید. در مرورگری که report-uri و report-to تشخیص می دهد، در صورت وجود report-to report-uri نادیده گرفته می شود. در مرورگری که فقط 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 (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 برای نظرات و پیشنهاداتشان در مورد این مقاله.