chrome.declarativeWebRequest

Açıklama

Not: Bu API'nin desteği sonlandırılmıştır. Bunun yerine declarativeNetRequest API'ye göz atın. Yayındaki isteklere müdahale etmek, bunları engellemek veya değiştirmek için chrome.declarativeWebRequest API'yi kullanın. Değerlendirilen kuralları JavaScript motoru yerine tarayıcıda kaydedebildiğiniz için chrome.webRequest API'sinden önemli ölçüde daha hızlıdır. Bu da geri dönüş gecikmelerini azaltır ve daha yüksek verimlilik sağlar.

İ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

Hassas olmayan bazı işlem türlerinin, ana makine izinleri gerektirmediğini unutmayın:

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

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

Diğer tüm işlemler, tüm URL'ler için ana makine izni gerektirir.

Örneğin, "https://*.google.com/*" bir uzantının sahip olduğu tek ana makine izniyse bu tür bir uzantı şunun için bir kural oluşturabilir:

  • https://www.google.com veya https://anything.else.com için gönderilen isteği iptal edin.
  • https://www.google.com adlı işletmeye giderken mesaj gönder, ancak https://something.else.com numarasına gitmeyin.

Uzantı, https://www.google.com alanını https://mail.google.com hedefine yönlendirecek bir kural oluşturamaz.

Kurallar

Declarative Web Request API, Declarative API kavramlarına uygun hareket eder. Kuralları chrome.declarativeWebRequest.onRequest etkinlik nesnesine kaydedebilirsiniz.

Declarative Web Request API, tek bir eşleşme ölçütü türünü (RequestMatcher) destekler. RequestMatcher, yalnızca listelenen tüm ölçütler karşılanırsa ağ isteklerini eşleştirir. Kullanıcı, çok amaçlı adres çubuğuna https://www.example.com değerini girdiğinde aşağıdaki RequestMatcher, 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 istekleri, şema nedeniyle RequestMatcher tarafından reddedilecek. Ayrıca, tüm yerleştirilmiş iframe istekleri resourceType nedeniyle reddedilir.

"example.com" adresine gönderilen tüm istekleri iptal etmek için aşağıdaki şekilde bir kural tanımlayabilirsiniz:

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

Her bir koşul belirtilen tüm işlemleri tetiklemek için yeterli olduğundan, example.com ve foobar.com için yapılan tüm istekleri iptal etmek isterseniz ikinci bir koşul ekleyebilirsiniz:

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 şekilde kaydedin:

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

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

Declarative Web Request API, Web Request API'nin web istekleri için yaşam döngüsü modelini uygular. Bu, koşulların yalnızca bir web isteğinin belirli aşamalarında test edilebileceği ve benzer şekilde, işlemlerin yalnızca belirli aşamalarda yürütülebileceği anlamına gelir. Aşağıdaki tablolarda, koşullar ve işlemlerle uyumlu olan istek aşamaları listelenmiştir.

Durum özelliklerinin işlenebileceği istek aşamaları.
Koşul ö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ığı gibi önceliklerle ilişkilendirilebilir. Bu mekanizma, istisnaları belirtmek için kullanılabilir. Aşağıdaki örnek, "sunucum.com" sunucusu dışında 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 devam etmediğini unutmayın. Bir web isteğinin her aşamasında tüm kuralların tüm koşulları değerlendirilir. Bir IgnoreRules işlemi yürütülürse bu, yalnızca aynı aşamada aynı web isteği için yürütülen diğer işlemlere uygulanır.

Türler

AddRequestCookie

İsteğe bir çerez ekler veya aynı ada sahip başka bir çerezin mevcut olması ihtimaline karşı bir çerezi geçersiz kılar. İşlem maliyeti daha düşük olduğundan Çerezler API'sinin tercih edildiğini unutmayın.

Özellikler

AddResponseCookie

Yanıta çerez ekler veya aynı ada sahip başka bir çerezin mevcut olması ihtimaline karşı çerezi geçersiz kılar. İşlem maliyeti daha düşük olduğundan Çerezler API'sinin tercih edildiğini unutmayın.

