Przejdź na interfejs API do raportowania w wersji 1

Dostępna jest nowa wersja interfejsu Reporting API. Ma on bardziej prywatny charakter i większe prawdopodobieństwo, że będą obsługiwane w różnych przeglądarkach.

Maud Nalpas

Uwaga: ten artykuł zawiera informacje o przechodzeniu na nową wersję interfejsu Reporting API (w wersji 1). Jeśli nie znasz jeszcze interfejsu Reporting API lub potrzebujesz szczegółowych przykładów jego użycia, przeczytaj główny artykuł na temat tego interfejsu.

Interfejs Reporting API informuje o błędach występujących w Twojej witrynie podczas jej używania przez użytkowników. Dzięki niemu możesz sprawdzać interwencje przeglądarki, jej awarie, naruszenia zasad Content Security Policy, naruszenia zasad COOP/COEP, ostrzeżenia o wycofaniu i inne informacje.

Dostępna jest nowa wersja interfejsu Reporting API. Nowy interfejs API jest prostszy i lepiej działa w różnych przeglądarkach.

Uwaga: starsza wersja interfejsu Reporting API nosi nazwę Reporting API w wersji 0. Nowy interfejs Reporting API nosi nazwę Reporting API v1.

Podsumowanie

Deweloperzy witryn

Jeśli masz już w swojej witrynie funkcję raportowania: przejdź na wersję 1 za pomocą nowego nagłówka (Reporting-Endpoints), ale przez jakiś czas zachowaj stary nagłówek (Report-To). Zobacz Przejście na wersję 1: przykładowy kod.

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

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

Programiści usług raportowania

Jeśli zarządzasz usługą punktu końcowego lub sam ją udostępniasz, spodziewaj się większego ruchu, gdy Ty lub zewnętrzni deweloperzy przejdziecie na interfejs Reporting API w wersji 1 (nagłówek Reporting-Endpoints).

Czytaj dalej, aby dowiedzieć się więcej i poznać przykładowy kod.

Rejestrowanie błędów sieci

Uwaga: jeśli korzystasz z rejestrowania błędów sieci, nadal używaj interfejsu Report-To (w wersji 0), ponieważ rejestrowanie błędów sieci nie jest obsługiwane w interfejsie Reporting API w wersji 1.

Zostanie opracowany nowy mechanizm rejestrowania błędów sieci. Gdy to nastąpi, przejdź z interfejsu Reporting API w wersji 0 na nowy mechanizm.

Wersja demonstracyjna i kod

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

Różnice między wersjami v0 i v1

Co się zmienia

• Interfejs 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 służy do odwoływania się do tych grup.

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 wersji 0, ta dyrektywa wykorzystuje dyrektywę report-to w innych nagłówkach, aby odwoływać się do tych grup punktów końcowych.

• Zakres raportu jest inny.

v0 (starsza wersja)

W wersji 0 możesz skonfigurować punkty końcowe raportowania tylko w przypadku niektórych odpowiedzi. Inne dokumenty (strony) w tym źródle będą automatycznie używać tych punktów końcowych.

v1 (nowa)

W 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: 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. W przyszłości prawdopodobnie będzie obsługiwana w różnych przeglądarkach.

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ści 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 w wersji 1.
• Rola punktu końcowego default pozostaje niezmieniona.

• Interfejs API do raportowania w wersji 1 nie ma wpływu na ReportingObserver. Organizacja ReportingObserver nadal ma dostęp do wszystkich raportów możliwych do obserwowania, a ich format jest taki sam.

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

	Starszy interfejs Reporting API (w wersji 0) Report-To nagłówek	Nowy nagłówek interfejsu API do raportowania (v1) Reporting-Endpoints
