Dostępna jest nowa wersja interfejsu API do raportowania. Ma on bardziej prywatny charakter i większe prawdopodobieństwo, że będą obsługiwane 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ą. Zapewnia informacje na temat interwencji i awarii przeglądarek, naruszeń zasad Content-Security-Policy, Naruszenia dotyczące współpracy i COEP, ostrzeżenia o wycofaniu i inne informacje.
Dostępna jest nowa wersja interfejsu API do raportowania. Nowy interfejs API jest prostszy i prawdopodobnie obsługiwane w różnych przeglądarkach.
Podsumowanie
Programiści witryn
Jeśli masz już w swojej witrynie funkcję raportowania, przejdź do wersji 1, używając nowego nagłówka.
(Reporting-Endpoints
), ale zachowaj starszy nagłówek przez jakiś czas (Report-To
).
Zobacz Migracja: przykładowy kod.
Jeśli właśnie dodajesz do witryny funkcję raportowania: używaj tylko nowego nagłówka.
(Reporting-Endpoints
).
⚠️ W obu przypadkach ustaw nagłówek Reporting-Endpoints
dla wszystkich odpowiedzi, które mogą
generować raporty.
Programiści usług raportowania
Jeśli korzystasz z usługi punktu końcowego lub korzystasz z własnej obsługi, możesz spodziewać się większego ruchu w miarę
lub zewnętrznych programistów przeszli na interfejs API do raportowania w wersji 1 (nagłówek Reporting-Endpoints
).
Szczegóły i przykładowy kod znajdziesz w dalszej części tego artykułu.
Logowanie błędów sieci
Zostanie opracowany nowy mechanizm logowania błędów sieci. Gdy stanie się on dostępny, przejdź z interfejsu Reporting API w wersji 0 na ten nowy mechanizm.
Wersja demonstracyjna i kod
- Witryna demonstracyjna: nowy interfejs API do raportowania (v1)
- kod witryny demonstracyjnej.
Różnice między wersjami v0 i v1
Co się zmienia
- Interfejs API wygląda inaczej.
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
{0 używa nagłówka Report-To
do konfigurowania nazwanych grup punktów końcowych, a dyrektywy report-to
w innych nagłówkach służy do odwoływania się do tych grup.
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default" Document-Policy: ...; report-to main-endpoint
Wersja v1 używa nagłówka Reporting-Endpoints
do konfigurowania nazwanych
i punktów końcowych. Podobnie jak w wersji 0, ta dyrektywa wykorzystuje dyrektywę report-to
w innych nagłówkach, aby odwoływać się do tych grup punktów końcowych.
- Zakres tego raportu jest inny.
W wersji 0 możesz ustawiać punkty końcowe raportowania tylko w przypadku niektórych odpowiedzi. inne dokumenty (strony) na ten temat. źródło automatycznie używa tych punktów końcowych otoczenia.
W wersji 1 musisz ustawiać nagłówek Reporting-Endpoints
we wszystkich odpowiedziach, które mogą generować
raportów.
- 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 krokach migracji.
- Wersja 0 nie jest i nie będzie obsługiwana w różnych przeglądarkach. v1 ma większe szanse na obsługę więcej niż jedna przeglądarka.
Co pozostaje niezmienione
- Format i struktura raportów pozostają bez zmian.
- Żądanie wysłane przez przeglądarkę do punktu końcowego pozostaje żądaniem
POST
o wartościContent-type
application/reports+json
- Mapowanie niektórych punktów końcowych na określone typy raportów jest obsługiwane zarówno w wersjach 0, jak i 1.
- Rola punktu końcowego
default
pozostanie bez zmian. Interfejs API do raportowania w wersji 1 nie ma wpływu na
ReportingObserver
. OrganizacjaReportingObserver
nadal ma dostęp do wszystkich dostrzegalnych raportów, a jej format to identyczna.
Wszystkie różnice między v0 a v1
Starsza wersja interfejsu API do raportowania (wersja 0)Report-To – nagłówek |
Nowy interfejs API do raportowania (v1)Reporting-Endpoints – nagłówek |
|
---|---|---|
Obsługa przeglądarek | Chrome w wersji 69 lub nowszej oraz Edge w wersji 69 lub nowszej. | Chrome 96 i nowsze oraz Edge w wersji 96 lub nowszej. Program Firefox działa. Safari nie działa. Zobacz sygnały przeglądarki. |
Punkty końcowe | Wysyła raporty do dowolnego z wielu kolektorów raportów (wiele adresów URL zdefiniowanych na każdą grupę punktów końcowych). | Wysyła raporty do określonych kolektorów raportów (tylko jeden adres URL zdefiniowany na punkt końcowy). |
Interfejs API | Używa 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 Network Error Logging (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 nadal 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 nadal różni się w zależności od dokumentu.
|
Izolacja raportów (grupowe) | Różne dokumenty (strony) lub witryny lub źródła, które generują raport mniej więcej w tym samym czasie i mają ten sam punkt końcowy raportowania, zostaną grupowane: do punktu końcowego raportowania zostaną wysłane w tym samym komunikacie. |
|
Obsługa równoważenia obciążenia / priorytetów | Tak | Nie |
Programiści punktów końcowych: spodziewaj się większego ruchu
Jeśli jako punkt końcowy raportowania masz skonfigurowany własny serwer albo tworzysz lub utrzymujesz kolektora jako usługi, należy spodziewać się większego ruchu do tego punktu końcowego.
Dzieje się tak, ponieważ raporty nie są grupowane za pomocą interfejsu Reporting API w wersji 1, tak jak w przypadku interfejsu API do raportowania w wersji 0. Dlatego gdy deweloperzy aplikacji zaczną przechodzić na interfejs API do raportowania w wersji 1, liczba raportów będzie pozostaną podobne, ale liczba żądań do serwera punktu końcowego wzrośnie.
Programiści aplikacji: migracja do wersji Reporting-Endpoints
(v1)
Co musisz zrobić?
Korzystanie z nowego interfejsu Reporting API (wersja 1) ma kilka zalet ✅:
- Sygnały przeglądarki są pozytywne, co oznacza, że że w przypadku wersji 1 można oczekiwać obsługi różnych przeglądarek (w przeciwieństwie do wersji 0, która jest obsługiwana tylko Edge).
- Interfejs API jest prostszy.
- Pracujemy nad narzędziami opartymi na nowym interfejsie Reporting API (v1).
Mając to na uwadze:
- Jeśli Twoja witryna używa już interfejsu API do raportowania w wersji 0 z nagłówkiem
Report-To
, przejdź na Interfejs API do raportowania w wersji 1 (zobacz instrukcje migracji). Jeśli Twoja witryna używa już funkcji zgłaszania naruszeń zasad zabezpieczeń treści, zapoznaj się z instrukcjami migracji dotyczącymi raportowania CSP. - Jeśli Twoja witryna nie korzysta jeszcze z interfejsu API do raportowania, a teraz dodajesz funkcję raportowania:
użyć nowego interfejsu API do raportowania (v1) (nagłówka
Reporting-Endpoints
). Jedyny wyjątek to to: jeśli chcesz skorzystać z logowania błędów sieci, użyjReport-To
(v0). Logowanie błędów sieci nie jest obecnie obsługiwane przez interfejs API do raportowania w wersji 1. Nowy mechanizm logowania błędów sieci do czasu, aż będzie dostępny, używaj interfejsu Reporting API w wersji 0. Jeśli potrzebujesz logowania błędów sieci obok innych typów raportów użyj obu typów raportów:Report-To
(v0) iReporting-Endpoints
(v1). v0 umożliwia rejestrowanie błędów sieciowych, a wersja 1 umożliwia generowanie raportów ze wszystkich innych typów.
Etapy migracji
Celem migracji jest nieutracie raportów, które były dostępne w wersji 0.
Krok 1 (zrób teraz). Użyj obu nagłówków:
Report-To
(wersja 0) iReporting-Endpoints
(wersja 1).Dzięki temu:
- Raporty z nowszych klientów Chrome i Edge dzięki
Reporting-Endpoints
(v1). - Raporty ze starszych klientów Chrome i Edge dzięki
Report-To
(v0).
Instancje przeglądarki, które obsługują interfejs
Reporting-Endpoints
, będą używać tych reguł:Reporting-Endpoints
, instancje, które nie zostaną przełączone na wersjęReport-To
. Żądanie i raport są w tych samych miejscach v0 i v1.- Raporty z nowszych klientów Chrome i Edge dzięki
Krok 2. Upewnij się, że nagłówek
Reporting-Endpoints
jest ustawiony we wszystkich odpowiedziach, które może generować raporty.W wersji 0 można było ustawić punkty końcowe raportowania tylko dla niektórych odpowiedzi, a w innych (strony) w tym źródle używałoby określenia „otoczenie” punktu końcowego. W przypadku wersji v1 ze względu na różnicę musisz ustawić nagłówek
Reporting-Endpoints
we wszystkich odpowiedziach, które mogą generować raportów.Krok 3 (później): po zaktualizowaniu Chrome lub Edge dla wszystkich lub większości użytkowników instalacje (96 i nowsze), usuń
Report-To
(v0) i zachowuj tylkoReporting-Endpoints
.Jedyny wyjątek: jeśli potrzebujesz raportów logowania błędów sieci, zachowaj
Report-To
do czasu dla logowania błędów sieci.
Zobacz przykłady kodu w książce kucharskiej na temat migracji.
Etapy migracji raportowania CSP
Funkcja Content-Security-Policy Raporty o naruszeniach można skonfigurować:
- Z samym nagłówkiem CSP za pomocą dyrektywy
report-uri
. Obsługuje wszystkie przeglądarki – Chrome, Firefox, Safari i Edge. Raporty są wysyłane z typem treściapplication/csp-report
i mają format odpowiedni dla CSP. Raporty te noszą nazwę „Raporty CSP poziomu 2”. i zrób nie korzystają z interfejsu API do raportowania. - w interfejsie API do raportowania, czyli za pomocą nagłówka
Report-To
(starsza wersja) lub nowszej,Reporting-Endpoints
(wersja 1). Ta funkcja jest obsługiwana tylko w Chrome i Edge. Żądania raportów zawierają taki sam format jak inne żądania do interfejsu Reporting API i ten sam typ treściapplication/reports+json
.
Pierwsza metoda (tylko report-uri
) nie jest już zalecana, a druga ma kilka zalet. W szczególności pozwala korzystać z jednego sposobu konfigurowania raportów dla wszystkich typów raportów oraz ustawić ogólny punkt końcowy (ponieważ wszystkie żądania raportów wygenerowane przez interfejs API do raportowania⏤CSP i inne⏤ mają ten sam format application/reports+json
).
Jednak tylko kilka przeglądarek obsługuje report-to
.
Z tego względu zalecamy stosowanie report-uri
obok interfejsu API do raportowania (Report-To
Reporting-Endpoints
), aby otrzymywać raporty o naruszeniach zasad CSP z różnych przeglądarek. W
przeglądarka, która rozpoznaje report-uri
i report-to
, zasada report-uri
zostanie zignorowana, jeśli report-to
. W przeglądarce, która rozpoznaje tylko tag report-uri
, uwzględniana jest tylko wartość report-uri
.
Krok 1 (zrób teraz). Jeśli kod
report-to
nie został jeszcze dodany, dodaj go razem z usługąreport-uri
. Przeglądarki obsługujące tylkoreport-uri
(Firefox) będą używaćreport-uri
, a także przeglądarki, które również obsługareport-to
(Chrome, Edge) będzie używaćreport-to
. Aby określić nazwane punkty końcowe, których użyjesz w plikureport-to
użyj nagłówkówReport-To
iReporting-Endpoints
. Dzięki temu uzyskasz ze starszych i nowszych klientów Chrome i Edge.Krok 3 (później): po zaktualizowaniu Chrome lub Edge dla wszystkich lub większości użytkowników instalacje (96 i nowsze), usuń
Report-To
(v0) i zachowuj tylkoReporting-Endpoints
. Google Keepreport-uri
, aby nadal otrzymywać raporty dotyczące tylko przeglądarek, które go obsługują.
Przykładowe fragmenty kodu związane z tymi instrukcjami znajdziesz w artykule na temat migracji raportów CSP.
Migracja: przykładowy kod
Omówienie
Jeśli używasz starszej wersji interfejsu Reporting API (w wersji 0) do otrzymywania raportów o naruszeniach zasad dotyczących współpracy
(nagłówek Cross-Origin-Opener-Policy
), zasady dotyczące kosztu własnego sprzedaży (Cross-Origin-Embedder-Policy
) lub zasady dotyczące dokumentów
(nagłówek Document-Policy
): nie musisz samodzielnie zmieniać nagłówków zasad podczas migracji.
do interfejsu API do raportowania w wersji 1. Musisz tylko przejść ze starszego nagłówka Report-To
na nowy.
Reporting-Endpoints
.
Jeśli używasz starszej wersji interfejsu Reporting API (v0) do otrzymywania raportów o naruszeniach zasad dotyczących CSP
(Content-Security-Policy
), być może trzeba będzie dostosować Content-Security-Policy
w ramach
przejście na nowy interfejs API do raportowania (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" }] }
Jeśli masz już w witrynie funkcję raportowania, zachowaj Report-To
tylko tymczasowo
(dopóki większość klientów Chrome i Edge zostanie zaktualizowana), aby uniknąć utraty raportów.
Jeśli potrzebujesz logowania błędów sieci, zachowaj Report-To
do czasu jego wymiany
będzie dostępna.
Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
Tak może wyglądać Twój kod w przyszłości, gdy większość klientów Chrome i Edge zostanie zaktualizowana i będzie obsługiwać interfejs API w wersji 1.
Pamiętaj, że w wersji 1 nadal możesz wysyłać określone typy raportów do określonych punktów końcowych. Ale Ty może 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(...) });
W wersji 0 możesz ustawiać punkty końcowe raportowania tylko w przypadku niektórych odpowiedzi. Inny powód
dokumenty (strony) w tym źródle automatycznie używają tych punktów końcowych otoczenia. Tutaj punkty końcowe
dla "/"
są używane we wszystkich odpowiedziach, na przykład dla page1
.
// 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(...) });
W wersji 1 musisz ustawić nagłówek Reporting-Endpoints
na wszystkich
odpowiedzi, które mogą generować raporty.
Migracja raportów CSP
Content-Security-Policy: ...; report-uri https://reports.example/main
Używanie tylko atrybutu report-uri
nie jest już możliwe
zalecamy.
Jeśli Twój kod wygląda tak jak powyżej, przeprowadź migrację. Zobacz przykłady nowego kodu poniżej (zaznaczone na zielono).
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint Report-To: main-endpoint="https://reports.example/main"
Jest lepsze: ten kod korzysta z parametru report-to, a jego nowszy odpowiednik
report-uri. Nadal zachowuje identyfikator URI raportu, by zapewnić zgodność wsteczną. kilka
przeglądarki nie obsługują
report-to
ale wspieraj
report-uri
Nadal może być inaczej: ten kod korzysta z interfejsu Reporting API w wersji 0 (nagłówek Report-To
). Migrate to v1: zobacz
Nowy kod poniżej (w kolorze zielonym).
Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint Reporting-Endpoints: main-endpoint="https://reports.example/main" Report-To: ...
Zachowaj dyrektywę report-uri
wraz z dyrektywą report-to
do momentu wprowadzenia dyrektywy report-to
działa w różnych przeglądarkach. Zobacz zgodność przeglądarek
Tymczasowo przechowuj Report-To
obok Reporting-Endpoints
. Gdy większość przeglądarki Chrome i Edge
użytkownicy uaktualnili przeglądarki do ponad 96 wersji, usuń Report-To
.
Więcej informacji
- Monitorowanie aplikacji internetowej przy użyciu interfejsu API do raportowania (główny post o interfejsie API do raportowania)
- Specyfikacja: starszy interfejs API do raportowania (v0)
- Specyfikacja: nowy interfejs API do raportowania (v1)
Baner powitalny: Nine Koepfer / @enka80, Unsplash, edycja. Z wieloma podziękowaniem dla Iana Clelland, Eiji Kitamura i Milica Mihajlija za opinie i sugestie na temat tego artykuł.