Bu sayfa, Cloud Translation API ile çevrilmiştir.

Reporting API v1'e geçin

Reporting API'nin yeni bir sürümü mevcut. Daha gizlidir ve tarayıcılar arasında desteklenme olasılığı daha yüksektir.

Maud Nalpas

Reporting API, ziyaretçiler sitenizi kullanırken sitenizde gerçekleşen hatalar hakkında sizi bilgilendirir. Bu sayede tarayıcı müdahaleleri, tarayıcı kilitlenmeleri, İçerik-Güvenliği-Politika ihlalleri ve COOP/COEP ihlalleri, desteği sonlandırma uyarıları ve daha fazlası.

Reporting API'nin yeni bir sürümü mevcut. Yeni API daha yalındır ve muhtemelen tarayıcılarda desteklenir.

Özet

Site geliştiriciler

Siteniz için raporlama işlevine zaten sahipseniz: Yeni üst bilgiyi kullanarak v1'e geçin (Reporting-Endpoints) ancak eski başlığı bir süre daha saklayın (Report-To). Taşıma: örnek kod bölümünü inceleyin.

Sitenize şu anda raporlama işlevi ekliyorsanız: Yalnızca yeni başlığı kullanın (Reporting-Endpoints).

⚠️ Her iki durumda da, bunu etkileyebilecek tüm yanıtlarda Reporting-Endpoints başlığını ayarladığınızdan emin olun raporları oluşturun.

Raporlama hizmeti geliştiricileri

Bir uç nokta hizmeti sağlıyor veya kendiniz çalıştırıyorsanız daha fazla trafik bekleyebilirsiniz. veya harici geliştiriciler Reporting API v1'e (Reporting-Endpoints başlığı) geçiş yapar.

Ayrıntılar ve örnek kod için okumaya devam edin.

Ağ Hatası Günlük Kaydı

Dikkat: Ağ Hatası Günlük Kaydı kullanıyorsanız şunu kullanmaya devam edin: Reporting API v1'de Ağ Hatası Günlük Kaydı desteklenmediğinden Report-To (v0).

Ağ Hatası Günlük Kaydı için yeni bir mekanizma geliştirilecek. Bu kullanıma sunulduğunda Reporting API v0'dan bu yeni mekanizmaya geçin.

Demo ve kod

Demo site: yeni Reporting API (v1)
Demo site kodu

v0 ile v1 arasındaki farklar

Neler değişecek?

API yüzeyi farklıdır.

v0 (eski)

 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, adlandırılmış uç nokta gruplarını yapılandırmak için Report-To başlığını ve bu uç nokta gruplarına başvuruda bulunmak için diğer üstbilgilerdeki report-to yönergesini kullanır.

s1 (yeni)

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

v1, Reporting-Endpoints üst bilgisini uç noktalar. v0'da olduğu gibi, bu uç nokta gruplarına referans vermek için diğer üst bilgilerde report-to yönergesini kullanır.

Raporun kapsamı farklıdır.

v0 (eski)

v0 ile yalnızca bazı yanıtlarda raporlama uç noktaları ayarlayabilirsiniz. Bu konudaki diğer dokümanlar (sayfalar) başlangıç noktası otomatik olarak bu ortam uç noktalarını kullanır.

s1 (yeni)

v1 ile, aşağıdakilerin oluşturulmasına neden olabilecek tüm yanıtlarda Reporting-Endpoints başlığını ayarlamanız gerekir raporlar.

Her iki API de aynı rapor türlerini destekler, ancak bir istisna vardır: v1, Ağ Hatası raporlarını desteklemez. Daha fazla bilgi için taşıma adımlarına bakın.
v0 desteklenmez ve tarayıcılarda desteklenmez. v1'in desteklenme olasılığı daha yüksektir ileride birden fazla tarayıcıda.

Neler değişmedi?

Raporların biçimi ve yapısı değiştirilmemiştir.
Tarayıcı tarafından uç noktaya gönderilen istek, Content-type tutarındaki POST isteği olarak kalır application/reports+json.
Belirli uç noktaların belirli rapor türleriyle eşlenmesi hem v0 hem de v1'de desteklenir.
default uç noktasının rolü değişmez.
Reporting API v1'in ReportingObserver üzerinde herhangi bir etkisi yoktur. ReportingObserver, tüm gözlemlenebilir raporlara erişmeye devam ediyor. Bu raporların biçimi: aynı olmalıdır.

v0 ile v1 arasındaki tüm farklar

	Eski Reporting API (v0) `Report-To` üst bilgisi	Yeni Reporting API (v1) `Reporting-Endpoints` üst bilgisi
