Przejdź na interfejs API do raportowania w wersji 1

Dostępna jest nowa wersja interfejsu API do raportowania. Zapewnia większą prywatność i jest bardziej prawdopodobne, że będzie obsługiwany przez różne przeglądarki.

Maud Nalpas

Uwaga: ten post zawiera informacje o tym, jak przejść na nową wersję interfejsu Reporting API (wersja 1). Jeśli dopiero zaczynasz korzystać z interfejsu API do raportowania lub potrzebujesz szczegółowych przykładów użycia, przejdź do głównego posta na temat interfejsu API do raportowania.

Interfejs API do raportowania informuje o błędach, które występują w Twojej witrynie podczas korzystania z niej przez użytkowników. Umożliwia on monitorowanie interwencji przeglądarki, awarii przeglądarki, naruszeń zasad Content Security Policy, naruszeń COOP/COEP, ostrzeżeń o wycofaniu i innych zdarzeń.

Dostępna jest nowa wersja interfejsu API do raportowania. Nowy interfejs API jest prostszy i bardziej prawdopodobne jest, że będzieobsługiwany przez różne przeglądarki.

Uwaga: starsza wersja interfejsu API do raportowania nosi nazwę Reporting API v0. Nowy interfejs API do raportowania nosi nazwę Reporting API v1.

Podsumowanie

Deweloperzy witryn

Jeśli masz już funkcję raportowania w swojej witrynie: przejdź na wersję 1, używając nowego nagłówka (Reporting-Endpoints), ale przez pewien czas zachowaj starszy nagłówek (Report-To). Zobacz Migracja: przykładowy kod.

Jeśli dopiero teraz dodajesz do witryny funkcję raportowania: używaj tylko nowego nagłówka (Reporting-Endpoints).

⚠️ W obu przypadkach pamiętaj, aby ustawić nagłówek Reporting-Endpoints we wszystkich odpowiedziach, które mogą generować raporty.

Deweloperzy usług raportowania

Jeśli utrzymujesz usługę punktu końcowego lub zarządzasz własną, spodziewaj się większego ruchu, ponieważ Ty i zewnętrzni programiści będziecie migrować do interfejsu API do raportowania w wersji 1 (nagłówek Reporting-Endpoints).

Szczegółowe informacje i przykładowy kod znajdziesz poniżej.

Rejestrowanie błędów sieci

Uwaga: jeśli używasz rejestrowania błędów sieci, nadal korzystaj z Report-To (wersja 0), ponieważ rejestrowanie błędów sieci nie jest obsługiwane w interfejsie API do raportowania w wersji 1.

Zostanie opracowany nowy mechanizm rejestrowania błędów sieci. Gdy ta funkcja będzie dostępna, przejdź z interfejsu API do raportowania w wersji 0 na ten nowy mechanizm.

Wersja demonstracyjna i kod

• Witryna demonstracyjna: nowy interfejs API do raportowania (wersja 1)
• Kod witryny demonstracyjnej

Różnice między wersjami 0 i 1

Co się zmienia

• Zestaw interfejsów API jest inny.

v0 (starsza wersja)

 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 do odwoływania się do tych grup punktów końcowych.

wersja 1 (nowa)

 Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"
 Document-Policy: ...; report-to main-endpoint

Wersja 1 używa nagłówka Reporting-Endpoints do konfigurowania nazwanych punktów końcowych. Podobnie jak w przypadku wersji 0, w innych nagłówkach używa dyrektywy report-to, aby odwoływać się do tych grup punktów końcowych.

• Zakres raportu jest inny.

wersja 0 (starsza wersja)

W przypadku wersji 0 możesz ustawić punkty końcowe raportowania tylko w przypadku niektórych odpowiedzi. Inne dokumenty (strony) w tej domenie będą automatycznie korzystać z tych punktów końcowych.

wersja 1 (nowa)

