Dostępna jest nowa wersja interfejsu API do raportowania. Zapewnia to większą prywatność i jest większa szansa na to, że będzie obsługiwany w różnych przeglądarkach.
Interfejs API do raportowania informuje o błędach, które pojawiają się w witrynie, gdy użytkownicy z niej korzystają. Informuje o interwencjach przeglądarek, awariach przeglądarki, naruszeniach zasad zabezpieczeń zawartości, naruszeń COOP/COEP, ostrzeżeniami o wycofaniu usługi i nie tylko.
Dostępna jest nowa wersja interfejsu API do raportowania. Nowy interfejs API jest udoskonalony i prawdopodobnie będzie obsługiwany w różnych przeglądarkach.
Podsumowanie
Deweloperzy witryn
Jeśli w swojej witrynie masz już funkcję raportowania: przejdź na wersję 1, używając nowego nagłówka (Reporting-Endpoints
), ale zachowaj starszy nagłówek przez pewien czas (Report-To
). Zobacz Migracja: przykładowy kod.
Jeśli dodajesz w witrynie funkcję raportowania od razu: używaj tylko nowego nagłówka (Reporting-Endpoints
).
⚠️ W obu przypadkach ustaw nagłówek Reporting-Endpoints
w przypadku wszystkich odpowiedzi, które mogą generować raporty.
Deweloperzy usług raportowania
Jeśli korzystasz z usługi punktu końcowego lub używasz własnej usługi, możesz spodziewać się większego ruchu w miarę przejścia przez Ciebie lub zewnętrznych deweloperów na interfejs Reporting API w wersji 1 (nagłówek Reporting-Endpoints
).
Czytaj dalej, aby poznać szczegóły i przykładowy kod.
Logowanie błędów sieciowych
Opracowany zostanie nowy mechanizm logowania błędów sieciowych. Gdy będzie on dostępny, przejdź z interfejsu Reporting API w wersji 0 na ten nowy mechanizm.
Demonstracja i kod
- Witryna demonstracyjna: nowy interfejs API do raportowania (wersja 1)
- Kod witryny demonstracyjnej
Różnice między wersjami v0 i v1
Co się zmienia
- Interfejs API jest inny.
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
- Zakres raportu jest inny.
W wersji 0 możesz ustawiać punkty końcowe raportowania tylko w przypadku niektórych odpowiedzi. Inne dokumenty (strony) z tego źródła będą automatycznie korzystać z tych punktów końcowych.
W wersji 1 musisz ustawiać nagłówek Reporting-Endpoints
we wszystkich odpowiedziach, które mogą generować raporty.
- Oba interfejsy API obsługują te same typy raportów z jednym wyjątkiem: wersja 1 nie obsługuje raportów o błędach sieci. Więcej informacji znajdziesz w sekcji Migracja.
- Wersja v0 nie jest i nie będzie obsługiwana w różnych przeglądarkach. Prawdopodobnie będzie ona w przyszłości obsługiwana w różnych przeglądarkach.
Co się nie zmieniło
- Format i struktura raportów nie uległy zmianie.
- Żądanie wysłane przez przeglądarkę do punktu końcowego pozostaje żądaniem
POST
Content-type
application/reports+json
. - Mapowanie niektórych punktów końcowych na określone typy raportów jest obsługiwane zarówno w wersji 0, jak i 1.
- Rola punktu końcowego
default
nie została zmieniona. Interfejs Reporting API w wersji 1 nie ma wpływu na środowisko
ReportingObserver
.ReportingObserver
nadal ma dostęp do wszystkich dostępnych raportów, a ich format jest identyczny.
Wszystkie różnice między wersjami v0 i v1
Starsza wersja interfejsu API do raportowania (v0) Nagłówek Report-To |
Nowy interfejs API do raportowania (v1)Reporting-Endpoints nagłówek |
|
---|---|---|
Obsługiwane przeglądarki | Chrome 69 i nowsze oraz Edge 69 i nowsze. | Chrome 96 i nowsze oraz Edge 96 i nowsze. Firefox obsługuje te aplikacje. Safari ich nie zgłasza. Zobacz sygnały z przeglądarki. |
Punkty końcowe | Wysyła raporty do dowolnego z wielu kolektorów raportów (dla każdej grupy punktów końcowych zdefiniowano wiele adresów URL). | Wysyła raporty do określonych kolektorów raportów (dla każdego punktu końcowego zdefiniowany jest tylko 1 adres URL). |
Interfejs API | Użycie nagłówka `Report-To` do konfigurowania nazwanych grup punktów końcowych. |
Używa nagłówka `Reporting-Endpoints` do konfigurowania nazwanych punktów końcowych. |
Typy raportów, które można generować za pomocą tego interfejsu API |
|
Bez zmian, z wyjątkiem funkcji rejestrowania błędów sieci (NEL): ta funkcja nie jest obsługiwana w nowym interfejsie Reporting API (v1). |
Zakres raportu | pochodzenia. Nagłówek Report-To dokumentu ma wpływ na inne dokumenty (strony) z tego źródła.
Pole url raportu różni się w zależności od dokumentu.
|
Dokument. Nagłówek Reporting-Endpoints dokumentu ma wpływ tylko na ten dokument.
Pole url raportu różni się w zależności od dokumentu.
|
Izolacja raportu (zbiorcza) | Różne dokumenty (strony) lub witryny i źródła, które generują raport mniej więcej w tym samym czasie i mają ten sam punkt końcowy raportowania, będą grupowane w grupę i będą wysyłane w tej samej wiadomości do punktu końcowego raportowania. |
|
Obsługa równoważenia obciążenia / priorytetów | Tak | Nie |
Deweloperzy punktów końcowych: spodziewaj się większego ruchu
Jeśli masz skonfigurowany własny serwer jako punkt końcowy raportowania albo tworzysz lub utrzymujesz kolektor raportów jako usługę, spodziewaj się większego ruchu do tego punktu końcowego.
Dzieje się tak, ponieważ raporty nie są grupowane w wersji 1 interfejsu Reporting API (w wersji 1), jak w przypadku interfejsu Reporting API v0. Dlatego gdy deweloperzy aplikacji zaczną przechodzić na interfejs Reporting API w wersji 1, liczba raportów pozostanie podobna, ale liczba żądań do serwera punktu końcowego będzie się zwiększać.
Programiści aplikacji: Migracja do Reporting-Endpoints
(wersja 1)
Co musisz zrobić?
Korzystanie z nowego interfejsu Reporting API (v1) ma kilka zalet ✅:
- Sygnały z przeglądarki są pozytywne, co oznacza, że wersja 1 będzie obsługiwać wiele przeglądarek (w przeciwieństwie do wersji 0, która jest obsługiwana tylko w Chrome i Edge).
- Interfejs API jest udoskonalony.
- Pracujemy nad narzędziami związanymi z nowym interfejsem Reporting API (v1).
Pamiętaj o tym:
- Jeśli Twoja witryna korzysta już z interfejsu Reporting API w wersji 0 z nagłówkiem
Report-To
, przejdź na interfejs Reporting API w wersji 1 (patrz instrukcje migracji). Jeśli Twoja witryna korzysta już z funkcji zgłaszania naruszeń zasad bezpieczeństwa treści, zapoznaj się z instrukcją migracji raportów CSP. - Jeśli Twoja witryna nie korzysta jeszcze z interfejsu API do raportowania i dodajesz funkcję raportowania, użyj nowego interfejsu Reporting API (v1) (nagłówka
Reporting-Endpoints
). Jest jeden wyjątek: jeśli chcesz korzystać z logowania błędów sieci, użyjReport-To
(v0). Logowanie błędów sieciowych nie jest obecnie obsługiwane w interfejsie Reporting API w wersji 1. Opracujemy nowy mechanizm logowania błędów sieciowych ⏤ Dopóki nie będzie dostępny, używaj interfejsu Reporting API w wersji 0. Jeśli logowanie błędów sieci potrzebujesz razem z innymi typami raportów, użyj zarównoReport-To
(v0), jak iReporting-Endpoints
(1). Wersja 0 umożliwia rejestrowanie błędów sieciowych, a wersja 1 – raporty wszystkich innych typów.
Etapy migracji
W ramach tej migracji chcesz nie utracić raportów, które były dostępne w wersji 0.
Krok 1 (wykonaj teraz): użyj obu nagłówków:
Report-To
(v0) iReporting-Endpoints
(v1).Dzięki temu zyskujesz:
- Raporty generowane przez nowsze klienty Chrome i Edge za pomocą usługi
Reporting-Endpoints
(v1). - Raporty generowane przez starsze klienty Chrome i Edge za pomocą
Report-To
(v0).
Instancje przeglądarki, które obsługują
Reporting-Endpoints
, będą używaćReporting-Endpoints
, a instancje, które nie korzystają z metodyReport-To
. Format żądania i raportu jest taki sam w wersjach v0 i 1.- Raporty generowane przez nowsze klienty Chrome i Edge za pomocą usługi
Krok 2 (wykonaj teraz): upewnij się, że we wszystkich odpowiedziach, które mogą generować raporty, jest ustawiony nagłówek
Reporting-Endpoints
.W wersji 0 punkty końcowe raportowania można ustawić tylko w przypadku niektórych odpowiedzi, a inne dokumenty (strony) w tym źródle będą używać tego punktu końcowego „otwartego”. Ze względu na różnice w zakresie w wersji 1 musisz ustawiać nagłówek
Reporting-Endpoints
we wszystkich odpowiedziach, które mogą generować raporty.Krok 3 (Rozpocznij później). Gdy wszyscy lub większość Twoich użytkowników zaktualizują Chrome lub Edge do nowszej wersji (96 i nowsze), usuń
Report-To
(wersja 0) i zachowaj tylkoReporting-Endpoints
.Jeden wyjątek: jeśli potrzebujesz raportów dotyczących logowania błędów sieci, zachowaj
Report-To
, dopóki nie zostanie wdrożony nowy mechanizm logowania błędów sieciowych.
Przykłady kodu znajdziesz w książce kucharskiej dotyczącej migracji.
Etapy migracji raportów CSP
Raporty o naruszeniach zasad Content-Security-Policy można skonfigurować na 2 sposoby:
- Z samym nagłówkiem CSP za pomocą dyrektywy
report-uri
. Obsługuje ona szeroką gamę przeglądarek z Chrome, Firefoksa, Safari i Edge. Raporty są wysyłane z typem treściapplication/csp-report
i w formacie dostosowanym do potrzeb CSP. Raporty te są nazywane „raportami CSP poziomu 2” i nie korzystają z interfejsu Reporting API. - Za pomocą interfejsu API do raportowania można to robić za pomocą nagłówka
Report-To
(starsza wersja) lub nowszegoReporting-Endpoints
(wersja 1). Ta funkcja jest obsługiwana tylko w Chrome i Edge. Żądania raportu mają ten sam format co inne żądania do interfejsu API do raportowania i ten sam typ treściapplication/reports+json
.
Stosowanie pierwszego podejścia (tylko report-uri
) nie jest już zalecane, a drugie przynosi kilka korzyści. W szczególności pozwala skonfigurować raportowanie we wszystkich typach raportów w jeden sposób, a także ustawić ogólny punkt końcowy (ponieważ wszystkie żądania raportów generowane za pomocą interfejsu API do raportowania ⏤CSP i inne ⏤ mają ten sam format application/reports+json
.
Jednak tylko niektóre przeglądarki obsługują report-to
.
Dlatego zalecamy stosowanie metody report-uri
równolegle z metodą Reporting API (Report-To
lub lepiej Reporting-Endpoints
), aby otrzymywać z różnych przeglądarek zgłoszenia o naruszeniach zasad CSP. W przeglądarce, która rozpoznaje report-uri
i report-to
, ciąg report-uri
jest ignorowany, jeśli występuje report-to
. W przeglądarce, która rozpoznaje tylko typ report-uri
, tylko report-uri
zostanie uwzględniony.
Krok 1 (wykonaj teraz). Jeśli nie został jeszcze dodany element
report-to
, dodaj go oprócz polareport-uri
. Przeglądarki, które obsługują tylkoreport-uri
(Firefox), będą używaćreport-uri
, a przeglądarki, które również obsługująreport-to
(Chrome, Edge), będą używać przeglądarkireport-to
. Aby określić nazwane punkty końcowe, których będziesz używać w usłudzereport-to
, użyj zarówno nagłówkówReport-To
, jak iReporting-Endpoints
. Dzięki temu będziesz otrzymywać raporty zarówno ze starszych, jak i nowszych klientów Chrome i Edge.Krok 3 (Rozpocznij później). Gdy wszyscy lub większość Twoich użytkowników zaktualizują Chrome lub Edge do nowszej wersji (96 i nowsze), usuń
Report-To
(wersja 0) i zachowaj tylkoReporting-Endpoints
. Zachowajreport-uri
, aby nadal otrzymywać raporty w przeglądarkach, które ją obsługują.
Przykłady kodu tych czynności znajdziesz w artykule Migracja raportów CSP.
Migracja: przykładowy kod
Przegląd
Jeśli używasz starszej wersji interfejsu Reporting API (v0) do pobierania raportów o naruszeniach dotyczących COOP (nagłówka Cross-Origin-Opener-Policy
), COEP (Cross-Origin-Embedder-Policy
) lub zasad dotyczących dokumentów (nagłówek Document-Policy
): nie musisz zmieniać samych nagłówków zasad podczas migracji do interfejsu Reporting API w wersji 1. Musisz tylko przejść ze starszego nagłówka Report-To
na nowy nagłówek Reporting-Endpoints
.
Jeśli do otrzymywania raportów o naruszeniach dotyczących CSP (nagłówek Content-Security-Policy
) używasz starszej wersji interfejsu Reporting API (v0), być może musisz zmodyfikować Content-Security-Policy
w ramach migracji do nowego interfejsu Reporting API (v1).
Migracja podstawowa
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"
Pamiętaj, że wersja 1 pozwala wysyłać określone typy raportów do określonych punktów końcowych. Ale możesz mieć tylko 1 adres URL na punkt końcowy.
Obserwowanie wszystkich stron
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(...) });
Migracja raportów 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: ...
Więcej informacji
- Monitorowanie aplikacji internetowej przy użyciu interfejsu Reporting API (główny post o interfejsie Reporting API)
- Specyfikacja: starsza wersja interfejsu API do raportowania (wersja 0)
- Specyfikacja: nowy interfejs API do raportowania (wersja 1)
Baner powitalny od Nine Koepfer / @enka80 na kanale Unsplash, edytowany. Podziękowania dla Iana Clellanda, Eiji Kitamury i Milicy Mihajlija za ich opinie i sugestie dotyczące tego artykułu.