Tarayıcı desteği	Chrome 69 ve sonraki sürümler ve Edge 69 ve sonraki sürümler.	Chrome 96+ ve Edge 96+. Firefox destekleniyor. Safari itiraz etmiyor. Tarayıcı sinyalleri başlıklı makaleyi inceleyin.
Uç noktalar	Raporları birden fazla rapor toplayıcıdan herhangi birine gönderir (uç nokta grubu başına birden fazla URL tanımlanmış).	Raporları Belirli rapor toplayıcılara gönderir (uç nokta başına yalnızca bir URL tanımlar).
API yüzeyi	Adlandırılmış uç nokta gruplarını yapılandırmak için `Report-To` üstbilgisini kullanır.	Adlandırılmış uç noktaları yapılandırmak için `Reporting-Endpoints` başlığını kullanır.
Bu API aracılığıyla oluşturulabilecek rapor türleri	Kullanımdan Kaldırma Müdahale Kaza COOP/COEP İçerik Güvenliği Politikası Düzeyi 3 (İGP Düzeyi 3) Ağ Hatası Günlük Kaydı (NEL) ziyaret edin. _{Reporting API yayınından rapor türleri hakkında daha fazla bilgi edinebilirsiniz.}	Network Error Logging (NEL) hariç: Bu özellik yeni Reporting API'de (v1) desteklenmemektedir.
Rapor kapsamı	Kaynağınıza aitmiş gibi ele almasını sağlayan teknoloji. Bir dokümanın `Report-To` başlığı, söz konusu kaynaktaki diğer dokümanları (sayfalar) etkiler. Bir raporun `url` alanı yine de dokümana göre değişiklik gösterir.	Doküman. Bir dokümanın `Reporting-Endpoints` başlığı yalnızca söz konusu dokümanı etkiler. Bir raporun `url` alanı yine de dokümana göre değişiklik gösterir.
Rapor yalıtımı (toplu işlem)	Yaklaşık olarak aynı zamanda bir rapor oluşturan ve aynı raporlama uç noktasına sahip farklı belgeler (sayfalar) veya siteler/kaynaklar birlikte toplu halde toplanır: Bunlar, aynı mesaj içinde raporlama uç noktasına gönderilir.	Farklı dokümanlardan (sayfalar) alınan raporlar hiçbir zaman birlikte gönderilmez. Aynı kaynaktan iki doküman (sayfa) aynı anda bir rapor oluştursa bile aynı uç nokta için bunlar toplu olarak işlenmez. Bu, gizlilik saldırılarını hafifletmeye yönelik bir mekanizmadır. Aynı dokümandaki (sayfa) raporlar birlikte gönderilebilir.
Yük dengeleme / öncelikler için destek	Evet	Hayır

Uç nokta geliştiricileri: Daha fazla trafik bekleyin

Kendi sunucunuzu raporlama uç noktası olarak ayarladıysanız veya bir uç nokta için daha fazla trafik bekleyebilirsiniz.

Bunun nedeni, raporların Reporting API v0'da olduğu gibi Reporting API v1 ile toplu olarak gruplandırılmamasıdır. Dolayısıyla, Uygulama geliştiriciler Reporting API v1'e geçiş yaptıkça rapor sayısı Benzer kalır ancak uç nokta sunucusuna yapılan isteklerin hacmi artar.

Uygulama geliştiriciler: `Reporting-Endpoints` (v1) sürümüne geçiş yapın

Bu durumda ne yapmanız gerekir?

Yeni Reporting API'yi (v1) kullanmanın çeşitli avantajları vardır ✅:

Tarayıcı sinyalleri olumlu. Bu da v1 için (yalnızca Chrome ve Chrome'da desteklenen v0 sürümünden farklı olarak) Kenar).
API daha yalındır.
Araçlar, yeni Reporting API (v1) etrafında geliştiriliyor.

Bunu göz önünde bulundurarak:

Sitenizde Report-To başlığıyla birlikte Reporting API v0 kullanılıyorsa Reporting API v1 (taşıma adımlarına göz atın). Sitenizde zaten İçerik Güvenliği Politikası ihlallerini bildirme işlevi yerine İGP raporlaması için taşıma adımlarını inceleyin.
Sitenizde Raporlama API'si kullanılmıyorsa ve şimdi raporlama işlevi ekliyorsanız: yeni Reporting API'yi (v1) (Reporting-Endpoints başlığı) kullanmalıdır. Çünkü Çevik felsefesi için şunu kullanın: Ağ Hatası Günlük Kaydı kullanmanız gerekiyorsa Report-To (v0) kullanın. Ağ Hatası Günlük Kaydı Şu anda Reporting API v1'de desteklenmemektedir. Ağ Hatası Günlük Kaydı için yeni bir mekanizma, kullanıma sunulana kadar Reporting API v0'ı kullanın. Ağ Hatası Günlük Kaydına ihtiyacınız varsa Diğer rapor türlerinin yanında Report-To (v0) ve Reporting-Endpoints (v1) ikisini de kullanın. v0 Network Error Logging, v1 ise diğer tüm türlerin raporlarını sunar.

Taşıma adımları

Bu taşımadaki hedefiniz, v0 ile aldığınız raporları kaybetmemek.

1. Adım (şimdi yapın): Hem Report-To (v0) hem de Reporting-Endpoints (v1) üstbilgilerini kullanın.

Bu sayede:
- Reporting-Endpoints (v1) sayesinde yeni Chrome ve Edge istemcilerinden raporlar.
- Report-To (v0) sayesinde eski Chrome ve Edge istemcilerinden gelen raporlar.
Reporting-Endpoints destekleyen tarayıcı örnekleri, Reporting-Endpoints ve örnek olarak Report-To değerine yedeklenmez. İstek ve rapor biçimi, v0 ve v1.
2. Adım (şimdi yapın): Reporting-Endpoints üstbilgisinin rapor oluşturabilir.

v0 ile yalnızca bazı yanıtlarda ve diğer dokümanlarda raporlama uç noktaları ayarlamayı seçebilirsiniz. (sayfalar) bu "ambiyans"ı kullanır uç nokta. v1 ile birlikte kullanıldığında, oluşturabilirsiniz. Bu nedenle, gerçekleşebilecek tüm yanıtlarda Reporting-Endpoints başlığını raporlar.
3. Adım (daha sonra başlatın): Kullanıcılarınızın tümü veya çoğu daha sonra Chrome veya Edge'e güncellendikten sonra yüklemeleri (96 ve sonrası), Report-To (v0) kaldırın ve yalnızca Reporting-Endpoints değerini tutun.

Bir istisna: Ağ Hatası Günlük Kaydı raporlarına ihtiyacınız varsa yeni birReport-To Ağ Hatası Günlüğü için mekanizmanın uygulanmakta olduğunu gösterir.

Taşıma kılavuzundaki kod örneklerini inceleyin.

CSP raporlaması için taşıma adımları

Content-Security-Policy'nın iki şekilde ihlal raporları yapılandırılabilir:

report-uri yönergesi aracılığıyla yalnızca CSP başlığıyla. Bu özellik, Chrome, Firefox, Safari ve Edge. Raporlar, application/csp-report içerik türüyle gönderilir özel bir formatta olması gerekir. Bu raporlara "İGP Düzey 2 Raporları" adı verilir. ve Reporting API'ye bağımsız olmamalıdır.
Reporting API ile Report-To başlığı (eski) veya daha yeni Reporting-Endpoints (sürüm 1). Bu özellik yalnızca Chrome ve Edge'de desteklenir. Rapor isteklerinde diğer Reporting API istekleriyle aynı biçimde ve aynı içerik türü (application/reports+json) olmalıdır.

İlk yaklaşımı (yalnızca report-uri) kullanmanız artık önerilmez. İkinci yaklaşımın ise birkaç avantajı vardır. Özellikle, tüm rapor türleri için raporlamayı ayarlamak üzere tek bir yöntemden yararlanmanın yanı sıra genel bir uç nokta ayarlamanıza olanak tanır. Bunun nedeni, Reporting API⏤CSP ve diğer tüm rapor istekleri aynı biçimde application/reports+json olacaktır.

Ancak report-to özelliğini yalnızca birkaç tarayıcı destekler. Bu nedenle, Reporting API yaklaşımıyla (Report-To) birlikte report-uri değerini de kullanmanız önerilir. veya daha iyisi Reporting-Endpoints) kullanarak birden çok tarayıcıdan İGP ihlal raporları alabilirsiniz. report-uri ve report-to özelliklerini tanıyan tarayıcı, report-to ise report-uri yoksayılır olduğundan emin olun. Yalnızca report-uri adlı kullanıcıyı tanıyan bir tarayıcıda sadece report-uri dikkate alınır.

1. Adım (şimdi yapın): Henüz eklemediyseniz report-uri öğesinin yanına report-to ekleyin. Yalnızca report-uri'yi (Firefox) destekleyen tarayıcılar report-uri kullanır ve aynı zamanda desteği report-to(Chrome, Edge) report-to kullanacak. Kullanacağınız adlandırılmış uç noktaları belirtmek için report-to içinde hem Report-To hem de Reporting-Endpoints başlığını kullanın. Bu sayede hem eski hem de yeni Chrome ve Edge istemcilerinden gelen raporları görebilirsiniz.
3. Adım (daha sonra başlatın): Kullanıcılarınızın tümü veya çoğu daha sonra Chrome veya Edge'e güncellendikten sonra yüklemeleri (96 ve sonrası), Report-To (v0) kaldırın ve yalnızca Reporting-Endpoints değerini tutun. Sakla report-uri. Böylece yalnızca bu uzantıyı destekleyen tarayıcılar hakkında raporlar almaya devam edersiniz.