W przypadku wersji 1 musisz ustawić 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: interfejs API w wersji 1 nie obsługuje raportów o błędach sieci. Więcej informacji znajdziesz w instrukcji migracji.
• Wersja 0 nie jest i nie będzie obsługiwana w przeglądarkach. Wersja 1 ma większe szanse na obsługę w przyszłości w wielu przeglądarkach.

Co pozostaje bez zmian

• Format i struktura raportów nie uległy zmianie.
• Żądanie wysłane przez przeglądarkę do punktu końcowego pozostaje żądaniem POST typu Content-type application/reports+json.
• Mapowanie określonych punktów końcowych na określone typy raportów jest obsługiwane w wersjach 0 i 1.
• Rola punktu końcowego default pozostaje bez zmian.

• Interfejs API do raportowania w wersji 1 nie ma wpływu na ReportingObserver. ReportingObserver nadal ma dostęp do wszystkich raportów, które można obserwować, a ich format jest identyczny.

Wszystkie różnice między wersją 0 a wersją 1

	Starszy interfejs API do raportowania (wersja 0) Report-To header	Nowy interfejs API do raportowania (wersja 1) Reporting-Endpoints nagłówek
Obsługa przeglądarek	Chrome 69 lub nowsza i Edge 69 lub nowsza.	Chrome 96+, Edge 96+. Firefox jest obsługiwany. Safari nie zgłasza sprzeciwu. Zobacz sygnały przeglądarki.
Punkty końcowe	Wysyła raporty do wielu kolektorów raportów (w przypadku 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 jeden adres URL).
Powierzchnia interfejsu 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	Wycofanie Interwencja Wypadek COOP/COEP Content-Security-Policy Level 3 (CSP Level 3) Rejestrowanie błędów sieci (NEL) Więcej informacji o typach raportów znajdziesz w poście na temat interfejsu API do raportowania.	Bez zmian, z wyjątkiem rejestrowania błędów sieciowych (NEL): ta funkcja nie jest obsługiwana w nowym interfejsie API do raportowania (wersja 1).
Zakres raportu	pochodzenia. Nagłówek dokumentu Report-To wpływa na inne dokumenty (strony) z tego źródła. Pole url w raporcie 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 w raporcie nadal różni się w zależności od dokumentu.
Izolacja zgłoszeń (grupowanie)	Różne dokumenty (strony) lub witryny/źródła, które generują raport w tym samym czasie i mają ten sam punkt końcowy raportowania, będą łączone w pakiety: będą wysyłane w tym samym komunikacie do punktu końcowego raportowania.	Raporty z różnych dokumentów (stron) nigdy nie są wysyłane razem. Nawet jeśli 2 dokumenty (strony) z tego samego źródła wygenerują raport w tym samym czasie dla tego samego punktu końcowego, nie zostaną one połączone w pakiet. Jest to mechanizm ograniczający ataki na prywatność. Zgłoszenia z tego samego dokumentu (strony) mogą być wysyłane razem.
Obsługa równoważenia obciążenia i priorytetów	Tak	Nie

Deweloperzy punktów końcowych: spodziewajcie się większego ruchu

Jeśli Twój serwer został skonfigurowany jako punkt końcowy raportowania lub jeśli tworzysz lub utrzymujesz kolektor raportów jako usługę, spodziewaj się większego ruchu w tym punkcie końcowym.

Dzieje się tak, ponieważ w interfejsie API do raportowania w wersji 1 raporty nie są przetwarzane zbiorczo, 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 pozostanie podobna, ale liczba żądań wysyłanych do serwera punktu końcowego wzrośnie.

Deweloperzy aplikacji: migracja do Reporting-Endpoints (wersja 1)

Co musisz zrobić?

Korzystanie z nowego interfejsu API do raportowania (wersja 1) ma kilka zalet: ✅