Özellikler

AddResponseHeader

Bu web isteğinin yanıtına yanıt başlığı ekler. Birden çok yanıt başlığı aynı adı paylaşabileceğinden, başlık başlığını kaldırıp yenisini eklemeniz gerekir.

Özellikler

CancelRequest

Ağ isteğini iptal eden bildirim temelli etkinlik işlemi.

Özellikler

EditRequestCookie

İstekte bulunan bir veya daha fazla çerezi düzenler. İşlem maliyeti daha düşük olduğundan Çerezler API'sinin tercih edildiğini unutmayın.

Özellikler

  • oluşturucu

    void

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

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

  • filter

    RequestCookie

    Değiştirilecek çerezler için filtre uygulayın. Tüm boş girişler yoksayılır.

  • değiştirme

    RequestCookie

    Filtreyle işlenmiş çerezlerde geçersiz kılınacak özellikler. Boş dize olarak ayarlanan özellikler kaldırılır.

EditResponseCookie

Bir veya daha fazla yanıt çerezini düzenler. İşlem maliyeti daha düşük olduğundan Çerezler API'sinin tercih edildiğini unutmayın.

Özellikler

FilterResponseCookie

HTTP Yanıtlarındaki bir çerez filtresi.

Özellikler

  • ageLowerBound

    numara isteğe bağlı

    Çerez ömründeki kapsayıcı alt sınır (geçerli saatten sonra saniye cinsinden belirtilir). Yalnızca geçerlilik bitiş tarihi ve saati "now + ageLowerBound" veya daha ileri bir değere ayarlanmış çerezler bu ölçütü karşılar. Oturum çerezleri bu filtrenin kriterini karşılamıyor. Çerez ömrü, "max-age" veya "süresi doluyor" çerez özelliklerinden biriyle hesaplanır. Her ikisi de belirtilirse çerez kullanım ömrünü hesaplamak için "max-age" kullanılır.

  • ageUpperBound

    numara isteğe bağlı

    Çerez ömründeki kapsayıcı üst sınır (geçerli saatten sonra saniye cinsinden belirtilir). Yalnızca geçerlilik bitiş tarihi/saati [şimdi, şimdi + ageUpperBound] aralığında olan çerezler bu ölçütü karşılar. Geçerlilik bitiş tarihi/saati geçmişte olan oturum çerezleri ve çerezler, bu filtrenin kriterini karşılamaz. Çerez ömrü, "max-age" veya "süresi doluyor" çerez özelliklerinden biriyle hesaplanır. Her ikisi de belirtilirse çerez kullanım ömrünü hesaplamak için "max-age" kullanılır.

  • alan

    string isteğe bağlı

    Alan çerezi özelliğinin değeri.

  • geçerlilik bitiş tarihi

    string isteğe bağlı

    Expires çerezi özelliğinin değeri.

  • httpOnly

    string isteğe bağlı

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

  • maxAge

    numara isteğe bağlı

    Maksimum Yaş çerez özelliğinin değeri

  • ad

    string isteğe bağlı

    Bir çerezin adı.

  • yol

    string isteğe bağlı

    Yol çerezi özelliğinin değeri.

  • güvenli

    string isteğe bağlı

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

  • sessionCookie

    boole isteğe bağlı

    Oturum çerezlerini filtreler. Oturum çerezlerinin "max-age" veya "expires" özelliklerinin hiçbirinde ömür boyu belirtilmemiştir.

  • value

    string isteğe bağlı

    Çerezin değeri çift tırnakla doldurulabilir.

HeaderFilter

Filtreler, çeşitli ölçütler için üst bilgileri ister. Birden çok ölçüt bir bağlaç olarak değerlendirilir.

