chrome.declarativeWebRequest

refresh date: 2026-09-25 robots: noindex

Açıklama

Not: Bu API'nin desteği sonlandırılmıştır. Bunun yerine declarativeNetRequest API'yi inceleyin. Devam eden istekleri yakalamak, engellemek veya değiştirmek için chrome.declarativeWebRequest API'yi kullanın. chrome.webRequest API'den önemli ölçüde daha hızlıdır. Bunun nedeni, gidiş dönüş gecikmelerini azaltan ve daha yüksek verimlilik sağlayan JavaScript motoru yerine tarayıcıda değerlendirilen kurallar kaydedebilmenizdir.

İzinler

declarativeWebRequest

Bu API'yi kullanmak için ana makine izinleriyle birlikte uzantı manifestinde "declarativeWebRequest" iznini beyan etmeniz gerekir.

{
  "name": "My extension",
  ...
  "permissions": [
    "declarativeWebRequest",
    "*://*/*"
  ],
  ...
}

Kullanılabilirlik

Beta kanalı ≤ MV2

Manifest

Belirli hassas olmayan işlemler için düzenleyen kullanıcı izinlerinin gerekmediğini unutmayın:

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

SendMessageToExtension() işlemi, ağ istekleri için mesaj tetiklemek istediğiniz tüm ana makineler için ana makine izinleri gerektirir.

Diğer tüm işlemler için tüm URL'lerde ana makine izinleri gerekir.

Örneğin, bir uzantının sahip olduğu tek ana makine izni "https://*.google.com/*" ise bu uzantı, aşağıdaki işlemleri yapacak bir kural oluşturabilir:

  • https://www.google.com veya https://anything.else.com için yapılan bir isteği iptal etme
  • https://www.google.com konumuna giderken mesaj gönderilir ancak https://something.else.com konumuna giderken gönderilmez.

Uzantı, https://www.google.com adresini https://mail.google.com adresine yönlendirecek bir kural oluşturamıyor.

Kurallar

Bildirimsel Web İsteği API'si, Bildirimsel API'nin kavramlarını izler. chrome.declarativeWebRequest.onRequest etkinlik nesnesine kurallar kaydedebilirsiniz.

Bildirimsel Web İsteği API'si, tek bir eşleşme ölçütü türünü (RequestMatcher) destekler. RequestMatcher, yalnızca listelenen tüm ölçütler karşılandığında ağ istekleriyle eşleşir. Aşağıdaki RequestMatcher, kullanıcı çok amaçlı adres çubuğuna https://www.example.com yazdığında bir ağ isteğiyle eşleşir:

var matcher = new chrome.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com', schemes: ['http'] },
  resourceType: ['main_frame']
});

https://www.example.com için yapılan istekler, şema nedeniyle RequestMatcher tarafından reddedilir. Ayrıca, yerleştirilmiş bir iFrame'e yönelik tüm istekler resourceType nedeniyle reddedilir.

"example.com"a yapılan tüm istekleri iptal etmek için kuralı aşağıdaki gibi tanımlayabilirsiniz:

var rule = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

example.com ve foobar.com ile ilgili tüm istekleri iptal etmek için ikinci bir koşul ekleyebilirsiniz. Her koşul, belirtilen tüm işlemleri tetiklemek için yeterlidir:

var rule2 = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } }),
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'foobar.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

Kuralları aşağıdaki gibi kaydedin:

chrome.declarativeWebRequest.onRequest.addRules([rule2]);

Koşulların ve işlemlerin değerlendirilmesi

Bildirimsel Web İsteği API'si, Web Request API'nin Web istekleri için yaşam döngüsü modelini izler. Bu nedenle, koşullar yalnızca bir web isteğinin belirli aşamalarında test edilebilir ve işlemler de yalnızca belirli aşamalarda yürütülebilir. Aşağıdaki tablolarda, koşullar ve işlemlerle uyumlu istek aşamaları listelenmiştir.

Koşul özelliklerinin işlenebileceği istek aşamaları.
Durum özelliği onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
url ✓ ✓ ✓ ✓
resourceType ✓ ✓ ✓ ✓
contentType ✓
excludeContentType ✓
responseHeaders ✓
excludeResponseHeaders ✓
requestHeaders ✓
excludeRequestHeaders ✓
thirdPartyForCookies ✓ ✓ ✓ ✓
İşlemlerin yürütülebileceği istek aşamaları.
Etkinlik onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
AddRequestCookie ✓
AddResponseCookie ✓
AddResponseHeader ✓
CancelRequest ✓ ✓ ✓ ✓
EditRequestCookie ✓
EditResponseCookie ✓
IgnoreRules ✓ ✓ ✓ ✓
RedirectByRegEx ✓ ✓
RedirectRequest ✓ ✓
RedirectToEmptyDocument ✓ ✓
RedirectToTransparentImage ✓ ✓
RemoveRequestCookie ✓
RemoveRequestHeader ✓
RemoveResponseCookie ✓
RemoveResponseHeader ✓
SendMessageToExtension ✓ ✓ ✓ ✓
SetRequestHeader ✓

