chrome.declarativeWebRequest

Açıklama

Not: Bu API'nin desteği sonlandırılmıştır. Bunun yerine declarativeNetRequest API'sine göz atın. Devam eden istekleri yakalamak, engellemek veya değiştirmek için chrome.declarativeWebRequest API'yi kullanın. Gidiş dönüş gecikmelerini azaltan ve daha yüksek verimlilik sağlayan chrome.webRequest API'sinden önemli ölçüde daha hızlıdır. Bunun nedeni, 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 ana makine izni 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 mesaj gönderilmez.

Uzantı, https://www.google.com adresinden https://mail.google.com adresine yönlendirme kuralı oluşturamıyor.

Kurallar

Bildirimsel Web İsteği API'si, Bildirimsel API kavramlarını izler. Kuralları chrome.declarativeWebRequest.onRequest etkinlik nesnesine 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. Kullanıcı çok amaçlı adres çubuğuna https://www.example.com yazdığında aşağıdaki RequestMatcher, 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 ile ilgili 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 şekilde 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ı unutmamak önemlidir. 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 zaten 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 zaten 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 başlığı 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

    geçersiz

    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. Çerezin kullanım ömrü, "max-age" veya "expires" çerez özelliklerine göre hesaplanır. Her ikisi de belirtilmişse çerez ömrünü hesaplamak için "max-age" kullanılır.

  • ageUpperBound

    number isteğe bağlı

    Çerezin kullanım ömrüyle ilgili ü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. Çerezin kullanım ömrü, "max-age" veya "expires" çerez özelliklerine göre hesaplanır. Her ikisi de belirtilmişse çerez ömrünü hesaplamak için "max-age" kullanılır.

  • alan

    dize isteğe bağlı

    Alan adı çerez ö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 çerezi ö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 kullanım ömrü yoktur.

  • value

    dize isteğe bağlı

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

HeaderFilter

İstek üst bilgilerini çeşitli ölçütlere göre filtreler. Birden fazla ölçüt, bağlaç olarak değerlendirilir.

Özellikler

  • nameContains

    string | string[] 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

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

    Üstbilgi değeri belirtilen dizelerin tümünü 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 şu şekilde görünür: 

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

  • hasTag

    dize isteğe bağlı

    Ayarlanırsa belirtilen etikete sahip kurallar yoksayılır. Bu yoksayma 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 yok sayılabilir veya yok sayılmayabilir.

  • lowerPriorityThan

    number isteğe bağlı

    Ayarlanırsa belirtilen değerden daha düşük önceliğe sahip kurallar göz ardı edilir. 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 ifadelerde RE2 söz dizimi kullanılır.

Özellikler

  • oluşturucu

    geçersiz

    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

    geçersiz

    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

    geçersiz

    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 başlığından) listede yoksa eşleşir.

  • excludeRequestHeaders

    HeaderFilter[] isteğe bağlı

    İstek üst bilgilerinden hiçbiri HeaderFilters'lardan biriyle eşleşmediğinde eşleşir.

  • excludeResponseHeaders

    HeaderFilter[] isteğe bağlı

    Yanıt başlıklarından hiçbiri HeaderFilters'dan herhangi biriyle eşleşmezse eşleşir.

  • firstPartyForCookiesUrl

    UrlFilter isteğe bağlı

    Kullanımdan kaldırıldı

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

    İsteğin "birinci taraf" URL'si için UrlFilter koşulları karşılanıyorsa eşleşir. Bir isteğin "birinci taraf" URL'si, mevcut olduğunda 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 üst bilgilerinden 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 üst bilgilerinden bazıları HeaderFilters'dan biriyle eşleşirse eşleşir.

  • sahneler

    Stage[] isteğe bağlı

    Aşamaları açıklayan bir dize listesi içerir. İzin verilen değerler "onBeforeRequest", "onBeforeSendHeaders", "onHeadersReceived", "onAuthRequired" şeklindedir. Bu özellik varsa geçerli aşamalar, listelenen aşamalarla sınırlanı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.

    True 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 çerezin spesifikasyonu.

Özellikler

  • alan

    dize isteğe bağlı

    Alan adı çerez ö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 çerezi ö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. Başlık 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 gönderen 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 sarmalayan çerçevenin kimliği. Üst çerçeve yoksa -1 olarak ayarlayın.

      • requestId

        dize

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

      • aşama

        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 sekme ile 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