이 페이지는 Cloud Translation API를 통해 번역되었습니다.

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 헤더)로 이전할 수 있습니다.

자세한 내용과 코드 예를 보려면 계속 읽어보세요.

네트워크 오류 로깅

주의: 네트워크 오류 로깅을 사용하는 경우 Report-To (v0) - Reporting API v1에서 네트워크 오류 로깅이 지원되지 않기 때문입니다.

네트워크 오류 로깅을 위한 새로운 메커니즘이 개발될 예정입니다. 이를 사용할 수 있게 되면 Reporting API v0에서 새로운 메커니즘으로 전환하세요.

데모 및 코드

데모 사이트: 새 Reporting API (v1)
데모 사이트의 코드

v0과 v1의 차이점

변경사항

API 노출 영역은 다릅니다.

v0 (기존)

 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은 Report-To 헤더를 사용하여 이름이 지정된 엔드포인트 그룹을 구성하고 다른 헤더의 report-to 지시문을 사용하여 이러한 엔드포인트 그룹을 참조합니다.

v1 (신규)

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

v1은 Reporting-Endpoints 헤더를 사용하여 엔드포인트입니다. v0과 마찬가지로 다른 헤더의 report-to 지시문을 사용하여 이러한 엔드포인트 그룹을 참조합니다.

보고서의 범위가 다릅니다.

v0 (기존)

v0에서는 일부 응답에 대해서만 보고 엔드포인트를 설정할 수 있습니다. 관련된 다른 문서 (페이지) 출처에서 자동으로 이러한 대기 엔드포인트를 사용합니다.

v1 (신규)

v1에서는 생성할 수 있는 모든 응답에 Reporting-Endpoints 헤더를 설정해야 합니다. 있습니다.

두 API 모두 동일한 보고서 유형을 지원하지만 v1에서는 네트워크 오류 보고서를 지원하지 않습니다. 자세한 내용은 이전 단계를 참고하세요.
v0는 지원되지 않으며 여러 브라우저에서 지원되지 않습니다. v1이 지원될 가능성이 더 높음 지원될 예정입니다.

변경되지 않는 사항

보고서의 형식과 구조는 변경되지 않았습니다.
브라우저에서 엔드포인트로 보낸 요청은 Content-type의 POST 요청으로 유지됩니다. application/reports+json입니다.
특정 엔드포인트를 특정 보고서 유형에 매핑하는 기능은 v0 및 v1에서 모두 지원됩니다.
default 엔드포인트의 역할은 변경되지 않습니다.
Reporting API v1은 ReportingObserver에 영향을 미치지 않습니다. ReportingObserver에서는 관찰 가능한 모든 보고서에 계속 액세스할 수 있으며 형식은 다음과 같습니다. 동일합니다.

v0과 v1의 모든 차이점

	기존 Reporting API (v0) `Report-To` 헤더	새 Reporting API (v1) `Reporting-Endpoints` 헤더
브라우저 지원	Chrome 69 이상 및 Edge 69 이상	Chrome 96 이상 및 Edge 96 이상 Firefox가 지원됩니다. Safari는 이에 반대하지 않습니다. 브라우저 신호를 참고하세요.
엔드포인트	여러 보고서 수집기 (엔드포인트 그룹당 여러 URL 정의됨) 중 하나로 보고서를 전송합니다.	특정 보고서 수집기에 보고서를 전송합니다 (엔드포인트당 하나의 URL만 정의됨).
API 노출 영역	`Report-To` 헤더를 사용하여 이름이 지정된 엔드포인트 그룹을 구성합니다.	`Reporting-Endpoints` 헤더를 사용하여 이름이 지정된 엔드포인트를 구성합니다.
이 API를 통해 생성할 수 있는 보고서 유형	지원 중단 개입 교통사고 COOP/COEP 콘텐츠 보안 정책 수준 3 (CSP 수준 3) 네트워크 오류 로깅 (NEL) 를 통해 개인정보처리방침을 정의할 수 있습니다. _{Reporting API 게시물에서 보고서 유형에 대해 자세히 알아보세요.}	네트워크 오류 로깅 (NEL)을 제외하고 변경되지 않음: 새 Reporting API (v1)에서 지원되지 않습니다.
보고서 범위	원본에 속한 것으로 처리하는 기술입니다. 문서의 `Report-To` 헤더는 해당 출처의 다른 문서 (페이지)에 영향을 미칩니다. 보고서의 `url` 필드는 문서마다 다릅니다.	문서. 문서의 `Reporting-Endpoints` 헤더는 해당 문서에만 영향을 미칩니다. 보고서의 `url` 필드는 문서마다 다릅니다.
보고서 격리 (일괄 처리)	거의 동시에 보고서를 생성하고 동일한 보고 엔드포인트를 갖는 서로 다른 문서 (페이지) 또는 사이트/원본은 함께 일괄 처리되며, 동일한 메시지로 보고 엔드포인트로 전송됩니다.	다른 문서 (페이지)의 보고서는 함께 전송되지 않습니다. 동일한 출처의 두 문서 (페이지)가 동시에 보고서를 생성하더라도 동일한 엔드포인트에 대해서는 일괄 처리되지 않습니다. 이는 개인 정보 보호 공격을 완화하는 메커니즘입니다. 동일한 문서 (페이지)의 보고서가 함께 전송될 수 있습니다.
부하 분산 / 우선순위 지원	예	아니요