• Sygnały przeglądarki są pozytywne, co oznacza, że można oczekiwać obsługi w różnych przeglądarkach w przypadku wersji 1 (w przeciwieństwie do wersji 0, która jest obsługiwana tylko w Chrome i Edge).
• Interfejs API jest bardziej przejrzysty.
• Narzędzia są opracowywane na podstawie nowego interfejsu API do raportowania (wersja 1).

Pamiętaj:

• Jeśli Twoja witryna korzysta już z interfejsu API do raportowania w wersji 0 z nagłówkiem Report-To, przeprowadź migrację do interfejsu API do raportowania w wersji 1 (patrz kroki migracji). Jeśli Twoja witryna korzysta już z funkcji raportowania naruszeń standardu Content Security Policy, zapoznaj się z konkretnymi krokami migracji w przypadku raportowania CSP.
• Jeśli Twoja witryna nie korzysta jeszcze z interfejsu API do raportowania, a teraz dodajesz funkcję raportowania: użyj nowego interfejsu API do raportowania (wersja 1) (nagłówek Reporting-Endpoints). Jest jeden wyjątek od tej reguły: jeśli musisz użyć rejestrowania błędów sieci, użyj Report-To (wersja 0). Rejestrowanie błędów sieciowych nie jest obecnie obsługiwane w interfejsie API do raportowania w wersji 1. Zostanie opracowany nowy mechanizm rejestrowania błędów sieciowych. Do tego czasu używaj interfejsu API do raportowania w wersji 0. Jeśli potrzebujesz rejestrowania błędów sieci wraz z innymi typami raportów, użyj obu wersji: Report-To (v0) i Reporting-Endpoints (v1). Wersja v0 umożliwia rejestrowanie błędów sieci, a wersja v1 – generowanie raportów o wszystkich innych typach.

Etapy migracji

Celem tej migracji jest nieutracenie raportów, które były dostępne w wersji 0.

Uwaga: ponieważ tylko Chrome i Edge obsługują interfejs API do raportowania w wersji 0, podczas migracji do wersji 1 nie musisz skupiać się na innych przeglądarkach. Pamiętaj jednak, że wkrótce może pojawić się szersza obsługa przeglądarek. Obecnie nie ma błędów śledzenia w przypadku tych przeglądarek, ale może się to zmienić.

1. Krok 1 (wykonaj teraz): użyj obu nagłówków: Report-To (v0) i Reporting-Endpoints (v1).

   Dzięki temu zyskujesz:

   • Raporty z nowszych klientów Chrome i Edge dzięki Reporting-Endpoints (wersja 1).
   • Raporty ze starszych klientów Chrome i Edge dzięki Report-To (v0).

   Instancje przeglądarki, które obsługują Reporting-Endpoints, będą używać Reporting-Endpoints, a instancje, które nie obsługują tej funkcji, będą używać Report-To. Format żądania i raportu jest taki sam w przypadku wersji 0 i 1.

2. Krok 2 (wykonaj teraz): upewnij się, że nagłówek Reporting-Endpoints jest ustawiony we wszystkich odpowiedziach, które mogą generować raporty.

   W przypadku wersji 0 można było ustawić punkty końcowe raportowania tylko w przypadku niektórych odpowiedzi, a inne dokumenty (strony) w tej domenie używałyby tego „otaczającego” punktu końcowego. W przypadku wersji 1 ze względu na różnice w zakresie musisz ustawić nagłówek Reporting-Endpoints we wszystkich odpowiedziach, które mogą generować raporty.

3. Krok 3 (rozpocznij później): gdy wszyscy lub większość użytkowników zaktualizuje Chrome lub Edge do nowszej wersji (96 lub nowszej), usuń Report-To (v0) i pozostaw tylko Reporting-Endpoints.

   Wyjątek: jeśli potrzebujesz raportów rejestrowania błędów sieciowych, zachowaj Report-To, dopóki nie zostanie wdrożony nowy mechanizm rejestrowania błędów sieciowych.