Özellikler

  • nameContains

    string|string[] optional

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

  • nameEquals

    string isteğe bağlı

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

  • namePrefix

    string isteğe bağlı

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

  • nameSuffix

    string isteğe bağlı

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

  • valueContains

    string|string[] optional

    Başlık değeri belirtilen tüm dizeleri içeriyorsa eşleşir.

  • valueEquals

    string isteğe bağlı

    Başlık değeri belirtilen dizeye eşitse eşleşir.

  • valuePrefix

    string isteğe bağlı

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

  • valueSuffix

    string 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

    string isteğe bağlı

    Ayarlanırsa belirtilen etikete sahip kurallar yoksayılır. Bu yoksayma devam etmez. Yalnızca kuralları ve bu kuralların aynı ağ isteği aşamasındaki işlemlerini etkiler. Kuralların, önceliklerine göre azalan düzende yürütüldüğünü unutmayın. Bu işlem, mevcut kuraldan daha düşük önceliğe sahip kuralları etkiliyor. Aynı önceliğe sahip kurallar yoksayılabilir veya yoksayılabilir.

  • lowerPriorityThan

    numara isteğe bağlı

    Ayarlanırsa belirtilen değerden daha düşük önceliğe sahip kurallar yoksayılır. Bu sınır kalıcı değil, yalnızca kuralları ve bunların aynı ağ isteği aşamasındaki 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)=> {...}

  • şuradan

    dize

    Yakalama grupları içerebilen bir eşleşme kalıbı. Yakalama gruplarına, JavaScript Normal İfadelerine daha yakın olmaları için RE2 söz dizimi (\1, \2, ...) yerine Perl sözdiziminde ($1, $2, ...) referans verilir.

  • -

    dize

    Hedef kalıbı.

RedirectRequest

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

Özellikler

RedirectToEmptyDocument

Ağ isteğini boş bir belgeye yönlendiren bildirim temelli etkinlik işlemi.

Özellikler

RedirectToTransparentImage

Ağ isteğini şeffaf bir resme yönlendiren bildirim temelli etkinlik işlemi.

Özellikler

RemoveRequestCookie

Bir veya daha fazla istek çerezini kaldırır. İşlem maliyeti daha düşük olduğundan Çerezler API'sinin tercih edildiğini unutmayın.

Özellikler

RemoveRequestHeader

Belirtilen adın istek başlığını kaldırır. SetRequestHeader ve RemoveRequestHeader öğelerini aynı istekte aynı üstbilgi adıyla kullanmayın. Her istek başlığı adı her istekte yalnızca bir kez geçer.

Özellikler

RemoveResponseCookie

Bir veya daha fazla yanıt çerezini kaldırır. İşlem maliyeti daha düşük olduğundan Çerezler API'sinin tercih edildiğini unutmayın.

Özellikler

RemoveResponseHeader

Belirtilen adların ve değerlerin 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 istek başlığı adı (büyük/küçük harfe duyarlı değildir).

  • value

    string isteğe bağlı

    HTTP istek başlığı değeri (büyük/küçük harfe duyarlı değil).

RequestCookie

HTTP İstekleri'ndeki bir çerezin filtresi veya spesifikasyonu.

