chrome.declarativeWebRequest

Açıklama

Not: Bu API'nin desteği sonlandırılmıştır. Bunun yerine declarativeNetRequest API'yi inceleyin. Yayındaki isteklere müdahale etmek, bunları 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 çünkü JavaScript motoru yerine tarayıcıda değerlendirilen kuralları kaydedebilirsiniz. Böylece, gidiş dönüş gecikmelerini azaltıp daha yüksek verimlilik elde edebilirsiniz.

İzinler

declarativeWebRequest

"declarativeWebRequest"i beyan etmeniz gerekir uzantı manifestinde kullanabilirsiniz API ve ana makine izinleri.

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

Kullanılabilirlik

Beta kanalı ≤ MV2

Manifest

Bazı hassas olmayan işlem türlerinin ana makine izinleri gerektirmediğini unutmayın:

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

SendMessageToExtension() işlemi, ağ istekleri olan tüm ana makineler için ana makine izinleri gerektirir bir mesaj tetikleyin.

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

Örneğin, bir uzantının sahip olduğu tek ana makine izni "https://*.google.com/*" ise, bu tür bir uzantısı şu amaçlarla 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 hedefine giderken https://something.else.com hedefine gitmeden mesaj gönder.

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

Kurallar

Declarative Web Request API, Declarative API kavramlarını kullanır. Kaydolabilirsiniz kurallarını chrome.declarativeWebRequest.onRequest etkinlik nesnesine ekler.

Bildirimsel Web İsteği API'si, tek bir eşleşme ölçütü olan RequestMatcher türünü destekler. İlgili içeriği oluşturmak için kullanılan RequestMatcher, yalnızca listelenen tüm ölçütlerin karşılanması durumunda ağ istekleriyle eşleşir. Aşağıdakiler RequestMatcher, kullanıcı şunu girdiğinde bir ağ isteğiyle eşleşir: https://www.example.com çok amaçlı kutu:

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ş iframe için tüm istekler resourceType nedeniyle reddedilir.

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

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

example.com ve foobar.com isteklerine yönelik 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ı şu şekilde kaydedin:

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

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

Declarative Web Request API, Web'in Web istekleri için yaşam döngüsü modelini API isteğinde bulunun. Bu, koşulların bir web isteğinin yalnızca belirli aşamalarında test edilebileceği anlamına gelir. Benzer şekilde, işlemler de sadece belirli aşamalarda yürütülebilir. Aşağıdaki tablolarda koşullar ve işlemlerle uyumlu istek aşamaları.

Koşul ö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 aşamaları isteyin.
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çıklanan önceliklerle ilişkilendirilebilir. Bu mekanizmanın istisnaları ifade etmek için kullanılır. Aşağıdaki örnekte, evil.jpg adlı resim için gönderilen tüm istekler engellenmektedir "myserver.com" sunucusundakiler dışında.

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 genelinde devam ettirilmediğinin bilinmesi önemlidir. aşama. 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üldüğünde, yalnızca aynı aynı aşamadan geçer.

Türler

AddRequestCookie

İsteğe bir çerez ekler veya aynı ada sahip başka bir çerezin zaten mevcut olması durumunda bir çerezi geçersiz kılar. İşlem açısından daha ucuz olduğu için Cookies API'nin kullanılmasının tercih edildiğini unutmayın.

Özellikler

AddResponseCookie

Yanıta bir çerez ekler veya aynı ada sahip başka bir çerezin zaten mevcut olması durumunda bir çerezi geçersiz kılar. İşlem açısından daha ucuz olduğu için Cookies API'nin kullanılmasının tercih edildiğini unutmayın.

Özellikler

AddResponseHeader

Bu web isteğinin yanıtına yanıt başlığını ekler. Birden çok yanıt başlığı aynı ada sahip olabileceğinden, birini değiştirmek için önce mevcut yanıt başlığını kaldırmanız, sonra da yeni bir yanıt başlığı eklemeniz gerekir.

Özellikler

CancelRequest

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

Özellikler

EditRequestCookie

İsteğin bir veya daha fazla çerezini düzenler. İşlem açısından daha ucuz olduğu için Cookies API'nin kullanılmasının tercih edildiğini unutmayın.