Kuralları geçersiz kılmak için öncelikleri kullanma

Kurallar, Events API'de açıklandığı şekilde önceliklerle ilişkilendirilebilir. Bu mekanizma, istisnaları ifade etmek için kullanılabilir. Aşağıdaki örnek, "myserver.com" sunucusu hariç evil.jpg adlı resimlere yapılan tüm istekleri engeller.

var rule1 = {
  priority: 100,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
        url: { pathEquals: 'evil.jpg' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};
var rule2 = {
  priority: 1000,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: '.myserver.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.IgnoreRules({
      lowerPriorityThan: 1000 })
  ]
};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

IgnoreRules işleminin istek aşamalarında kalıcı olmadığını unutmayın. Tüm kuralların tüm koşulları, bir web isteğinin her aşamasında değerlendirilir. Bir IgnoreRules işlemi yürütülürse bu işlem yalnızca aynı aşamada aynı web isteği için yürütülen diğer işlemler için geçerli olur.

Türler

AddRequestCookie

İsteğe bir çerez ekler veya aynı ada sahip başka bir çerez varsa çerezi geçersiz kılar. Hesaplama açısından daha az maliyetli olduğu için Çerezler API'sinin kullanılması tercih edilir.

Özellikler

AddResponseCookie

Yanıtı bir çerez ekler veya aynı ada sahip başka bir çerez varsa çerezi geçersiz kılar. Hesaplama açısından daha az maliyetli olduğu için Çerezler API'sinin kullanılması tercih edilir.

Özellikler

AddResponseHeader

Bu web isteğinin yanıtına yanıt başlığını ekler. Birden fazla yanıt başlığı aynı adı paylaşabileceğinden, bir yanıt başlığını değiştirmek için önce kaldırmanız, ardından yeni bir yanıt başlığı eklemeniz gerekir.

Özellikler

CancelRequest

Bir ağ isteğini iptal eden bildirimsel etkinlik işlemi.

Özellikler

EditRequestCookie

İsteğin bir veya daha fazla çerezini düzenler. Hesaplama açısından daha az maliyetli olduğu için Çerezler API'sinin kullanılması tercih edilir.

Özellikler

  • oluşturucu

    void

    constructor işlevi şu şekilde görünür: 

    (arg: EditRequestCookie) => {...}

  • filtre

    RequestCookie

    Değiştirilecek çerezleri filtreleyin. Tüm boş girişler yoksayılır.

  • değişiklik

    RequestCookie

    Filtreyle eşleşen çerezlerde geçersiz kılınacak özellikler. Boş dize olarak ayarlanan özellikler kaldırılır.

EditResponseCookie

Yanıtın bir veya daha fazla çerezini düzenler. Hesaplama açısından daha az maliyetli olduğu için Çerezler API'sinin kullanılması tercih edilir.

Özellikler

FilterResponseCookie

HTTP yanıtlarındaki bir çerezin filtresi.