Obsługa przeglądarek	Chrome 69 lub nowszy oraz Edge 69 lub nowszy.	Chrome 96 lub nowszy oraz Edge 96 lub nowszy. Firefox jest obsługiwany. Safari nie ma nic przeciwko temu. Zobacz sygnały przeglądarki.
Punkty końcowe	Wysyła raporty do wielu gromadzącym raporty (wiele adresów URL zdefiniowanych na 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 wygenerować za pomocą tego interfejsu API	Wycofanie interwencji; Wypadek COOP/COEP Content-Security-Policy Level 3 (CSP Level 3) Rejestrowanie błędów sieciowych (NEL) Więcej informacji o typach raportów znajdziesz w poście na temat interfejsu Reporting API.	Nie zmienione, z wyjątkiem logowania błędów sieci (NEL): ta funkcja nie jest obsługiwana w nowym interfejsie Reporting API (w wersji 1).
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 zastosowanie tylko do tego dokumentu. Pole url w raporcie nadal różni się w zależności od dokumentu.
Izolowanie raportów (zbiorczo)	Różne dokumenty (strony) lub witryny/źródła, które generują raport mniej więcej w tym samym czasie i mają ten sam punkt końcowy raportowania, zostaną zgrupowane razem: zostaną wysł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 i dla tego samego punktu końcowego, nie zostaną one zgrupowane. Jest to mechanizm ograniczający ataki na prywatność. Raporty z tego samego dokumentu (tej samej strony) mogą być wysyłane razem.
Obsługa równoważenia obciążenia / priorytetów	Tak	Nie

Programiści punktów końcowych: spodziewaj się większego ruchu

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

Wynika to z tego, że w interfejsie Reporting API w wersji 1 raporty nie są grupowane, jak w interfejsie Reporting API w wersji 0. Dlatego, gdy deweloperzy aplikacji zaczną przechodzić na interfejs Reporting API w wersji 1, liczba raportów pozostanie podobna, ale objętość żądań do serwera punktu końcowego wzrośnie.

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

Co musisz zrobić?

Korzystanie z nowego interfejsu Reporting API (w wersji 1) niesie ze sobą kilka korzyści: ✅

• Sygnały przeglądarki są dodatnie, co oznacza, że można oczekiwać obsługi wersji 1 w różnych przeglądarkach (w przeciwieństwie do wersji 0, która jest obsługiwana tylko w Chrome i Edge).
• Interfejs API jest prostszy.
• Narzędzia są opracowywane pod kątem nowego interfejsu Reporting API (w wersji 1).

Mając to na uwadze:

• Jeśli Twoja witryna korzysta już z interfejsu Reporting API w wersji 0 z nagłówkiem Report-To, przeprowadź migrację do interfejsu Reporting API w wersji 1 (patrz sposób przeprowadzenia migracji). Jeśli w swojej witrynie korzystasz już z funkcji zgłaszania naruszeń zasad zabezpieczeń treści, zapoznaj się z instrukcjami migracji raportów CSP.
• Jeśli Twoja witryna nie korzysta jeszcze z interfejsu Reporting API i dodajesz do niej funkcję raportowania: użyj nowego interfejsu Reporting API (w wersji 1) (nagłówek Reporting-Endpoints). Jest 1 wyjątek: jeśli musisz używać rejestrowania błędów sieci, użyj Report-To (wersja 0). Logowanie błędów sieci nie jest obecnie obsługiwane w interfejsie Reporting API w wersji 1. Będziemy opracowywać nowy mechanizm rejestrowania błędów sieci. Do tego czasu używaj interfejsu Reporting API w wersji 0. Jeśli potrzebujesz rejestrowania błędów sieci oraz innych typów raportów, użyj obu opcji Report-To (w wersji 0) i Reporting-Endpoints (w wersji 1). Opcja w wersji 0 umożliwia rejestrowanie błędów sieci, a opcja w wersji 1 – raportowanie wszystkich innych typów.

Etapy migracji

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

Uwaga: ponieważ tylko Chrome i Edge obsługują interfejs Reporting API w wersji 0, podczas migracji do wersji 1 nie musisz się skupiać na innych przeglądarkach. Pamiętaj jednak, że w przyszłości może się to zmienić i obsługa w większej liczbie przeglądarek może się zwiększyć. Obecnie w tych przeglądarkach nie ma błędów związanych z śledzeniem, ale może się to zmienić.

1. Krok 1 (do tej pory): użyj obu nagłówków: Report-To (wersja 0) i Reporting-Endpoints (wersja 1).

   Dzięki temu:

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

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

2. Krok 2 (do tej pory): sprawdź, czy nagłówek Reporting-Endpoints jest ustawiony we wszystkich odpowiedziach, które mogą generować raporty.

   W wersji 0 można było ustawić punkty końcowe raportowania tylko w niektórych odpowiedziach, a inne dokumenty (strony) w tej domenie używałyby tego „obciętego” punktu końcowego. W wersji 1 ze względu na różnice w zakresie działania 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 zaktualizują Chrome lub Edge do nowszych wersji (96 i nowszych), usuń Report-To (w wersji 0) i zachowaj tylko Reporting-Endpoints.

   Wyjątek: jeśli potrzebujesz raportów z rejestrowania błędów sieciowych, zachowaj Report-To do czasu wdrożenia nowego mechanizmu rejestrowania błędów sieciowych.

Przykłady kodu znajdziesz w książce kucharskiej migracji.

Kroki migracji dotyczące raportowania CSP

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

• Z samym nagłówkiem CSP za pomocą dyrektywy report-uri. Ta funkcja jest obsługiwana w wielu przeglądarkach, takich jak Chrome, Firefox, Safari i Edge. Raporty są wysyłane z typem treści application/csp-reporti mają format właściwy dla CSP. Te raporty nazywają się „Raporty CSP poziomu 2” i nie są zależne od interfejsu Reporting API.
• W przypadku interfejsu Reporting API można to zrobić za pomocą nagłówka Report-To (w starszej wersji) lub nowszego nagłówka Reporting-Endpoints (w wersji 1). Ta funkcja jest obsługiwana tylko w Chrome i Edge. Żądania dotyczące raportów mają taki sam format i typ treści application/reports+jsonjak inne żądania w interfejsie Reporting API.

Pierwsza metoda (tylko report-uri) nie jest już zalecana, a druga ma kilka zalet. W szczególności umożliwia to skonfigurowanie raportowania dla wszystkich typów raportów za pomocą jednej metody oraz ustawienie ogólnego punktu końcowego (ponieważ wszystkie żądania raportów wygenerowane za pomocą interfejsu Reporting API⏤CSP i innych⏤ mają ten sam format: application/reports+json.

Jednak report-to obsługuje tylko kilka przeglądarek. Dlatego zalecamy, aby report-uri stosować równolegle z interfejsem API do raportowania (Report-To lub lepiej Reporting-Endpoints), aby otrzymywać raporty o naruszeniu zasad CSP z wielu przeglądarek. W przeglądarce, która rozpoznaje report-uri i report-to, zasada report-uri zostanie zignorowana, jeśli obecna jest zasada report-to. W przeglądarce, która rozpoznaje tylko report-uri, brany pod uwagę będzie tylko report-uri.

1. Krok 1 (zrób teraz). Jeśli kod report-to nie został jeszcze dodany, dodaj go razem z usługą 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ą 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 (zacznij później). Gdy wszyscy lub większość użytkowników zaktualizuje swoją przeglądarkę do nowszych instalacji Chrome lub Edge (w wersji 96 lub nowszej), usuń wersję Report-To (v0) i zachowuj tylko Reporting-Endpoints. Zachowaj report-uri, aby nadal otrzymywać raporty z przeglądarek, które obsługują tylko tę metodę.

Przykłady kodu dla tych kroków znajdziesz w artykule Migrowanie raportowania z usług CSP.

Migracja: przykładowy kod

Omówienie

Jeśli korzystasz ze starszej wersji interfejsu Reporting API (v0) do otrzymywania raportów o naruszeniach dotyczących podmiotu stowarzyszonego (nagłówek Cross-Origin-Opener-Policy), kosztu własnego sprzedaży (Cross-Origin-Embedder-Policy) lub zasad dotyczących dokumentów (nagłówek Document-Policy): nie musisz samodzielnie zmieniać tych nagłówków zasad po przejściu na interfejs Reporting API w wersji 1. Musisz tylko przejść ze starego nagłówka Report-To na nowy nagłówek Reporting-Endpoints.

Jeśli używasz starszego interfejsu Reporting API (wersja 0) do otrzymywania raportów o naruszeniu zasad dotyczących mechanizmu CSP (nagłówek Content-Security-Policy), w ramach migracji na nowy interfejs Reporting API (wersja 1) możesz potrzebować dostosowania Content-Security-Policy.

Migracja podstawowa

Kod starszy (w wersji 0)

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 wersji 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 w swojej witrynie masz już funkcję raportowania, zachowaj Report-To tylko tymczasowo (do czasu zaktualizowania większości klientów Chrome i Edge), aby nie stracić raportów.

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

Nowy kod (tylko w 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 obsługiwać będzie 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. Możesz jednak użyć tylko 1 adresu URL na punkt końcowy.

Obserwowanie wszystkich stron

Starszy kod (z wersją v0), na przykład w formacie Express

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

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

Nowy kod (z wersją 1), np. z 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 wersji 1 musisz ustawiać nagłówek Reporting-Endpoints we wszystkich odpowiedziach, które mogą generować raporty.

Migracja raportów CSP

Starszy kod, tylko z parametrem report-uri

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

Nie zalecamy już używać tylko pola report-uri. Jeśli Twój kod wygląda jak powyżej, przeprowadź migrację. Poniżej (na zielono) znajdziesz przykłady nowego kodu.

Ulepszony starszy kod z parametrem report-uri i dyrektywą report-to z nagłówkiem Report-To (w wersji 0).

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

Lepiej jest użyć kodu, który używa parametru report-to, który jest nowszą wersją parametru report-uri. W celu zachowania zgodności wstecznej nadal zachowuje parametr report-uri. Wiele przeglądarek nie obsługuje parametru report-to, ale obsługuje parametr report-uri.

Nadal może być inaczej: ten kod korzysta z interfejsu Reporting API w wersji 0 (nagłówek Report-To). Przejście na wersję 1: poniżej znajdziesz przykłady „Nowego kodu” (kolor zielony).

Nowy kod z parametrem report-uri i dyrektywą report-to z nagłówkiem Punkty końcowe raportowania (w wersji 1)

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

Stosuj dyrektywę report-uri wraz z dyrektywą report-to, dopóki dyrektywa report-to nie będzie obsługiwana w różnych przeglądarkach. Zobacz tabelę zgodności z przeglądarkami.

Tymczasowo Report-To będzie się znajdować obok Reporting-Endpoints. 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 Reporting API (główny post na temat interfejsu Reporting API)
• Specyfikacja: starsza wersja interfejsu API do raportowania (v0)
• Specyfikacja: nowy interfejs Reporting API (wersja 1)

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