پایش برنامه وب با Reporting API

از Reporting API برای نظارت بر نقض‌های امنیتی، فراخوانی‌های API منسوخ‌شده، و غیره استفاده کنید.

Maud Nalpas

برخی‌از خطاها فقط در تولید رخ می‌دهند. این مشکلات را به‌صورت محلی یا درطول توسعه نخواهید دید زیرا کاربران واقعی، شبکه‌های واقعی، و دستگاه‌های واقعی بازی را تغییر می‌دهند. «میانای برنامه‌سازی کاربردی گزارش‌دهی» کمک می‌کند برخی‌از این خطاها را—مثل نقض‌های امنیتی یا فراخوانی‌های منسوخ‌شده و به‌زودی منسوخ‌شده میانای برنامه‌سازی کاربردی در سراسر سایتتان—شناسایی کنید و آن‌ها را به نقطه پایانی که مشخص کرده‌اید منتقل کنید.

این ویژگی به شما امکان می‌دهد آنچه را که می‌خواهید بااستفاده از سرایندهای HTTP پایش کنید اعلام کنید و توسط مرورگر اجرا می‌شود.

راه‌اندازی Reporting API به شما اطمینان می‌دهد که وقتی کاربران با این نوع خطاها مواجه می‌شوند، مطلع خواهید شد تا بتوانید آن‌ها را برطرف کنید.

این پست توضیح می‌دهد که این API چه کارهایی می‌تواند انجام دهد و چگونه از آن استفاده کنید. بیایید شروع کنیم!

نمای کلی

فرض کنید سایت شما، site.example، دارای Content-Security-Policy و Document-Policy است. نمی‌دانید این‌ها چه کاری انجام می‌دهند؟ اشکالی ندارد، همچنان می‌توانید این مثال را متوجه شوید.

تصمیم می‌گیرید سایتتان را پایش کنید تا بدانید چه زمانی این خط‌مشی‌ها نقض می‌شوند، اما همچنین می‌خواهید مراقب میاناهای برنامه‌سازی کاربردی منسوخ یا به‌زودی منسوخ‌شده‌ای باشید که پایگاه کد شما ممکن است از آن‌ها استفاده کند.

برای انجام این کار، سرصفحه Reporting-Endpoints را پیکربندی می‌کنید و این نام‌های نقطه پایانی را بااستفاده از دستور report-to در خط‌مشی‌هایتان درصورت نیاز نگاشت می‌کنید.

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

# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0; report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the `default` endpoint

اتفاق غیرمنتظره‌ای رخ می‌دهد و این خط‌مشی‌ها برای برخی‌از کاربران شما نقض می‌شود.

نمونه‌های نقض

index.html

<script src="script.js"></script>
<!-- CSP VIOLATION: Try to load a script that's forbidden as per the Content-Security-Policy -->
<script src="https://example.com/script.js"></script>

script.js، بارشده توسط index.html

// DOCUMENT-POLICY VIOLATION: Attempt to use document.write despite the document policy
try {
  document.write('<h1>hi</h1>');
} catch (e) {
  console.log(e);
}
// DEPRECATION: Call a deprecated API
const webkitStorageInfo = window.webkitStorageInfo;

مرورگر گزارش نقض CSP، گزارش نقض «خط‌مشی سند»، و گزارش «منسوخ شدن» را که این مشکلات را ثبت می‌کند تولید می‌کند.

با کمی تأخیر—حداکثر یک دقیقه—مرورگر سپس گزارش‌ها را به نقطه پایانی که برای این نوع نقض پیکربندی شده است ارسال می‌کند. گزارش‌ها خارج از باند توسط خود مرورگر ارسال می‌شوند (نه توسط سرور یا سایت شما).

نقطه(های) پایان این گزارش‌ها را دریافت می‌کند.

اکنون می‌توانید به گزارش‌های این نقطه‌های پایان دسترسی پیدا کنید و آنچه را که اشتباه بوده است پایش کنید. آماده‌اید عیب‌یابی مشکلی را که بر کاربران شما تأثیر می‌گذارد شروع کنید.

گزارش نمونه

