Przejdź na interfejs API do raportowania w wersji 1

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.

Maud Nalpas

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

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

• Zakres tego raportu jest inny.

• 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ś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 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. Organizacja ReportingObserver nadal ma dostęp do wszystkich dostrzegalnych raportów, a jej format to identyczna.

Wszystkie różnice między v0 a v1

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żyj Report-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) i Reporting-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.

1. Krok 1 (zrób teraz). Użyj obu nagłówków: Report-To (wersja 0) i Reporting-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.

2. 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.

3. 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 tylko Reporting-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ści application/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ści application/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.

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 obsługujące tylko report-uri (Firefox) będą używać report-uri, a także przeglądarki, które również obsługa report-to(Chrome, Edge) będzie używać report-to. Aby określić nazwane punkty końcowe, których użyjesz w pliku report-to użyj nagłówków Report-To i Reporting-Endpoints. Dzięki temu uzyskasz ze starszych i nowszych klientów Chrome i Edge.

2. 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 tylko Reporting-Endpoints. Google Keep report-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" }] }

Reporting-Endpoints: main-endpoint="https://reports.example/main", default="https://reports.example/default"

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(...)
});

// 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 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ł.