Bu adımlarla ilgili kod örneklerini İGP raporlamasının taşınması bölümünde bulabilirsiniz.

Taşıma: Örnek kod

Genel Bakış

COOP için ihlal raporları almak üzere eski Reporting API'yi (v0) kullanıyorsanız (Cross-Origin-Opener-Policy başlığı), bir COEP (Cross-Origin-Embedder-Policy) veya belge politikası (Document-Policy başlığı): Taşıma sırasında bu politika başlıklarını değiştirmeniz gerekmez Reporting API v1'e geri yükleyin. Yapmanız gereken, eski Report-To başlığından yeni Reporting-Endpoints üstbilgisi.

İGP için ihlal raporları almak üzere eski Reporting API'yi (v0) kullanıyorsanız (Content-Security-Policy üstbilgisi), şunun bir parçası olarak Content-Security-Policy üzerinde değişiklik yapmanız gerekebilir: yeni Reporting API'ye (v1) geçişiniz.

Temel taşıma

Eski kod (v0 ile)

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

Yeni kod (v1 yanında v0 ile geçiş kodu)

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

Sitenizde raporlama işlevi varsa Report-To özelliğini yalnızca geçici olarak saklayın (çoğu Chrome ve Edge istemcisi güncellenene kadar).

Ağ Hatası Günlük Kaydı'na ihtiyacınız varsa Ağ Hatası Günlük Kaydı yenilenene kadar Report-To değerini koruyun kullanılabilir hale gelir.

Yeni kod (yalnızca v1 ile)

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

Chrome ve Edge istemcilerinin çoğu güncellendikten ve API v1'i desteklediğinde kodunuz gelecekte bu şekilde görünür.

v1 ile belirli rapor türlerini belirli uç noktalara göndermeye devam edebileceğinizi unutmayın. Ancak siz uç nokta başına yalnızca bir URL'ye sahip olabilir.

Tüm sayfalar gözlemleniyor

Eski kod (v0 ile), örneğin Express ile

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

v0 ile yalnızca bazı yanıtlarda raporlama uç noktaları ayarlayabilirsiniz. Diğer ilgili kaynaktaki dokümanlar (sayfalar) otomatik olarak bu ortam uç noktalarını kullanır. Burada, ayarlanan uç noktalar "/" tüm yanıtlar için kullanılır, örneğin page1.

Yeni kod (v1 ile), örneğin Express için

// 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'de Reporting-Endpoints başlığını tüm yanıt verebilir.

CSP raporlarını taşıma

Eski kod, yalnızca rapor URI'si ile

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

Yalnızca report-uri kullanımı artık geçerli değil önerilir. Kodunuz yukarıdaki gibi görünüyorsa taşıyın. Aşağıdaki Yeni kod örneklerine (yeşil renkte) bakın.

Daha iyi eski kod, report-uri ve report-to yönergesi içeren Report-To (v0) üstbilgisi

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

Bu daha iyidir: Bu kod, report-uri. Geriye dönük uyumluluk için rapor URI'sini korur; birkaç tarayıcı tarafından desteklenmiyor report-to ama destekleme report-uri.

Yine de bu daha iyi olabilir: Bu kodlar Reporting API v0'ı (Report-To başlığı) kullanır. v1'e taşıma: "Yeni kod" aşağıdaki örnekler (yeşil) arasında gösterilir.

Reporting-Endpoints (v1) üstbilgisine sahip report-uri ve report-to yönergesini içeren yeni kod

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 yönergesini, report-to yönergesi olana kadar report-to yönergesiyle birlikte koruyun tüm tarayıcılarda desteklenir. Bkz. tarayıcı uyumluluğu tablosunu inceleyin.

Report-To öğesini geçici olarak Reporting-Endpoints ile birlikte tutun. Chrome ve Edge cihazınızda Ziyaretçiler 96'dan fazla tarayıcı sürümüne geçti, Report-To sürümünü kaldırın.

Daha fazla bilgi

Web uygulamanızı Reporting API ile izleme (Reporting API'deki ana yayın)
Spesifikasyon: eski Reporting API (v0)
Spesifikasyon: yeni Reporting API (v1)

Nine Koepfer / @enka80'in hero resmi Unsplash, düzenlendi. Ian'ın sayesinde Clelland, Eiji Kitamura ve Milica Mihajlija bu konuyla ilgili incelemeleri ve önerileri için bulabilirsiniz.