{
  "age": 2,
  "body": {
    "blockedURL": "https://site2.example/script.js",
    "disposition": "enforce",
    "documentURL": "https://site.example",
    "effectiveDirective": "script-src-elem",
    "originalPolicy": "script-src 'self'; object-src 'none'; report-to main-endpoint;",
    "referrer": "https://site.example",
    "sample": "",
    "statusCode": 200
  },
  "type": "csp-violation",
  "url": "https://site.example",
  "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
}

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

‫Reporting API را می‌توان به‌گونه‌ای پیکربندی کرد که به شما کمک کند انواع مختلفی از هشدارها یا مشکلات جالب را که در سراسر سایت شما اتفاق می‌افتد نظارت کنید:

گزارش‌ها

مرورگر گزارش‌ها را به نقطه پایانی‌ای که پیکربندی کرده‌اید ارسال می‌کند. درخواست‌هایی ارسال می‌کند که به این شکل است:

POST
Content-Type: application/reports+json

بار این درخواست‌ها فهرستی از گزارش‌ها است.

فهرست نمونه گزارش‌ها

[
  {
    "age": 420,
    "body": {
      "columnNumber": 12,
      "disposition": "enforce",
      "lineNumber": 11,
      "message": "Document policy violation: document-write is not allowed in this document.",
      "policyId": "document-write",
      "sourceFile": "https://site.example/script.js"
    },
    "type": "document-policy-violation",
    "url": "https://site.example/",
    "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
  },
  {
    "age": 510,
    "body": {
      "blockedURL": "https://site.example/img.jpg",
      "destination": "image",
      "disposition": "enforce",
      "type": "corp"
    },
    "type": "coep",
    "url": "https://dummy.example/",
    "user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"
  }
]

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

گزارش‌های دارای اعتبارنامه

پایانه‌های گزارش‌دهی که هم‌مبدأ با صفحه‌ای هستند که گزارش را تولید می‌کند، اطلاعات کاربری (کوکی‌ها) را در درخواست‌های حاوی گزارش دریافت می‌کنند.

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

مرورگر چه زمانی و چگونه گزارش‌ها را ارسال می‌کند؟

گزارش‌ها به‌صورت خارج از باند از سایت شما ارسال می‌شوند: مرورگر کنترل می‌کند که چه زمانی به نقطه(های) پایانی پیکربندی‌شده ارسال شوند. همچنین هیچ راهی برای کنترل زمان ارسال گزارش‌ها توسط مرورگر وجود ندارد؛ مرورگر گزارش‌ها را ضبط، صف‌بندی، و به‌طور خودکار در زمان مناسب ارسال می‌کند.

این یعنی هنگام استفاده از Reporting API، نگرانی چندانی درباره عملکرد وجود ندارد.

گزارش‌ها با تأخیر ارسال می‌شوند—تا یک دقیقه—تا احتمال ارسال گزارش‌ها به‌صورت دسته‌ای افزایش یابد. این کار باعث صرفه‌جویی در پهنای باند می‌شود تا به اتصال شبکه کاربر احترام گذاشته شود، که به‌ویژه در تلفن همراه مهم است. اگر مرورگر مشغول پردازش کار با اولویت بالاتر باشد، یا اگر کاربر در آن زمان در شبکه‌ای کند یا شلوغ باشد، مرورگر می‌تواند تحویل را به‌تأخیر بیندازد.

مشکلات طرف سوم و طرف اول

گزارش‌هایی که به‌دلیل نقض یا منسوخ شدن در صفحه شما ایجاد می‌شوند به نقطه(های) پایانی که پیکربندی کرده‌اید ارسال خواهند شد. این شامل نقض‌های انجام‌شده توسط دستورات شخص ثالث درحال اجرا در صفحه‌تان می‌شود.

موارد نقض یا منسوخ شدن که در iframe میان‌مبدئی جاسازی‌شده در صفحه شما اتفاق افتاده است به نقطه(های) پایانی شما گزارش نخواهد شد (حداقل به‌طور پیش‌فرض). یک iframe می‌تواند گزارش‌دهی خود را راه‌اندازی کند و حتی به سرویس گزارش‌دهی سایت شما—یعنی سرویس گزارش‌دهی طرف اول—گزارش دهد؛ اما این به سایت قاب‌بندی‌شده بستگی دارد. همچنین توجه داشته باشید که اکثر گزارش‌ها تنها درصورتی تولید می‌شوند که خط‌مشی صفحه‌ای نقض شود و خط‌مشی‌های صفحه شما و خط‌مشی‌های iframe متفاوت هستند.

