برنامه وب خود را با گزارش API نظارت کنید

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

Maud Nalpas

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

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

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

این پست به بررسی قابلیت‌های این API و نحوه‌ی استفاده از آن می‌پردازد. بیایید شروع کنیم!

نمای کلی

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

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

برای انجام این کار، شما یک هدر 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، یک گزارش نقض Document-Policy و یک گزارش Deprecation ایجاد می‌کند که این مشکلات را ثبت می‌کند.

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

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

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

گزارش نمونه

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

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

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 می‌تواند گزارش خود را تنظیم کند و حتی به سرویس گزارش‌دهی سایت شما - یعنی سرویس شخص اول - گزارش دهد؛ اما این به سایت framed بستگی دارد. همچنین توجه داشته باشید که اکثر گزارش‌ها فقط در صورتی ایجاد می‌شوند که خط‌مشی یک صفحه نقض شود و خط‌مشی‌های صفحه شما و خط‌مشی‌های iframe متفاوت هستند.

مثال با منسوخات

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

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

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

استفاده از API گزارش‌دهی

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

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

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

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

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

• گزارش-uri
• بنادر

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

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

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

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

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

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

• درخواست‌های 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"

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

مقادیر (URLها)

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

یک آدرس اینترنتی (URL) نقطه پایانی:

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

مثال‌ها

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

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

هدر رو کجا باید تنظیم کرد؟

در 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 باید یکی از نقاط پایانی نامگذاری شده‌ای باشد که پیکربندی کرده‌اید.

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

برای گزارش‌های deprecation ، intervention و crash نیازی به 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

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

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

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

در زمان صرفه‌جویی کنید

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

برای فعال کردن این پرچم، این دستور را در ترمینال خود اجرا کنید:

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

از ابزارهای توسعه (DevTools) استفاده کنید

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

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

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

گزارش وضعیت

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

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

عیب‌یابی

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

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

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

• در سیاست‌های خود، report-to بررسی کنید. اگر این مورد به اشتباه پیکربندی شده باشد، گزارشی ایجاد نمی‌شود. برای رفع این مشکل به بخش Edit your policies بروید. یک راه دیگر برای عیب‌یابی این مشکل، بررسی کنسول DevTools در کروم است: اگر خطایی در کنسول برای تخلفی که انتظار داشتید ظاهر شد، به این معنی است که احتمالاً سیاست شما به درستی پیکربندی شده است.
• به خاطر داشته باشید که فقط گزارش‌هایی که برای سندی که DevTools در آن باز است ایجاد شده‌اند، در این لیست نمایش داده می‌شوند. به عنوان مثال: اگر سایت شما 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

API جاوا اسکریپت ReportingObserver می‌تواند به شما در مشاهده هشدارهای سمت کلاینت کمک کند.

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

ReportingObserver استفاده کنید اگر:

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

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

مطالعه بیشتر

• راهنمای مهاجرت از Reporting API نسخه ۰ به نسخه ۱
• گزارشگر ناظر
• مشخصات: API گزارش‌دهی قدیمی (نسخه ۰)
• مشخصات: API گزارش‌دهی جدید (نسخه ۱)

تصویر قهرمان اثر Nine Koepfer / @enka80 در Unsplash ، ویرایش شده. با تشکر فراوان از Ian Clelland، Eiji Kitamura و Milica Mihajlija برای بررسی‌ها و پیشنهاداتشان در مورد این سند.