Reporting API v1 に移行する

新しいバージョンの Reporting API をご利用いただけます。機密性が高いため、ブラウザ間でサポートされる可能性が高くなります。

Maud Nalpas

Reporting API は、ユーザーがサイトを使用するときにサイトで発生したエラーを通知します。与えられるもの ブラウザへの介入、ブラウザのクラッシュ、コンテンツ セキュリティ ポリシー違反、 COOP/COEP 違反、非推奨の警告など。

新しいバージョンの Reporting API をご利用いただけます。新しい API はより無駄がなく、 対応しています。

概要

サイト デベロッパー

サイトですでにレポート機能をご利用の場合: 新しいヘッダーを使用して v1 に移行します （Reporting-Endpoints）。ただし、しばらくは以前のヘッダーを維持します（Report-To）。 移行: サンプルコードをご覧ください。

今すぐサイトにレポート機能を追加する場合: 新しいヘッダーのみを使用してください。 （Reporting-Endpoints）。

いずれの場合も、メールに含まれる可能性のあるすべてのレスポンスに Reporting-Endpoints ヘッダーを設定してください。 レポートの生成

レポート サービス デベロッパー

エンドポイント サービスを管理している場合や独自のエンドポイントを運用している場合は、エンドポイント サービスの使用に伴いトラフィックの増加が予想されます。 または外部のデベロッパーが Reporting API v1（Reporting-Endpoints ヘッダー）に移行する場合。

詳細とサンプルコードについては、以下をご確認ください。

ネットワーク エラーのロギング

ネットワーク エラーロギングの新しいメカニズムが開発されます。この機能が利用可能になったら、Reporting API v0 からこの新しいメカニズムに切り替えてください。

デモとコード

• デモサイト: 新しい Reporting API（v1）
• デモサイトのコード

v0 と v1 の違い

変更点

• API サーフェスは異なります。

 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

• レポートの範囲は異なります。

• どちらの API も同じレポートタイプをサポートしていますが、1 つの例外として、v1 ではネットワーク エラーレポートはサポートされていません。詳しくは、移行手順をご覧ください。
• v0 はサポートされておらず、複数のブラウザではサポートされません。バージョン 1 は、 複数のブラウザに対応できます

これまでと変わらない点

• レポートの形式と構造に変更はありません。
• ブラウザからエンドポイントに送信されたリクエストは、引き続き Content-type の POST リクエストになります。 application/reports+json。
• 特定のエンドポイントの特定のレポートタイプへのマッピングは、v0 と v1 の両方でサポートされています。
• default エンドポイントのロールは変更されません。

• Reporting API v1 は ReportingObserver には影響しません。 ReportingObserver は、すべての観測可能なレポートに引き続きアクセスできます。形式は以下のようになります。 あります。

v0 と v1 のすべての違い

エンドポイント デベロッパー: トラフィックの増加が予想される

独自のサーバーをレポート エンドポイントとして設定している場合、または そのエンドポイントへのトラフィックが増えることが予想されます。

これは、Reporting API v0 とは異なり、Reporting API v1 ではレポートがバッチ処理されないためです。したがって、 アプリケーション デベロッパーが Reporting API v1 への移行を開始すると、レポートの数は エンドポイント サーバーへのリクエストの量は増加する。

アプリケーション デベロッパー: Reporting-Endpoints（v1）に移行する

どうすればよいですか。

新しい Reporting API（v1）を使用すると、次のようなメリットがあります ✅:

• ブラウザのシグナルはポジティブです。つまり、 v1 ではクロスブラウザ サポートが期待できる点に注意が必要です（Chrome と Edge）。
• API の方が効率的です。
• 現在、新しい Reporting API（v1）を中心とするツールを開発中です。

これを踏まえると以下のようになります。

• サイトですでに Reporting API v0 と Report-To ヘッダーを使用している場合は、 Reporting API v1（移行手順をご覧ください）。サイトですでに コンテンツ セキュリティ ポリシー違反に関する報告機能を使用する場合は、CSP レポートの移行手順を確認してください。
• サイトでまだ Reporting API を使用していない場合にレポート機能を追加する場合: 新しい Reporting API（v1）（Reporting-Endpoints ヘッダー）を使用する。例外が 1 つあり、 : ネットワーク エラー ロギングを使用する必要がある場合は、Report-To（v0）を使用します。ネットワーク エラーのロギング Reporting API v1 ではサポートされていません。ネットワーク エラー ロギングの新しいメカニズムは、 利用可能になるまで、Reporting API v0 を使用してください。ネットワーク エラー ロギングが必要な場合 他のレポートタイプと一緒に使用する場合は、Report-To（v0）と Reporting-Endpoints（v1）の両方を使用します。v0 v1 ではネットワーク エラー ロギング、v1 ではその他すべてのタイプのレポートが提供されます。

移行手順

この移行の目標は、v0 で取得していたレポートが失われるのを防ぐことです。