Przykłady kodu znajdziesz w przewodniku po migracji.

Kroki migracji raportowania CSP

Raporty o naruszeniach Content-Security-Policy można skonfigurować na 2 sposoby:

• za pomocą samego nagłówka CSP za pomocą dyrektywy report-uri, Jest ona obsługiwana przez wiele przeglądarek, w tym Chrome, Firefox, Safari i Edge. Raporty są wysyłane z typem treści application/csp-report i mają format specyficzny dla CSP. Są to „Raporty CSP na poziomie 2”, które nie korzystają z interfejsu Reporting API.
• W przypadku interfejsu API do raportowania jest to nagłówek Report-To (starszy) lub nowszy nagłówek Reporting-Endpoints (wersja 1). Ta funkcja jest obsługiwana tylko w Chrome i Edge. Żądania raportów mają taki sam format jak inne żądania interfejsu API do raportowania i ten sam typ treści application/reports+json.

Pierwsze podejście (tylko report-uri) nie jest już zalecane, a drugie ma kilka zalet. Umożliwia to w szczególności korzystanie z jednego sposobu konfigurowania raportowania dla wszystkich typów raportów, a także ustawianie ogólnego punktu końcowego (ponieważ wszystkie żądania raportów generowane za pomocą interfejsu Reporting API – CSP i innych – mają ten sam format application/reports+json).

Jednak tylko kilka przeglądarek obsługuje report-to. Dlatego zalecamy, aby oprócz podejścia opartego na interfejsie API do raportowania (Report-To lub nowszym, Reporting-Endpoints) stosować też report-uri, aby otrzymywać raporty o naruszeniach CSP z wielu przeglądarek. W przeglądarce, która rozpoznaje report-uri i report-to, element report-uri zostanie zignorowany, jeśli występuje element report-to. W przeglądarce, która rozpoznaje tylko report-uri, pod uwagę będzie brany tylko znak report-uri.

1. Krok 1. (wykonaj teraz): jeśli jeszcze tego nie zrobiono, dodaj report-to obok report-uri. Przeglądarki, które obsługują tylko report-uri (Firefox), będą używać report-uri, a przeglądarki, które obsługują też report-to(Chrome, Edge), będą używać report-to. Aby określić nazwane punkty końcowe, których będziesz używać w report-to, użyj nagłówków Report-To i Reporting-Endpoints. Dzięki temu będziesz otrzymywać raporty zarówno ze starszych, jak i nowszych klientów Chrome i Edge.

2. Krok 3 (rozpocznij później): gdy wszyscy lub większość użytkowników zaktualizuje Chrome lub Edge do nowszej wersji (96 lub nowszej), usuń Report-To (v0) i pozostaw tylko Reporting-Endpoints. Zachowaj report-uri, aby nadal otrzymywać raporty dotyczące przeglądarek, które obsługują tylko tę opcję.

Przykłady kodu dla tych kroków znajdziesz w artykule Migracja raportowania CSP.

Migracja: przykładowy kod

Przegląd

Jeśli używasz starszej wersji interfejsu API do raportowania (v0) do pobierania raportów o naruszeniach zasad dotyczących nagłówka COOP (Cross-Origin-Opener-Policy), COEP (Cross-Origin-Embedder-Policy) lub zasad dokumentu (Document-Policy): podczas migracji do interfejsu API do raportowania w wersji 1 nie musisz zmieniać tych nagłówków zasad. Musisz jednak przejść ze starszego nagłówka Report-To na nowy nagłówek Reporting-Endpoints.

Jeśli używasz starszej wersji interfejsu API do raportowania (v0) do uzyskiwania raportów o naruszeniach w przypadku nagłówka CSP (Content-Security-Policy), w ramach migracji na nowy interfejs API do raportowania (v1) może być konieczne dostosowanie Content-Security-Policy.

Podstawowa migracja

Starsza wersja kodu (z v0)