Özellikler

  • oluşturucu

    geçersiz

    constructor işlevi aşağıdaki gibi görünür: 

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

  • filtrele

    RequestCookie

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

  • değişiklik

    RequestCookie

    Filtreyi birleştiren çerezlerde geçersiz kılınacak özellikler. Boş bir dizeye ayarlanan özellikler kaldırılır.

EditResponseCookie

Yanıt çerezlerini düzenler. İşlem açısından daha ucuz olduğu için Cookies API'nin kullanılmasının tercih edildiğini unutmayın.

Özellikler

FilterResponseCookie

HTTP yanıtlarında bir çerez filtresi.

Özellikler

  • ageLowerBound

    sayı isteğe bağlı

    Çerez ömrü için kapsayıcı alt sınır (geçerli tarihten sonraki saniye cinsinden belirtilir). Yalnızca geçerlilik bitiş tarihi "şimdi + yaşLowerBound" olarak ayarlanan çerezler veya daha sonra karşılayabilir. Oturum çerezleri bu filtrenin kriterini karşılamıyor. Çerez ömrü, "max-age" parametresinden hesaplanır. veya "süresi doluyor" çerez özellikleriyle değiştirebilirsiniz. Her ikisi de belirtilirse "max-age" çerezin ömrünü hesaplamak için kullanılır.

  • ageUpperBound

    sayı isteğe bağlı

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

  • alan

    dize isteğe bağlı

    Alan çerezi özelliğinin değeri.

  • geçerlilik bitiş tarihi

    dize isteğe bağlı

    Geçerliliği sona eren çerez özelliğinin değeri.

  • httpOnly

    dize isteğe bağlı

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

  • maxAge

    sayı isteğe bağlı

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

  • ad

    dize isteğe bağlı

    Çerezin adı.

  • yol

    dize isteğe bağlı

    Yol çerezi özelliğinin değeri.

  • güvenli

    dize isteğe bağlı

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

  • sessionCookie

    boole isteğe bağlı

    Oturum çerezlerini filtreler. Oturum çerezlerinin hiçbir "max-age" için kullanım ömrü belirtilmemiş veya "süresi doluyor" özellikleri hakkında daha fazla bilgi edinin.

  • value

    dize isteğe bağlı

    Bir çerezin değeri çift tırnak içinde doldurulabilir.

HeaderFilter

Filtreler, çeşitli ölçütler için başlık ister. Birden çok ölçüt bağlayıcı olarak değerlendirilir.

Özellikler

  • nameContains

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

    Başlık adı, belirtilen tüm dizeleri 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

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

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

  • valueEquals

    dize isteğe bağlı

    Başlık 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

    geçersiz

    constructor işlevi aşağıdaki gibi görünür: 

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

  • hasTag

    dize isteğe bağlı

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

  • lowerPriorityThan

    sayı 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ğildir ve yalnızca kuralları ve aynı ağ isteği aşamasındaki eylemlerini etkiler.

RedirectByRegEx

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

Özellikler

  • oluşturucu

    geçersiz

    constructor işlevi aşağıdaki gibi görünür: 

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

  • şuradan

    dize

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

  • -

    dize

    Hedef kalıbı.

RedirectRequest

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

Özellikler

RedirectToEmptyDocument

Bir ağ isteğini boş bir dokümana yönlendiren bildirim temelli etkinlik işlemi.

Özellikler

RedirectToTransparentImage

Bir ağ isteğini şeffaf bir görüntüye yönlendiren bildirim temelli etkinlik işlemi.

Özellikler

RemoveRequestCookie

İstekle ilgili bir veya daha fazla çerezi kaldırır. İşlem açısından daha ucuz olduğu için Cookies API'nin kullanılmasının tercih edildiğini unutmayın.

Özellikler

RemoveRequestHeader

Belirtilen adın istek başlığını kaldırır. Aynı istekte aynı başlık adıyla SetRequestHeader ve RemoveRequestHeader öğelerini 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 açısından daha ucuz olduğu için Cookies API'nin kullanılmasının tercih edildiğini unutmayın.

Özellikler

RemoveResponseHeader