엔드포인트 개발자: 트래픽 증가 예상

자체 서버를 보고 엔드포인트로 설정했거나 보고서 수집기를 서비스로 사용하면 해당 엔드포인트에 더 많은 트래픽이 발생할 것으로 예상됩니다.

이는 Reporting API v0에서와 같이 Reporting API v1에서 보고서가 일괄 처리되지 않기 때문입니다. 따라서 애플리케이션 개발자가 Reporting API v1로 이전을 시작하면 보고서의 수가 비슷하지만 엔드포인트 서버에 대한 요청 볼륨이 증가합니다.

애플리케이션 개발자: `Reporting-Endpoints` (v1)로 이전

어떻게 해야 할까요?

새 Reporting API (v1)를 사용하면 다음과 같은 몇 가지 이점이 있습니다 ✅:

브라우저 신호가 긍정적입니다. 즉, 교차 브라우저 지원이 v1에 대해 예상될 수 있다는 것을 발견했습니다. Edge).
API가 더 가볍습니다.
도구는 새로운 Reporting API (v1)를 중심으로 개발되고 있습니다.

이를 기준으로 보면 다음과 같습니다.

사이트에서 이미 Report-To 헤더가 있는 Reporting API v0을 사용하고 있다면 Reporting API v1 (이전 단계 참고) 사이트에서 이미 자세한 내용은 CSP 신고의 이전 단계를 확인하세요.
사이트에서 아직 Reporting API를 사용하지 않고 현재 보고 기능을 추가하는 경우 다음 단계를 따르세요. 새 Reporting API (v1) (Reporting-Endpoints 헤더)를 사용해야 합니다. 한 가지 예외가 있는데 이: 네트워크 오류 로깅을 사용해야 하는 경우 Report-To (v0)를 사용하세요. 네트워크 오류 로깅 는 Reporting API v1에서 지원되지 않습니다. 네트워크 오류 로깅을 위한 새로운 메커니즘은 사용할 수 있을 때까지 Reporting API v0을 사용하세요. 네트워크 오류 로깅이 필요한 경우 다른 보고서 유형과 함께 Report-To (v0) 및 Reporting-Endpoints (v1)을 모두 사용하세요. v0 네트워크 오류 로깅을 제공하고 v1은 기타 모든 유형의 보고서를 제공합니다.

이전 단계

이번 이전의 목표는 v0에서 제공되던 보고서가 손실되지 않도록 하는 것입니다.

1단계 (지금 실행): Report-To (v0) 및 Reporting-Endpoints (v1) 헤더를 모두 사용합니다.

다음과 같은 이점이 있습니다.
- Reporting-Endpoints (v1) 덕분에 최신 Chrome 및 Edge 클라이언트에서 보고되었습니다.
- Report-To (v0) 덕분에 이전 Chrome 및 Edge 클라이언트에서 보고되었습니다.
Reporting-Endpoints을(를) 지원하는 브라우저 인스턴스는 Reporting-Endpoints을(를) 사용합니다. 그렇지 않은 인스턴스는 Report-To로 대체됩니다. 요청 및 보고서 형식은 v0 및 v1입니다.
2단계 (지금 실행): Reporting-Endpoints 헤더가 보고서를 생성할 수 있습니다

v0에서는 일부 응답에 대해서만 보고 엔드포인트를 설정하도록 선택할 수 있었습니다. (페이지)가 이 '분위기'를 사용합니다. 할 수 있습니다 v1에서는 범위 지정을 사용하려면 생성할 수 있는 모든 응답에 Reporting-Endpoints 헤더를 설정해야 합니다. 있습니다.
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 사용 시 Report-To 헤더 (기존) 이상을 통해 Reporting-Endpoints (v1) 이 기능은 Chrome 및 Edge에서만 지원됩니다. 보고서 요청에는 다른 Reporting API 요청과 동일한 형식 및 동일한 콘텐츠 유형 application/reports+json를 제공합니다.

첫 번째 접근 방식 (report-uri만)을 사용하는 것은 더 이상 권장되지 않으며 두 번째 접근 방식을 사용하면 몇 가지 이점이 있습니다. 특히 Reporting API⏤CSP 및 기타 항목을 통해 생성된 모든 보고서 요청의 application/reports+json 형식이 동일하므로 모든 보고서 유형에 대한 보고서를 설정하고 일반 엔드포인트를 설정하는 단일 방법을 사용할 수 있습니다.

