Reporting API

Konzepte und Verwendung

Es gibt mehrere verschiedene Funktionen und Probleme auf der Webplattform, die Informationen generieren, die für Webentwickler nützlich sind, wenn sie versuchen, Fehler zu beheben oder ihre Websites anderweitig zu verbessern. Solche Informationen können umfassen:

• Content Security Policy Verstöße.
• Permissions-Policy Verstöße.
• Integrity-Policy Verstöße.
• Nutzung veralteter Funktionen (wenn Sie etwas verwenden, das bald in Browsern nicht mehr funktioniert).
• Auftreten von Abstürzen.
• Auftreten von User-Agent-Eingriffen (wenn der Browser etwas blockiert, was Ihr Code tun möchte, weil es zum Beispiel als Sicherheitsrisiko eingestuft wird oder einfach nur nervt, wie automatisch wiedergebender Ton).

Der Zweck der Reporting-API ist es, einen konsistenten Mechanismus zur Verfügung zu stellen, mit dem solche Informationen den Entwicklern in Form von Berichten, die durch JavaScript-Objekte repräsentiert werden, zugänglich gemacht werden können. Es gibt mehrere Möglichkeiten, sie zu nutzen, die in den untenstehenden Abschnitten im Detail beschrieben werden.

Endpunkte für Reporting-Server

Für jeden eindeutigen Ursprung, für den Sie Berichte erhalten möchten, kann eine Reihe von "Endpunkten" angegeben werden, bei denen es sich um benannte URLs (oder Gruppen von URLs) handelt, von denen Berichte von einem User-Agent gesendet werden können. Ein Reporting-Server an diesen Endpunkten kann die Berichte sammeln, verarbeiten und nach Bedarf für Ihre Anwendung präsentieren.

Der Reporting-Endpoints HTTP-Header wird verwendet, um Details zu den verschiedenen Endpunkten anzugeben, die einem User-Agent zum Zurstellen von Berichten zur Verfügung stehen. Die report-to Direktive kann dann auf bestimmten HTTP-Antwort-Headern verwendet werden, um den spezifischen Endpunkt anzugeben, der für den zugehörigen Bericht verwendet wird. Zum Beispiel kann die CSP report-to Direktive auf den Content-Security-Policy oder Content-Security-Policy-Report-Only HTTP-Headern verwendet werden, um den Endpunkt anzugeben, an den CSP-Verletzungsberichte gesendet werden sollen.

Die Berichte selbst werden vom User-Agent bei einer POST-Operation mit einem Content-Type von application/reports+json an den Zielendpunkt gesendet. Sie sind Serialisierungen von Report-Objekten, wobei type den Berichtstyp angibt, url den Ursprung des Berichts und body eine Serialisierung der API-Schnittstelle enthält, die dem Berichtstyp entspricht. Beispielsweise haben CSP-Verletzungsberichte einen type von csp-violation und einen body, der eine Serialisierung eines CSPViolationReportBody-Objekts ist.

Berichte, die an Endpunkte gesendet werden, können unabhängig vom Betrieb der Websites, auf die sie sich beziehen, abgerufen werden, was nützlich ist - ein Absturz könnte zum Beispiel eine Website lahmlegen und alles zum Stillstand bringen, aber ein Bericht könnte immer noch beschafft werden, um dem Entwickler einige Hinweise darauf zu geben, warum es passiert ist.

Reporting-Observer

Berichte können auch über ReportingObserver-Objekte erhalten werden, die über JavaScript innerhalb der Website erstellt werden, auf der Sie Berichte erhalten möchten. Diese Methode ist nicht so ausfallsicher wie das Senden von Berichten an den Server, da jeder Seitenabsturz das Abrufen der Berichte verhindern könnte — aber es ist einfacher einzurichten und flexibler.

Ein ReportingObserver-Objekt wird mit dem ReportingObserver()-Konstruktor erstellt, der zwei Parameter erhält:

• Eine Callback-Funktion mit zwei Parametern - ein Array der im Beobachter-Berichtsqueue verfügbaren Berichte und eine Kopie desselben ReportingObserver-Objekts, mit dem die Beobachtung direkt aus der Callback-Funktion gesteuert werden kann. Die Callback-Funktion wird ausgeführt, wenn die Beobachtung beginnt.
• Ein Options-Wörterbuch, das es Ihnen ermöglicht, den zu sammelnden Berichtstyp anzugeben und ob Berichte, die vor der Erstellung des Beobachters generiert wurden, beobachtbar sein sollen (buffered: true).

Dem Beobachter stehen dann Methoden zur Verfügung, um die Berichterfassung zu starten (ReportingObserver.observe()), die derzeit im Berichtsqueue befindlichen Berichte abzurufen (ReportingObserver.takeRecords()) und den Beobachter zu trennen, sodass er keine Berichte mehr sammeln kann (ReportingObserver.disconnect()).

Berichtstypen