Belirtilen adların ve değerlerin tüm yanıt başlıklarını kaldırır.

Özellikler

  • oluşturucu

    geçersiz

    constructor işlevi aşağıdaki gibi görünür: 

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

  • ad

    dize

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

  • value

    dize isteğe bağlı

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

RequestCookie

HTTP isteklerindeki bir çerezin filtresi veya spesifikasyonu.

Özellikler

  • ad

    dize isteğe bağlı

    Çerezin adı.

  • value

    dize isteğe bağlı

    Bir çerezin değeri çift tırnak içinde doldurulabilir.

RequestMatcher

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

Özellikler

  • oluşturucu

    geçersiz

    constructor işlevi aşağıdaki gibi 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 değilse eşleşir.

  • excludeRequestHeaders

    HeaderFilter[] isteğe bağlı

    İstek başlıklarından hiçbiri, Başlık Filtrelerinden herhangi biriyle eşleşmiyorsa eşleşir.

  • excludeResponseHeaders

    HeaderFilter[] isteğe bağlı

    Yanıt başlıklarından hiçbiri, Başlık Filtrelerinden herhangi biriyle eşleşmiyorsa eşleşir.

  • firstPartyForCookiesUrl

    UrlFilter isteğe bağlı

    Desteği sonlandırıldı

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

    "Birinci taraf" için UrlFilter koşulları karşılanırsa eşleşir İsteğin URL'si. "Birinci taraf" Bir isteğin URL'si (varsa), isteğin hedef URL'sinden farklı olabilir ve neyin "birinci taraf" olarak kabul edildiğini açıklar üçüncü taraf çerezlerine izin verdiğinden emin olun.

  • requestHeaders

    HeaderFilter[] isteğe bağlı

    İstek başlıklarından bazıları Başlık Filtrelerinden 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ı

    Yanıt başlıklarından bazıları Başlık Filtrelerinden biriyle eşleşirse eşleşir.

  • sahneler

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

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

  • thirdPartyForCookies

    boole isteğe bağlı

    Desteği sonlandırıldı

    87 sürümünden itibaren yoksayıldı.

    Doğru değerine ayarlanırsa üçüncü taraf çerez politikalarına tabi olan istekleri eşleştirir. Yanlış değerine ayarlanırsa tüm diğer 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ında bir çerezin spesifikasyonu.

Özellikler

  • alan

    dize isteğe bağlı

    Alan çerezi özelliğinin değeri.

  • geçerlilik bitiş tarihi

    dize isteğe bağlı

    Geçerliliği sona eren çerez özelliğinin değeri.

  • httpOnly

    dize isteğe bağlı

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

  • maxAge

    sayı isteğe bağlı

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

  • ad

    dize isteğe bağlı

    Çerezin adı.

  • yol

    dize isteğe bağlı

    Yol çerezi özelliğinin değeri.

  • güvenli

    dize isteğe bağlı

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

  • value

    dize isteğe bağlı

    Bir çerezin değeri çift tırnak içinde doldurulabilir.

SendMessageToExtension

declarativeWebRequest.onMessage etkinliğini tetikler.

Özellikler

SetRequestHeader

Belirtilen adın istek başlığını, belirtilen değere ayarlar. Daha önce belirtilen ada sahip bir üstbilgi yoksa yeni bir üstbilgi oluşturulur. Başlık 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"

"onAuthZorunlu"

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

        dize isteğe bağlı

        İsteği gönderen dokümanın UUID'si.

      • Dokümanın bulunduğu yaşam döngüsü.

      • frameId

        sayı

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

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

      • mesaj

        dize

        Görüşme komut dosyası tarafından gönderilen mesaj.

      • method

        dize

        Standart HTTP yöntemi.

      • parentDocumentId

        dize isteğe bağlı

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

      • 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. Bir tarayıcı oturumundaki istek kimlikleri benzersizdir. Sonuç olarak aynı isteğin farklı etkinliklerini ilişkilendirmek için kullanılabilirler.

      • aşama

        Sahne

        Ağ isteği aşamasında etkinliğin tetiklendiği 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ı

        Dönemden bu yana milisaniye cinsinden bu sinyalin tetiklenme süresi.

      • İ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