Özellikler

  • ageLowerBound

    number isteğe bağlı

    Çerez ömrünün kapsayıcı alt sınırı (geçerli zamandan sonraki saniye cinsinden belirtilir). Yalnızca geçerlilik tarihi ve saati "şimdi + ageLowerBound" veya daha sonraki bir tarih olarak ayarlanmış çerezler bu ölçütü karşılar. Oturum çerezleri, bu filtrenin ölçütünü karşılamıyor. Çerez ömrü, "max-age" veya "expires" çerez özelliklerinden biri kullanılarak hesaplanır. Her ikisi de belirtilmişse çerezin kullanım ömrünü hesaplamak için "max-age" kullanılır.

  • ageUpperBound

    number isteğe bağlı

    Çerez ömrünün kapsayıcı üst sınırı (geçerli zamandan sonraki saniye cinsinden belirtilir). Yalnızca geçerlilik bitiş tarihi ve saati [şimdi, şimdi + ageUpperBound] aralığında olan çerezler bu ölçütü karşılar. Oturum çerezleri ve geçerlilik bitiş tarihi geçmişte olan çerezler bu filtrenin ölçütünü karşılamaz. Çerez ömrü, "max-age" veya "expires" çerez özelliklerinden biri kullanılarak hesaplanır. Her ikisi de belirtilmişse çerezin kullanım ömrünü hesaplamak için "max-age" kullanılır.

  • alan

    dize isteğe bağlı

    Alan çerezi özelliğinin değeri.

  • geçerlilik bitiş tarihi

    dize isteğe bağlı

    Expires çerez özelliğinin değeri.

  • httpOnly

    dize isteğe bağlı

    HttpOnly çerez özelliğinin varlığı.

  • maxAge

    number isteğe bağlı

    Max-Age çerez özelliğinin değeri

  • ad

    dize isteğe bağlı

    Çerezin adı.

  • yol

    dize isteğe bağlı

    Yol çerez özelliğinin değeri.

  • güvenli

    dize isteğe bağlı

    Güvenli çerez özelliğinin varlığı.

  • sessionCookie

    boolean isteğe bağlı

    Oturum çerezlerini filtreler. Oturum çerezlerinin "max-age" veya "expires" özelliklerinde belirtilen bir ömrü yoktur.

  • value

    dize isteğe bağlı

    Çerezin değeri, çift tırnak içine alınmış olabilir.

HeaderFilter

İstek başlıklarını çeşitli ölçütlere göre filtreler. Birden fazla ölçüt birlikte değerlendirilir.

Özellikler

  • nameContains

    dize | dize[] isteğe bağlı

    Başlık adı, belirtilen dizelerin tümünü içeriyorsa eşleşir.

  • nameEquals

    dize isteğe bağlı

    Başlık adı belirtilen dizeye eşitse eşleşir.

  • namePrefix

    dize isteğe bağlı

    Başlık adı belirtilen dizeyle başlıyorsa eşleşir.

  • nameSuffix

    dize isteğe bağlı

    Başlık adı belirtilen dizeyle bitiyorsa eşleşir.

  • valueContains

    dize | dize[] isteğe bağlı

    Üstbilgi değeri belirtilen dizelerin tümünü içeriyorsa eşleşir.

  • valueEquals

    dize isteğe bağlı

    Üstbilgi değeri belirtilen dizeye eşitse eşleşir.

  • valuePrefix

    dize isteğe bağlı

    Başlık değeri belirtilen dizeyle başlıyorsa eşleşir.

  • valueSuffix

    dize isteğe bağlı

    Başlık değeri belirtilen dizeyle bitiyorsa eşleşir.

IgnoreRules

Belirtilen ölçütlerle eşleşen tüm kuralları maskeler.

Özellikler

  • oluşturucu

    void

    constructor işlevi şu şekilde görünür: 

    (arg: IgnoreRules) => {...}

  • hasTag

    dize isteğe bağlı

    Ayarlandığında, belirtilen etikete sahip kurallar yoksayılır. Bu yoksayma işlemi kalıcı değildir ve yalnızca aynı ağ isteği aşamasındaki kuralları ve bunların işlemlerini etkiler. Kuralların, önceliklerine göre azalan sırada yürütüldüğünü unutmayın. Bu işlem, geçerli kuraldan daha düşük önceliğe sahip kuralları etkiler. Aynı önceliğe sahip kurallar yoksayılabilir veya yoksayılmayabilir.

  • lowerPriorityThan

    number isteğe bağlı

    Ayarlanırsa belirtilen değerden daha düşük önceliğe sahip kurallar yok sayılır. Bu sınır kalıcı değildir ve yalnızca aynı ağ isteği aşamasındaki kuralları ve bunların işlemlerini etkiler.

RedirectByRegEx

URL'ye normal ifade uygulayarak isteği yönlendirir. Normal ifadeler RE2 söz dizimini kullanır.

Özellikler

  • oluşturucu

    void

    constructor işlevi şu şekilde görünür: 

    (arg: RedirectByRegEx) => {...}

  • başlangıç fiyatı:

    dize

    Yakalama grupları içerebilen bir eşleşme kalıbı. Yakalama grupları, JavaScript normal ifadelerine daha yakın olması için RE2 söz dizimi (\1, \2, ...) yerine Perl söz diziminde ($1, $2, ...) referanslanır.

  • to

    dize

    Hedef deseni.

RedirectRequest

Bir ağ isteğini yönlendiren bildirimsel etkinlik işlemi.

Özellikler

RedirectToEmptyDocument