Berichte, die an Reporting-Endpunkte und Reporting-Observer gesendet werden, sind im Wesentlichen dieselben: Sie haben einen Herkunfts-url, einen type und einen body, der eine Instanz der Schnittstelle ist, die mit diesem Typ korrespondiert. Der einzige Unterschied ist, dass Serverberichte JSON-Serialisierungen der Objekte sind.

Die Zuordnung von Bericht-type zu body ist unten dargestellt.

Berichtserstellung über WebDriver

Der Reporting-API-Standard definiert auch eine Generate Test Report WebDriver-Erweiterung, die es ermöglicht, die Berichtserstellung während der Automatisierung zu simulieren. Berichte, die über WebDriver generiert werden, werden von allen registrierten ReportObserver-Objekten beobachtet, die auf der geladenen Website vorhanden sind. Dies ist noch nicht dokumentiert.

Schnittstellen

DeprecationReportBody

Enthält Details zu veralteten Webplattform-Funktionen, die von einer Website verwendet werden.

InterventionReportBody

Enthält Details zu einem Eingriffsbericht, der generiert wird, wenn eine von der Website gestellte Anfrage vom Browser abgelehnt wurde; z.B. aus Sicherheitsgründen.

Report

Ein Objekt, das einen einzelnen Bericht darstellt.

ReportingObserver

Ein Objekt, das verwendet werden kann, um Berichte zu sammeln und darauf zuzugreifen, während sie generiert werden.

Verwandte Schnittstellen

Diese Schnittstellen werden als Teil der HTTP Content Security Policy (CSP)-Spezifikationen definiert:

CSPViolationReportBody

Enthält Details zu einer CSP-Verletzung.

SecurityPolicyViolationEvent

Stellt das Ereignisobjekt eines securitypolicyviolation-Ereignisses dar, das auf einem Element, Dokument oder Arbeiter ausgelöst wird, wenn seine CSP verletzt wird.

Diese Schnittstelle wird als Teil der Subresource Integrity-Spezifikation definiert:

IntegrityViolationReportBody

Enthält Informationen über eine Ressource, die blockiert wurde, weil sie nicht die Subresource-Integrity-Garantien erfüllt hat, die durch ihre Integrity-Policy-Richtlinie erforderlich sind, oder die für Berichte-Only-Richtlinien, die mit Integrity-Policy-Report-Only gesetzt werden, blockiert werden würde.

Verwandte HTTP-Header

Diese HTTP-Antwortheader definieren die Endpunkte, an die Berichte gesendet werden.

Reporting-Endpoints

Setzt den Namen und die URL von Reporting-Endpunkten. Diese Endpunkte können in der report-to-Direktive verwendet werden, die mit mehreren HTTP-Headern, einschließlich Content-Security-Policy, verwendet werden kann.

Report-To Veraltet

Nicht mehr Teil der Reporting-API, aber weiterhin von einigen Browsern unterstützt. Dies setzt den Namen und die URL von Reporting-Endpunktgruppen, die mit mehreren HTTP-Headern, insbesondere für Network Error Logging, die noch nicht aktualisiert wurde, um Reporting-Endpoints zu unterstützen, verwendet werden können. Andere Reporting-API-Berichte sollten stattdessen Reporting-Endpoints für eine bessere zukünftige Unterstützung verwenden.

Berichtsendpunkte können für die folgenden Berichte mit der report-to-Direktive auf den entsprechenden Headern festgelegt werden:

CSP-Verstöße

Content-Security-Policy oder Content-Security-Policy-Report-Only.

Berichtsendpunkte können für die folgenden Berichte mit dem endpoints-Feld in einem strukturierten Wörterbuch auf den entsprechenden Headern festgelegt werden:

Integrity-Policy-Verstöße

Integrity-Policy oder Integrity-Policy-Report-Only.

Beispiele

Berichterstattung über veraltete Funktionen

In unserem Beispiel deprecation_report.html erstellen wir einen einfachen Reporting-Observer, um die Verwendung veralteter Funktionen auf unserer Webseite zu beobachten:

const options = {
  types: ["deprecation"],
  buffered: true,
};

const observer = new ReportingObserver((reports, observer) => {
  reportBtn.onclick = () => displayReports(reports);
}, options);

Wir weisen ihn dann an, mit ReportingObserver.observe() Berichte zu beobachten; dies teilt dem Beobachter mit, mit der Sammlung von Berichten in seiner Berichtsqueue zu beginnen und die im Konstruktor angegebene Callback-Funktion auszuführen:

observer.observe();

Später im Beispiel verwenden wir absichtlich die veraltete Version von MediaDevices.getUserMedia():

if (navigator.mozGetUserMedia) {
  navigator.mozGetUserMedia(constraints, success, failure);
} else {
  navigator.getUserMedia(constraints, success, failure);
}

Dies führt zur Erstellung eines Veraltungsberichts; aufgrund des Ereignishandlers, den wir innerhalb des ReportingObserver()-Konstruktors eingerichtet haben, können wir nun auf die Schaltfläche klicken, um die Berichtdetails anzuzeigen.

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Content Security Policy
• Permissions-Policy