نمونه با موارد منسوخ‌شده

پشتیبانی مرورگر

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

این جدول فقط پشتیبانی از report-to را با سرصفحه جدید Reporting-Endpoints خلاصه می‌کند. اگر می‌خواهید به Reporting-Endpoints انتقال دهید، نکات انتقال گزارش CSP را بخوانید.

استفاده از Reporting API

تصمیم بگیرید گزارش‌ها به کجا ارسال شود

دو گزینه دارید:

• گزارش‌ها را به سرویس جمع‌آوری گزارش موجود ارسال کنید.
• گزارش‌ها را به جمع‌آورنده گزارش‌هایی که خودتان ساخته‌اید و اداره می‌کنید ارسال کنید.

گزینه ۱: استفاده از سرویس جمع‌آوری گزارش موجود

برخی‌از نمونه‌های سرویس‌های جمع‌آوری‌کننده گزارش عبارت‌اند از:

• report-uri
• uriports
• HeaderHawk
• Sentry

اگر راه‌حل‌های دیگری می‌شناسید، مشکلی را باز کنید تا به ما اطلاع دهید و ما این پست را به‌روزرسانی خواهیم کرد!

علاوه‌بر قیمت‌گذاری، هنگام انتخاب جمع‌آوری‌کننده گزارش، نکات زیر را درنظر بگیرید: 🧐

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

گزینه ۲: جمع‌آوری‌کننده گزارش خودتان را بسازید و اجرا کنید

ساختن سرور خودتان که گزارش‌ها را دریافت کند کار ساده‌ای نیست. برای شروع، می‌توانید از کد تکراری سبک ما انشعاب بگیرید. این برنامه با Express ساخته شده است و می‌تواند گزارش‌ها را دریافت و نمایش دهد.

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

• درخواست‌های POST با Content-Type از application/reports+json را بررسی کنید تا درخواست‌های گزارش ارسالی از مرورگر به نقطه پایانتان را تشخیص دهید.
• اگر نقطه پایانی شما در مبدأ متفاوتی از سایتتان قرار دارد، مطمئن شوید که از درخواست‌های پیش‌پرواز CORS پشتیبانی می‌کند.

گزینه ۳: ترکیب گزینه ۱ و ۲

ممکن است بخواهید ارائه‌دهنده خاصی را برای رسیدگی به برخی‌از انواع گزارش‌ها انتخاب کنید، اما برای موارد دیگر از راه‌حل داخلی استفاده کنید.

در این حالت، چند نقطه پایانی را به‌صورت زیر تنظیم کنید:

Reporting-Endpoints: endpoint-1="https://reports-collector.example", endpoint-2="https://my-custom-endpoint.example"

پیکربندی سرایند Reporting-Endpoints

سرایند پاسخ Reporting-Endpoints را تنظیم کنید. مقدار آن باید یک یا چند جفت کلید-مقدار جداشده با کاما باشد:

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

اگر از Reporting API قدیمی به Reporting API جدید مهاجرت می‌کنید، ممکن است منطقی باشد که هر دو Reporting-Endpoints و Report-To را تنظیم کنید. جزئیات را در راهنمای انتقال ببینید. به‌ویژه، اگر از گزارش‌دهی برای نقض‌های Content-Security-Policy فقط بااستفاده از دستورالعمل report-uri استفاده می‌کنید، مراحل انتقال برای گزارش‌دهی CSP را بررسی کنید.

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

کلیدها (نام‌های نقطه پایان)

هر کلید می‌تواند نامی به انتخاب شما باشد، مثلاً main-endpoint یا endpoint-1. می‌توانید تصمیم بگیرید که نقطه‌های پایانی نام‌گذاری‌شده مختلفی را برای انواع مختلف گزارش تنظیم کنید—برای مثال، my-coop-endpoint، my-csp-endpoint. با این کار، می‌توانید گزارش‌ها را بسته به نوعشان به نقطه‌های پایانی مختلف هدایت کنید.

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

اگر سرصفحه Reporting-Endpoints هیچ نقطه پایانی default تعریف نکند، گزارش‌های این نوع ارسال نخواهند شد (اگرچه تولید خواهند شد).

مقادیر (نشانی‌های وب)