Bir ağ isteğini boş bir belgeye yönlendiren bildirimsel etkinlik işlemi.

Özellikler

RedirectToTransparentImage

Bir ağ isteğini şeffaf bir resme yönlendiren bildirimsel etkinlik işlemi.

Özellikler

RemoveRequestCookie

İsteğin bir veya daha fazla çerezini kaldırır. Hesaplama açısından daha az maliyetli olduğu için Çerezler API'sinin kullanılması tercih edilir.

Özellikler

RemoveRequestHeader

Belirtilen ada sahip istek başlığını kaldırır. SetRequestHeader ve RemoveRequestHeader'ı aynı istekte aynı başlık adıyla kullanmayın. Her istek başlığı adı, her istekte yalnızca bir kez görünür.

Özellikler

RemoveResponseCookie

Yanıtın bir veya daha fazla çerezini kaldırır. Hesaplama açısından daha az maliyetli olduğu için Çerezler API'sinin kullanılması tercih edilir.

Özellikler

RemoveResponseHeader

Belirtilen adlara ve değerlere sahip tüm yanıt üstbilgilerini kaldırır.

Özellikler

  • oluşturucu

    void

    constructor işlevi şu şekilde görünür: 

    (arg: RemoveResponseHeader) => {...}

  • ad

    dize

    HTTP isteği başlığı adı (büyük/küçük harfe duyarlı değildir).

  • value

    dize isteğe bağlı

    HTTP isteği başlığı değeri (büyük/küçük harfe duyarlı değildir).

RequestCookie

HTTP isteklerindeki bir çerezin filtresi veya spesifikasyonu.

Özellikler

  • ad

    dize isteğe bağlı

    Çerezin adı.

  • value

    dize isteğe bağlı

    Çerezin değeri, çift tırnak içine alınmış olabilir.

RequestMatcher

Ağ etkinliklerini çeşitli ölçütlere göre eşleştirir.

Özellikler

  • oluşturucu

    void

    constructor işlevi şu şekilde görünür: 

    (arg: RequestMatcher) => {...}

  • contentType

    string[] isteğe bağlı

    Bir yanıtın MIME medya türü (HTTP Content-Type üstbilgisinden) listede yer alıyorsa eşleşir.

  • excludeContentType

    string[] isteğe bağlı

    Bir yanıtın MIME medya türü (HTTP Content-Type üstbilgisinden) listede yoksa eşleşir.

  • excludeRequestHeaders

    HeaderFilter[] isteğe bağlı

    İstek başlıklarından hiçbiri HeaderFilters'dan herhangi biriyle eşleşmediğinde eşleşir.

  • excludeResponseHeaders

    HeaderFilter[] isteğe bağlı

    Yanıt başlıklarından hiçbiri HeaderFilters'lardan biriyle eşleşmediğinde eşleşir.

  • firstPartyForCookiesUrl

    UrlFilter isteğe bağlı

    Kullanımdan kaldırıldı

    82. sürümden beri yoksayılır.

    İsteğin "birinci taraf" URL'si için UrlFilter koşulları karşılanırsa eşleşir. Bir isteğin "birinci taraf" URL'si varsa isteğin hedef URL'sinden farklı olabilir ve çerezlerle ilgili üçüncü taraf kontrolleri açısından neyin "birinci taraf" olarak kabul edildiğini açıklar.

  • requestHeaders

    HeaderFilter[] isteğe bağlı

    İstek başlıklarından bazıları HeaderFilters'dan biriyle eşleşirse eşleşir.

  • resourceType

    ResourceType[] isteğe bağlı

    Bir isteğin istek türü listede yer alıyorsa eşleşir. Türlerden herhangi biriyle eşleşemeyen istekler filtrelenir.

  • responseHeaders

    HeaderFilter[] isteğe bağlı

    Yanıt başlıklarından bazıları HeaderFilters'dan biriyle eşleşirse eşleşir.

  • sahneler

    Aşama[] isteğe bağlı

    Aşamaları açıklayan bir dize listesi içerir. İzin verilen değerler: "onBeforeRequest", "onBeforeSendHeaders", "onHeadersReceived", "onAuthRequired". Bu özellik varsa geçerli aşamalar, listelenen aşamalarla sınırlıdır. Koşulun tamamının yalnızca tüm özelliklerle uyumlu aşamalarda geçerli olduğunu unutmayın.

  • thirdPartyForCookies

    boolean isteğe bağlı

    Kullanımdan kaldırıldı

    87. sürümden beri yoksayılır.

    Doğru olarak ayarlanırsa üçüncü taraf çerez politikalarına tabi olan isteklerle eşleşir. Yanlış olarak ayarlanırsa diğer tüm isteklerle eşleşir.

  • url

    UrlFilter isteğe bağlı

    İsteğin URL'si için UrlFilter koşulları karşılanıyorsa eşleşir.