Report-To: { group: "main-endpoint", "endpoints": [ { "url": "https://reports.example/main" }] }, { group: "default-endpoint", "endpoints": [ { "url": "https://reports.example/default" }] }

Nowy kod (kod przejściowy z wersją 0 obok wersji 1)

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 Twoja witryna ma już funkcję raportowania, Report-To tymczasowo (do czasu zaktualizowania większości klientów Chrome i Edge) zachowaj tę funkcję, aby nie utracić raportów.

Jeśli potrzebujesz rejestrowania błędów sieci, zachowaj Report-To do czasu udostępnienia zamiennika rejestrowania błędów sieci.

Nowy kod (tylko w przypadku wersji 1)

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 przypadku wersji 1 nadal możesz wysyłać określone typy raportów do określonych punktów końcowych. Jednak do każdego punktu końcowego możesz przypisać tylko 1 adres URL.

Obserwowanie wszystkich stron

Starsza wersja kodu (z wersją 0), na przykład w przypadku Express

app.get("/", (request, response) => {
  response.set("Report-To", …)
  response.render(...)
});
app.get("/page1", (request, response) => {
  response.render(...)
});

W przypadku wersji 0 możesz ustawić punkty końcowe raportowania tylko w przypadku niektórych odpowiedzi. Inne dokumenty (strony) w tej domenie automatycznie korzystają z tych punktów końcowych. W tym przypadku punkty końcowe ustawione dla "/" są używane we wszystkich odpowiedziach, np. w przypadku page1.

Nowy kod (z wersją 1), na przykład w przypadku Express

// 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 przypadku wersji 1 musisz ustawić nagłówek Reporting-Endpoints we wszystkich odpowiedziach, które mogą generować raporty.

Migracja raportowania CSP

Starsza wersja kodu z samym parametrem report-uri

Content-Security-Policy: ...; report-uri https://reports.example/main

Używanie tylko report-uri nie jest już zalecane. Jeśli Twój kod wygląda jak powyżej, przeprowadź migrację. Poniżej znajdziesz przykłady nowego kodu (na zielono).

Lepszy kod starszego typu z dyrektywą report-uri i dyrektywą report-to z nagłówkiem Report-To (v0)

Content-Security-Policy: ...; report-uri https://reports.example/main; report-to main-endpoint
Report-To: main-endpoint="https://reports.example/main"

To lepsze rozwiązanie: ten kod używa dyrektywy report-to, która jest nowszym zamiennikiem dyrektywy report-uri. Zachowuje on nadal parametr report-uri ze względu na zgodność wsteczną. Niektóre przeglądarki nie obsługują parametru report-to, ale obsługują parametr report-uri.

Można to jednak zrobić lepiej: ten kod używa interfejsu API do raportowania w wersji 0 (nagłówek Report-To). Przejdź na wersję 1: zapoznaj się z przykładami „Nowy kod” poniżej (na zielono).

Nowy kod z dyrektywami report-uri i report-to oraz nagłówkiem Reporting-Endpoints (v1)

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 obok dyrektywy report-to, dopóki dyrektywa report-to nie będzie obsługiwana we wszystkich przeglądarkach. Zapoznaj się z tabelą zgodności z przeglądarkami.

Zachowaj Report-To obok Reporting-Endpoints tymczasowo. Gdy większość użytkowników Chrome i Edge zaktualizuje przeglądarkę do wersji 96 lub nowszej, usuń Report-To.

Więcej informacji

• Monitorowanie aplikacji internetowej za pomocą interfejsu API do raportowania (główny post o interfejsie API do raportowania)
• Specyfikacja: starszy interfejs API do raportowania (wersja 0)
• Specyfikacja: nowy interfejs API do raportowania (wersja 1)

Dziękujemy Ianowi Clellandowi, Eijiemu Kitamurze i Milicy Mihajliji za ich opinie i sugestie dotyczące tego artykułu.