هر مقدار نشانی وب انتخابی شما است که گزارش‌ها به آن ارسال خواهد شد. نشانی وبی که باید در اینجا تنظیم شود به آنچه در «مرحله ۱» تصمیم گرفته‌اید بستگی دارد.

نشانی وب نقطه پایان:

• باید با خط مورب (/) شروع شود. مسیرهای نسبی پشتیبانی نمی‌شوند.
• می‌تواند بین مبدأها باشد؛ اما در این حالت اعتبارنامه‌ها همراه با گزارش‌ها ارسال نمی‌شوند.

مثال‌ها

Reporting-Endpoints: my-coop-endpoint="https://reports.example/coop", my-csp-endpoint="https://reports.example/csp", default="https://reports.example/default"

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

کجا سرایند را تنظیم کنم؟

در Reporting API جدید (که در این پست پوشش داده شده است)، گزارش‌ها به اسناد محدود می‌شوند. این یعنی برای یک مبدأ معین، سندهای مختلف، مثل site.example/page1 و site.example/page2، می‌توانند گزارش‌ها را به نقطه‌های پایانی مختلف ارسال کنند.

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

در اینجا مثالی در «اکسپرس» آورده شده است:

const REPORTING_ENDPOINT_BASE = 'https://report.example';
const REPORTING_ENDPOINT_MAIN = `${REPORTING_ENDPOINT_BASE}/main`;
const REPORTING_ENDPOINT_DEFAULT = `${REPORTING_ENDPOINT_BASE}/default`;

app.use(function (request, response, next) {
  // Set up the Reporting API
  response.set(
    'Reporting-Endpoints',
    `main-endpoint="${REPORTING_ENDPOINT_MAIN}", default="${REPORTING_ENDPOINT_DEFAULT}"`,
  );
  next();
});

ویرایش خط‌مشی‌ها

اکنون که سرایند Reporting-Endpoints پیکربندی شده است، یک دستورالعمل report-to به هر سرایند خط‌مشی که می‌خواهید گزارش‌های نقض را برای آن دریافت کنید اضافه کنید. مقدار report-to باید یکی از نقاط پایانی نام‌گذاری‌شده‌ای باشد که پیکربندی کرده‌اید.

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

‫report-to برای گزارش‌های منسوخ شدن، مداخله، و خرابی لازم نیست. این گزارش‌ها به هیچ خط‌مشی‌ای محدود نیستند. این گزارش‌ها تا زمانی تولید می‌شوند که نقطه پایانی default راه‌اندازی شده باشد و به این نقطه پایانی default ارسال شوند.

مثال

# Content-Security-Policy violations and Document-Policy violations
# will be sent to main-endpoint
Content-Security-Policy: script-src 'self'; object-src 'none'; report-to main-endpoint;
Document-Policy: document-write=?0;report-to=main-endpoint;
# Deprecation reports don't need an explicit endpoint because
# these reports are always sent to the default endpoint

اشکال‌زدایی راه‌اندازی گزارش‌دهی

تولید عمدی گزارش‌ها

هنگام راه‌اندازی Reporting API، احتمالاً باید به‌طور عمدی خط‌مشی‌های خود را نقض کنید تا بررسی کنید که آیا گزارش‌ها طبق انتظار تولید و ارسال می‌شوند یا نه.

در وقت صرفه‌جویی کنید

گزارش‌ها ممکن است با تأخیر—حدود یک دقیقه—ارسال شوند که در زمان اشکال‌زدایی، زمان طولانی محسوب می‌شود. 😴 خوشبختانه، هنگام اشکال‌زدایی در Chrome، می‌توانید از پرچم --short-reporting-delay استفاده کنید تا گزارش‌ها را به‌محض تولید شدن دریافت کنید.

این فرمان را در پایانه خود اجرا کنید تا این پرچم روشن شود:

YOUR_PATH/TO/EXECUTABLE/Chrome --short-reporting-delay

استفاده از DevTools

در Chrome، از DevTools برای دیدن گزارش‌هایی که ارسال شده‌اند یا ارسال خواهند شد استفاده کنید.

از اکتبر ۲۰۲۱، این ویژگی آزمایشی است. برای استفاده از آن، این مراحل را دنبال کنید:

1. از Chrome نسخه ۹۶ و جدیدتر استفاده کنید (با تایپ کردن chrome://version در مرورگرتان بررسی کنید)
2. chrome://flags/#enable-experimental-web-platform-features را در نوار نشانی Chrome تایپ یا جای‌گذاری کنید.
3. روی فعال کلیک کنید.
4. مرورگر را بازراه‌اندازی کنید.
5. ‫Chrome DevTools را باز کنید.
6. در «ابزارهای توسعه‌دهندگان Chrome»، «تنظیمات» را باز کنید. در بخش «آزمایش‌ها»، روی فعال کردن پانل Reporting API در پانل «برنامه» کلیک کنید.
7. DevTools را مجدد بار کنید.
8. صفحه را مجدد بار کنید. گزارش‌های تولیدشده توسط صفحه‌ای که DevTools در آن باز است، در پانل برنامه Chrome DevTools، در بخش Reporting API فهرست خواهد شد.

وضعیت گزارش

ستون وضعیت به شما می‌گوید که آیا گزارشی باموفقیت ارسال شده است یا خیر.

گزارش‌ها پس‌از مدتی برداشته می‌شوند، چه باموفقیت ارسال شده باشند چه نشده باشند.

عیب‌یابی

آیا گزارش‌ها طبق انتظار تولید نمی‌شوند یا به نقطه پایانی شما ارسال نمی‌شوند؟ در اینجا چند نکته برای عیب‌یابی این مشکل ارائه شده است.

گزارش‌ها تولید نمی‌شوند

گزارش‌هایی که در DevTools نشان داده می‌شود به‌درستی تولید شده است. اگر گزارشی که انتظار دارید در این فهرست نشان داده نمی‌شود:

• report-to را در خط‌مشی‌هایتان بررسی کنید. اگر این مورد پیکربندی اشتباهی داشته باشد، گزارشی تولید نخواهد شد. برای رفع این مشکل، به ویرایش خط‌مشی‌ها بروید. روش دیگری برای عیب‌یابی این مشکل این است که کنسول «ابزارهای توسعه‌دهندگان» در Chrome را بررسی کنید: اگر خطایی در کنسول برای نقضی که انتظار داشتید ظاهر شد، این یعنی خط‌مشی شما احتمالاً به‌درستی پیکربندی شده است.
• به‌خاطر داشته باشید که فقط گزارش‌هایی که برای سندی که «ابزارهای توسعه‌دهندگان» در آن باز است در این فهرست نشان داده می‌شود. یک مثال: اگر سایت شما site1.example یک iframe site2.example را جاسازی کند که خط‌مشی را نقض می‌کند و بنابراین گزارشی تولید می‌کند، این گزارش فقط درصورتی در DevTools نشان داده می‌شود که iframe را در پنجره خودش باز کنید و DevTools را برای آن پنجره باز کنید.

گزارش‌ها تولید می‌شوند اما ارسال یا دریافت نمی‌شوند

اگر بتوانید گزارشی را در DevTools ببینید، اما نقطه پایانی شما آن را دریافت نکند، چه اتفاقی می‌افتد؟

• حتماً از تأخیرهای کوتاه استفاده کنید. شاید دلیل اینکه نمی‌توانید گزارشی را ببینید این است که هنوز ارسال نشده است!

• پیکربندی سرصفحه Reporting-Endpoints را بررسی کنید. اگر مشکلی وجود داشته باشد، گزارشی که به‌درستی تولید شده است ارسال نخواهد شد. در DevTools، وضعیت گزارش Queued باقی خواهد ماند (ممکن است به Pending بپرد و سپس وقتی تلاش برای ارسال انجام می‌شود، به‌سرعت به Queued برگردد) در این مورد. برخی‌از اشتباهات رایج که ممکن است باعث این مشکل شود:

• نقطه پایانی دردست استفاده است ولی پیکربندی نشده است. مثال:

 Document-Policy: document-write=?0;report-to=endpoint-1;
 Reporting-Endpoints: default="https://reports.example/default"

• نقطه پایان default وجود ندارد. برخی‌از انواع گزارش‌ها، مانند گزارش‌های مداخله و منسوخ شدن، فقط به نقطه پایانی به‌نام default ارسال خواهد شد. در پیکربندی سرصفحه Reporting-Endpoints بیشتر بخوانید.

• به‌دنبال مشکلات در نحو سرصفحه‌های خط‌مشی خود باشید، مانند نقل‌قول‌های جاافتاده. دیدن جزئیات.

• بررسی کنید که نقطه پایانی‌تان بتواند درخواست‌های ورودی را مدیریت کند.

  • مطمئن شوید که نقطه پایانی شما از درخواست‌های پیش‌پرواز CORS پشتیبانی می‌کند. اگر این کار را انجام ندهد، نمی‌تواند گزارش دریافت کند.

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

  curl --header "Content-Type: application/reports+json" \
    --request POST \
    --data '[{"age":420,"body":{"columnNumber":12,"disposition":"enforce","lineNumber":11,"message":"Document policy violation: document-write is not allowed in this document.","policyId":"document-write","sourceFile":"https://dummy.example/script.js"},"type":"document-policy-violation","url":"https://dummy.example/","user_agent":"xxx"},{"age":510,"body":{"blockedURL":"https://dummy.example/img.jpg","destination":"image","disposition":"enforce","type":"corp"},"type":"coep","url":"https://dummy.example/","user_agent":"xxx"}]' \
    YOUR_ENDPOINT
  

  نقطه پایانی شما باید با کد موفقیت (200 یا کد پاسخ موفقیت‌آمیز دیگری 2xx) پاسخ دهد. اگر این کار را نکند، مشکلی در پیکربندی آن وجود دارد.

سازوکارهای گزارش‌دهی مرتبط

فقط گزارش‌دهی

-Report-Only سرصفحه خط‌مشی و Reporting-Endpoints باهم کار می‌کنند.

وقتی این خط‌مشی‌ها نقض شود، نقاط پایانی پیکربندی‌شده در Reporting-Endpoints و مشخص‌شده در فیلد report-to Content-Security-Policy، Cross-Origin-Embedder-Policy و Cross-Origin-Opener-Policy گزارش دریافت خواهند کرد.

نقاط پایانی پیکربندی‌شده در Reporting-Endpoints را می‌توان در فیلد report-to Content-Security-Policy-Report-Only، Cross-Origin-Embedder-Policy-Report-Only و Cross-Origin-Opener-Policy-Report-Only نیز مشخص کرد. همچنین، درصورت نقض این خط‌مشی‌ها، گزارش دریافت خواهند کرد.

اگرچه در هر دو مورد گزارش ارسال می‌شود، اما سرایندهای -Report-Only خط‌مشی‌ها را اجرا نمی‌کنند: هیچ‌چیز خراب نمی‌شود یا واقعاً مسدود نمی‌شود، اما گزارش‌هایی از آنچه می‌توانست خراب شود یا مسدود شود دریافت خواهید کرد.

ReportingObserver

ReportingObserver JavaScript API می‌تواند به شما کمک کند هشدارهای سمت کارخواه را مشاهده کنید.

ReportingObserver و سرصفحه Reporting-Endpoints گزارش‌هایی تولید می‌کنند که یکسان به‌نظر می‌رسند، اما موارد استفاده کمی متفاوتی را فعال می‌کنند.

در شرایط زیر از ReportingObserver استفاده کنید:

• فقط می‌خواهید منسوخ شدن‌ها یا مداخلات مرورگر را پایش کنید. ReportingObserver سطوح هشدارهای سمت مشتری مانند منسوخ شدن و مداخلات مرورگر را نشان می‌دهد، اما برخلاف Reporting-Endpoints، انواع دیگر گزارش‌ها مانند نقض‌های CSP یا COOP/COEP را ضبط نمی‌کند.
• باید به این نقض‌ها به‌صورت هم‌زمان واکنش نشان دهید. ReportingObserver امکان پیوست کردن فراخوانی برگشتی به رویداد نقض را فراهم می‌کند.
• می‌خواهید اطلاعات بیشتری را به گزارش پیوست کنید تا به اشکال‌زدایی کمک کنید، بااستفاده از فراخوانی سفارشی.

تفاوت دیگر این است که ReportingObserver فقط در سمت کارخواه پیکربندی می‌شود: حتی اگر کنترلی بر سرصفحه‌های سمت سرور نداشته باشید و نتوانید Reporting-Endpoints را تنظیم کنید، می‌توانید از آن استفاده کنید.

مطالعه بیشتر

• راهنمای انتقال از Reporting API v0 به v1
• ReportingObserver
• مشخصات: Reporting API قدیمی (نسخه ۰)
• مشخصات: Reporting API جدید (نسخه ۱)

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