ResponseCookie

HTTP yanıtlarındaki bir çerez belirtimi.

Özellikler

  • alan

    dize isteğe bağlı

    Alan çerezi özelliğinin değeri.

  • geçerlilik bitiş tarihi

    dize isteğe bağlı

    Expires çerez özelliğinin değeri.

  • httpOnly

    dize isteğe bağlı

    HttpOnly çerez özelliğinin varlığı.

  • maxAge

    number isteğe bağlı

    Max-Age çerez özelliğinin değeri

  • ad

    dize isteğe bağlı

    Çerezin adı.

  • yol

    dize isteğe bağlı

    Yol çerez özelliğinin değeri.

  • güvenli

    dize isteğe bağlı

    Güvenli çerez özelliğinin varlığı.

  • value

    dize isteğe bağlı

    Çerezin değeri, çift tırnak içine alınmış olabilir.

SendMessageToExtension

declarativeWebRequest.onMessage etkinliğini tetikler.

Özellikler

SetRequestHeader

Belirtilen ada sahip istek başlığını belirtilen değere ayarlar. Belirtilen ada sahip bir başlık daha önce yoksa yeni bir başlık oluşturulur. Üstbilgi adı karşılaştırması her zaman büyük/küçük harfe duyarsızdır. Her istek başlığı adı, her istekte yalnızca bir kez görünür.

Özellikler

Stage

Enum

"onBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

"onAuthRequired"

Etkinlikler

onMessage

chrome.declarativeWebRequest.onMessage.addListener(
  callback: function,
)

Bildirimli web isteği API'sinin bir işlemiyle declarativeWebRequest.SendMessageToExtension üzerinden mesaj gönderildiğinde tetiklenir.

Parametreler

  • callback

    işlev

    callback parametresi şu şekilde görünür: 

    (details: object) => void

    • ayrıntılar

      nesne

      • documentId

        dize isteğe bağlı

        İsteği yapan dokümanın UUID'si.

      • Belgenin bulunduğu yaşam döngüsü.

      • frameId

        sayı

        0 değeri, isteğin ana çerçevede gerçekleştiğini gösterir. Pozitif bir değer ise isteğin gerçekleştiği bir alt çerçevenin kimliğini gösterir. Bir (alt) çerçevenin dokümanı yüklendiyse (type main_frame veya sub_frame), frameId dış çerçevenin kimliğini değil, bu çerçevenin kimliğini gösterir. Çerçeve kimlikleri, bir sekmede benzersizdir.

      • Gezinmenin gerçekleştiği çerçevenin türü.

      • mesaj

        dize

        Arama komut dosyası tarafından gönderilen mesaj.

      • method

        dize

        Standart HTTP yöntemi.

      • parentDocumentId

        dize isteğe bağlı

        Bu çerçeveye sahip üst dokümanın UUID'si. Üst öğe yoksa bu ayar belirlenmez.

      • parentFrameId

        sayı

        İsteği gönderen çerçeveyi saran çerçevenin kimliği. Üst çerçeve yoksa -1 olarak ayarlayın.

      • requestId

        dize

        İsteğin kimliği. İstek kimlikleri, tarayıcı oturumunda benzersizdir. Bu nedenle, aynı isteğin farklı etkinliklerini ilişkilendirmek için kullanılabilirler.

      • sürecin

        Sahne

        Etkinliğin tetiklendiği sırada ağ isteğinin bulunduğu aşama.

      • tabId

        sayı

        İsteğin gerçekleştiği sekmenin kimliği. İstek bir sekmeyle ilgili değilse -1 olarak ayarlayın.

      • timeStamp

        sayı

        Bu sinyalin tetiklendiği zaman (epoch'tan beri geçen milisaniye cinsinden).

      • İstenen kaynağın nasıl kullanılacağı

      • url

        dize

onRequest

addRules, removeRules ve getRules'den oluşan Declarative Event API'yi sağlar.

Koşullar

RequestMatcher

İşlemler

AddRequestCookie

AddResponseCookie

AddResponseHeader

CancelRequest

EditRequestCookie

EditResponseCookie

RedirectRequest

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

RemoveResponseCookie

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

SendMessageToExtension

IgnoreRules