1. ステップ 1（今すぐ実行）: Report-To（v0）と Reporting-Endpoints（v1）の両方のヘッダーを使用します。

   これにより、以下が得られます。

   • Reporting-Endpoints（v1）を利用した新しい Chrome および Edge クライアントからのレポート。
   • Report-To（v0）により古い Chrome および Edge クライアントからレポートされたレポート。

   Reporting-Endpoints をサポートするブラウザ インスタンスは Reporting-Endpoints を使用します。また、 そうでないインスタンスは Report-To にフォールバックします。リクエストとレポートの形式は、 比較します。

2. ステップ 2（今すぐ）:Reporting-Endpoints レポートを生成できます。

   v0 では、一部のレスポンスのみにレポート エンドポイントを設定し、他のドキュメントには （ページ）はこの「アンビエント」を使用します提供しますバージョン 1 では、 スコープ設定のため、生成される可能性のあるすべてのレスポンスに Reporting-Endpoints ヘッダーを設定する必要があります。 できます。

3. 手順 3（後で開始）: すべてまたは大部分のユーザーが新しい Chrome または Edge にアップデートされたら インストール（96 以降）の場合は、Report-To（v0）を削除して Reporting-Endpoints のみを残します。

   例外として、ネットワーク エラー ロギングのレポートが必要な場合は、Report-To は新しい ネットワーク エラー ロギングのメカニズムが備わっています。

移行クックブックのコードサンプルを確認する。

CSP レポートの移行手順

Content-Security-Policy と、 違反レポートは次のように設定できます。

• report-uri ディレクティブを介した CSP ヘッダーのみ。このプラットフォームは Chrome、Firefox、Safari、Edge。レポートは、コンテンツ タイプ application/csp-report で送信されます。 CSP 固有の形式になっている必要がありますこれらのレポートは「CSP レベル 2 レポート」と呼ばれます。そして Reporting API に依存しないでください。
• Reporting API の場合は、Report-To ヘッダー（従来版）以降を使用 Reporting-Endpoints（v1）。これは Chrome と Edge でのみサポートされています。レポート リクエストには 他の Reporting API リクエストと同じ形式、同じコンテンツ タイプの application/reports+json。

最初の方法（report-uri のみ）を使用することは非推奨になりました。2 つ目の方法を使用すると、いくつかのメリットがあります。特に、すべてのレポートタイプに対して 1 つの方法でレポートを設定できるほか、汎用エンドポイントも設定できます（Reporting API やその他を介して生成されたレポート リクエストはすべて同じ形式 application/reports+json であるため）。

ただし、report-to をサポートしているブラウザは限られています。 そのため、report-uri は Reporting API のアプローチ（Report-To Reporting-Endpoints 以上）を使用して、複数のブラウザから CSP 違反レポートを取得する必要があります。新しい report-uri と report-to を認識するブラウザ（report-to の場合、report-uri は無視されます） あります。report-uri のみを認識するブラウザでは、report-uri のみが考慮されます。

1. ステップ 1（今すぐ行う）: まだ追加していない場合は、report-uri と report-to を追加します。 report-uri のみをサポートするブラウザ（Firefox）では report-uri が使用されます。また、 サポートreport-to（Chrome、Edge）では report-to を使用します。使用する名前付きエンドポイントを指定するには、 report-to では、Report-To と Reporting-Endpoints の両方のヘッダーを使用します。これにより 新旧両方の Chrome および Edge クライアントからのレポートを作成できます。

2. 手順 3（後で開始）: すべてまたは大部分のユーザーが新しい Chrome または Edge にアップデートされたら インストール（96 以降）の場合は、Report-To（v0）を削除して Reporting-Endpoints のみを残します。維持 report-uri のみをサポートしているブラウザのレポートは引き続き表示できます。

これらの手順のコードサンプルについては、CSP レポートの移行をご覧ください。

移行: サンプルコード

概要

以前の Reporting API（v0）を使用して COOP の違反レポートを取得している場合 （Cross-Origin-Opener-Policy ヘッダー）、COEP（Cross-Origin-Embedder-Policy）、またはドキュメント ポリシー （Document-Policy ヘッダー）: 移行時にこれらのポリシー ヘッダー自体を変更する必要はありません。 Reporting API v1 にアップグレードされます。必要なのは、以前の Report-To ヘッダーを新しいヘッダーに移行する必要があります。 Reporting-Endpoints ヘッダー。

以前の Reporting API（v0）を使用して CSP の違反レポートを取得している場合 （Content-Security-Policy ヘッダー）、Content-Security-Policy 新しい Reporting API（v1）への移行をご完了ください。

基本的な移行

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"

v1 でも、特定のレポート タイプを特定のエンドポイントに送信できます。でも、 エンドポイントごとに 1 つの URL のみを指定できます。

すべてのページを監視する

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

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

関連情報

• Reporting API を使ったウェブ アプリケーションのモニタリング（Reporting API に関するメイン投稿）
• 仕様: 以前の Reporting API（v0）
• 仕様: 新しい Reporting API（v1）

ヒーロー画像提供: Nine Koepfer / @enka80 スプラッシュを解除、編集。伊藤様に心より感謝申し上げます Clelland、Eiji Kitamura、Miliica Mihajlija によるレビューと提案 記事をご覧ください。