그러나 report-to를 지원하는 브라우저에서만 지원됩니다. 따라서 Reporting API 접근 방식 (Report-To)과 함께 report-uri를 유지하는 것이 좋습니다. 이상(Reporting-Endpoints)이어야 합니다. report-uri 및 report-to를 인식하는 브라우저이므로 report-to인 경우 report-uri는 무시됩니다. 있습니다. report-uri만 인식하는 브라우저에서는 report-uri만 고려됩니다.

1단계 (지금 실행): 아직 추가하지 않았다면 report-uri와 함께 report-to를 추가합니다. report-uri만 지원하는 브라우저(Firefox)에서 report-uri을(를) 사용하며, 다른 브라우저에서도 report-uri을(를) 사용하게 됩니다. 지원report-to(Chrome, Edge)에서는 report-to을 사용합니다. 이름이 지정된 엔드포인트를 지정하려면 다음을 사용합니다. report-to에서 Report-To 헤더와 Reporting-Endpoints 헤더를 모두 사용합니다. 이렇게 하면 이전 및 최신 Chrome 및 Edge 클라이언트 모두의 보고서를 제공합니다.
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)로 이전해야 합니다.

기본 마이그레이션

기존 코드 (v0 포함)

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

새 코드 (v0과 v1을 함께 사용하는 전환 코드)

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" }] }

사이트에 이미 보고 기능이 있는 경우 Report-To를 일시적으로만 유지하세요. (대부분의 Chrome 및 Edge 클라이언트가 업데이트될 때까지) 보고서 손실을 방지합니다.

네트워크 오류 로깅이 필요한 경우 네트워크 오류 로깅을 대체할 때까지 Report-To를 유지하세요. 출시됩니다.

새 코드 (v1에만 해당)

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

대부분의 Chrome 및 Edge 클라이언트가 업데이트되고 API v1을 지원하게 되면 향후 코드의 모습은 다음과 같습니다.

v1에서도 특정 보고서 유형을 특정 엔드포인트에 보낼 수 있습니다. 하지만 너는 엔드포인트당 하나의 URL만 포함할 수 있습니다.

모든 페이지 관찰

기존 코드(v0 사용)(예: Express 사용)

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

v0에서는 일부 응답에 대해서만 보고 엔드포인트를 설정할 수 있습니다. 기타 해당 출처의 문서 (페이지)가 자동으로 이러한 대기 엔드포인트를 사용합니다. 여기서 엔드포인트는 "/"는 모든 응답에 사용됩니다(예: page1).

새 코드(v1 사용)(예: 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(...)
});

v1에서는 모든 URL에 Reporting-Endpoints 헤더를 설정해야 합니다. 보고서를 생성할 수 있습니다.

CSP 보고 이전

기존 코드(report-uri 전용)

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

더 이상 report-uri만 사용할 수 없습니다. 권장 코드가 위와 같으면 이전합니다. 아래의 새로운 코드 예 (녹색)를 참고하세요.

기존 코드(report-uri 및 report-to 지시문)를 다음과 같이 개선 Report-To (v0) 헤더

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

이 코드는 report-uri를 사용하세요. 이전 버전과의 호환성을 위해 report-uri를 계속 유지합니다. 여러 개 브라우저에서 report-to 드림 CANNOT TRANSLATE report-uri

그래도 더 나을 수 있습니다. 이 코드는 Reporting API v0 (Report-To 헤더)를 사용합니다. v1로 이전: '새 코드' (녹색으로 표시)

Reporting-Endpoint (v1) 헤더가 있는 report-uri 및 report-to 지시문을 포함한 새 코드

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

report-uri 지시어는 report-to 지시어가 나올 때까지 report-to 지시어와 함께 유지합니다. 여러 브라우저에서 지원됩니다 자세한 내용은 브라우저 호환성 표를 참조하세요.

Report-To을(를) Reporting-Endpoints와 함께 일시적으로 보관합니다. 대부분의 Chrome 및 Edge 방문자가 96개 이상의 브라우저 버전으로 업그레이드했습니다. Report-To을(를) 삭제하세요.

추가 자료

Reporting API로 웹 애플리케이션 모니터링 (Reporting API의 기본 게시물)
사양: 기존 Reporting API (v0)
사양: 새로운 Reporting API (v1)

히어로 이미지: Nine Koepfer / @enka80 Unsplash, 수정됨 많은 분들께 감사드립니다. Clelland, Eiji Kitamura, Milica Mihajlija가 이에 대한 리뷰와 제안을 제공해 주었습니다. 도움말을 참고하세요.