Özellikler

  • ad

    string isteğe bağlı

    Bir çerezin adı.

  • value

    string isteğe bağlı

    Çerezin değeri çift tırnakla doldurulabilir.

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 yer almıyorsa eşleşir.

  • excludeRequestHeaders

    HeaderFilter[] isteğe bağlı

    İstek başlıklarından hiçbiri HeaderFilter'den herhangi biriyle eşleşmezse eşleşir.

  • excludeResponseHeaders

    HeaderFilter[] isteğe bağlı

    Yanıt üstbilgilerinden hiçbiri Üstbilgi Filtrelerinden herhangi biriyle eşleşmezse eşleşir.

  • firstPartyForCookiesUrl

    UrlFilter isteğe bağlı

    Kullanımdan kaldırıldı

    82 sürümünden beri yoksayıldı.

    İsteğin "birinci taraf" URL'si için UrlFilter koşulları karşılanırsa eşleşir. Mevcut olduğunda bir isteğin "birinci taraf" URL'si, isteğin hedef URL'sinden farklı olabilir ve üçüncü tarafların çerez kontrolleri açısından neyin "birinci taraf" olarak kabul edildiğini açıklar.

  • requestHeaders

    HeaderFilter[] isteğe bağlı

    Bazı istek başlıkları HeaderFiltreler'den 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ürlerin hiçbiriyle eşleşemeyen istekler filtrelenir.

  • responseHeaders

    HeaderFilter[] isteğe bağlı

    Bazı yanıt üstbilgileri, Başlık Filtrelerinden biriyle eşleşirse eşleşir.

  • sahneler

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

    Aşamaları açıklayan dizelerin bir listesini içerir. İzin verilen değerler 'onBeforeRequest', 'onBeforeSendHeaders', 'onHeadersReceived', 'onAuthRequired'dır. Bu özellik mevcutsa geçerli aşamalar listelenenlerle sınırlandırılır. Tüm koşulun, yalnızca tüm özelliklerle uyumlu aşamalarda geçerli olacağını unutmayın.

  • thirdPartyForCookies

    boole isteğe bağlı

    Kullanımdan kaldırıldı

    87. sürümden bu yana yok sayıldı.

    Doğru değerine ayarlanırsa üçüncü taraf çerez politikalarına tabi istekleri eşleştirir. Yanlış değerine 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ırsa eşleşir.

ResponseCookie

HTTP Yanıtlarındaki çerez belirtimi.

Özellikler

  • alan

    string isteğe bağlı

    Alan çerezi özelliğinin değeri.

  • geçerlilik bitiş tarihi

    string isteğe bağlı

    Expires çerezi özelliğinin değeri.

  • httpOnly

    string isteğe bağlı

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

  • maxAge

    numara isteğe bağlı

    Maksimum Yaş çerez özelliğinin değeri

  • ad

    string isteğe bağlı

    Bir çerezin adı.

  • yol

    string isteğe bağlı

    Yol çerezi özelliğinin değeri.

  • güvenli

    string isteğe bağlı

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

  • value

    string isteğe bağlı

    Çerezin değeri çift tırnakla doldurulabilir.

SendMessageToExtension

declarativeWebRequest.onMessage etkinliğini tetikler.

Özellikler

SetRequestHeader

Belirtilen adın istek başlığını belirtilen değere ayarlar. Belirtilen ada sahip bir üstbilgi daha önce mevcut değilse yeni bir üstbilgi oluşturulur. Üst bilgi adı karşılaştırması hiçbir zaman büyük/küçük harfe duyarlı değildir. Her istek başlığı adı her istekte yalnızca bir kez geçer.

Özellikler

Stage

Enum

"onBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

"onAuthRequired"

Etkinlikler

onMessage

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

Bildirim temelli web isteği API'sinin bir işleminden declarativeWebRequest.SendMessageToExtension aracılığıyla bir mesaj gönderildiğinde tetiklenir.

Parametreler

  • geri çağırma

    işlev

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

    (details: object)=>void

    • ayrıntılar

      nesne

      • documentId

        string 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, pozitif değer ise isteğin gerçekleştiği alt çerçevenin kimliğini ifade eder. Bir (alt) çerçevenin dokümanı yüklendiyse (type, main_frame veya sub_frame ise) frameId, dış çerçevenin kimliğini değil, bu çerçevenin kimliğini belirtir. Çerçeve kimlikleri bir sekme içinde 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

        string isteğe bağlı

        Bu çerçevenin sahibi olan üst dokümanın UUID'si. Üst öğe yoksa bu ayar yapılmaz.

      • parentFrameId

        sayı

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

      • requestId

        dize

        İsteğin kimliği. İstek kimlikleri bir tarayıcı oturumunda benzersizdir. Sonuç olarak, aynı talepteki farklı etkinlikleri ilişkilendirmek için kullanılabilirler.

      • saklamak

        Sahne

        Etkinliğin tetiklendiği ağ isteğinin aşaması.

      • tabId

        sayı

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

      • timeStamp

        sayı

        Dönemden bu yana, milisaniye cinsinden bu sinyalin tetiklendiği süre.

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

      • url

        dize

onRequest

addRules, removeRules ve getRules öğelerinden 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