chrome.declarativeNetRequest (original) (raw)

Açıklama

chrome.declarativeNetRequest API, bildirim kuralları belirtilerek ağ isteklerini engellemek veya değiştirmek için kullanılır. Bu sayede uzantılar, ağ isteklerini engellemeden ve içeriklerini görüntülemeden değiştirebilir. Böylece daha fazla gizlilik sağlanır.

İzinler

declarativeNetRequest
declarativeNetRequestWithHostAccess

"declarativeNetRequest" ve "declarativeNetRequestWithHostAccess" izinleri aynı özellikleri sağlar. Bu izinler arasındaki fark, izinlerin istendiği veya verildiği zamandır.

"declarativeNetRequest"

Yükleme sırasında izin uyarısını tetikler ancak allow, allowAllRequests ve block kurallarına örtülü erişim sağlar. Toplantı sahiplerinden tam erişim isteğinde bulunmanız gerekmemesi için mümkün olduğunda bu yöntemi kullanın.

"declarativeNetRequestFeedback"

Paketlenmemiş uzantılar için hata ayıklama özelliklerini etkinleştirir. Özellikle getMatchedRules() ve onRuleMatchedDebug.

"declarativeNetRequestWithHostAccess"

Yükleme sırasında izin uyarısı gösterilmez ancak bir ana makinede herhangi bir işlem yapabilmek için ana makine izinleri istemeniz gerekir. Bu, halihazırda ana makine izinlerine sahip bir uzantıda ek uyarılar oluşturmadan bildirimli ağ isteği kurallarını kullanmak istediğinizde uygundur.

Kullanılabilirlik

Manifest

Daha önce açıklanan izinlere ek olarak, belirli kural grubu türleri (özellikle statik kural grupları) "declarative_net_request" manifest anahtarının bildirilmesini gerektirir. Bu anahtar, "rule_resources" adlı tek bir anahtara sahip bir sözlük olmalıdır. Bu anahtar, aşağıda gösterildiği gibi Ruleset türünde sözlükler içeren bir dizidir. (Yalnızca bir dizi olduğundan "Ruleset" adının manifestin JSON'ında görünmediğini unutmayın.) Statik kural kümeleri bu belgenin ilerleyen kısımlarında açıklanmaktadır.

{
  "name": "My extension",
  ...

  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback"
  ],
  "host_permissions": [
    "http://www.blogger.com/*",
    "http://*.google.com/*"
  ],
  ...
}

Kurallar ve kural kümeleri

Bu API'yi kullanmak için bir veya daha fazla kural grubu belirtin. Kural grubu, bir dizi kural içerir. Tek bir kural aşağıdakilerden birini yapar:

Biraz farklı şekillerde yönetilen üç tür kural grubu vardır.

Dinamik

Tarayıcı oturumlarında ve uzantı yükseltmelerinde kalıcıdır ve bir uzantı kullanılırken JavaScript kullanılarak yönetilir.

Oturum

Tarayıcı kapatıldığında ve uzantının yeni bir sürümü yüklendiğinde temizlenir. Oturum kuralları, bir uzantı kullanılırken JavaScript ile yönetilir.

Statik

Uzantı yüklendiğinde veya yükseltildiğinde paketlenir, yüklenir ve güncellenir. Statik kurallar, JSON biçimli kural dosyalarında depolanır ve manifest dosyasında listelenir.

Dinamik ve oturum kapsamlı kural kümeleri

Dinamik ve oturum kuralları, bir uzantı kullanılırken JavaScript ile yönetilir.

Bu kural grubu türlerinden yalnızca birer tane vardır. Bir uzantı, kural sınırları aşılmadığı sürece updateDynamicRules() ve updateSessionRules() işlevlerini çağırarak kuralları dinamik olarak ekleyebilir veya kaldırabilir. Kural sınırları hakkında bilgi edinmek için Kural sınırları başlıklı makaleyi inceleyin. Kod örnekleri bölümünde bununla ilgili bir örnek görebilirsiniz.

Statik kural kümeleri

Dinamik ve oturum kurallarının aksine, statik kurallar bir uzantı yüklendiğinde veya yükseltildiğinde paketlenir, yüklenir ve güncellenir. Bu dosyalar, yukarıda açıklandığı gibi "declarative_net_request" ve "rule_resources" anahtarları kullanılarak uzantıya belirtilen JSON biçimindeki kural dosyalarında ve bir veya daha fazla Ruleset sözlüğünde depolanır. Ruleset sözlüğü, kural dosyasına giden bir yolu, dosyada bulunan kural grubunun kimliğini ve kural grubunun etkin olup olmadığını içerir. Son ikisi, bir kural grubunu programatik olarak etkinleştirdiğinizde veya devre dışı bıraktığınızda önemlidir.

{
  ...
  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    },
    ...
    ]
  }
  ...
}

Kural dosyalarını test etmek için uzantınızı paketi açılmış olarak yükleyin. Geçersiz statik kurallarla ilgili hata ve uyarılar yalnızca açılmış uzantılar için gösterilir. Paketlenmiş uzantılardaki geçersiz statik kurallar yoksayılır.

Hızlı inceleme

Statik kural kümelerinde yapılan değişiklikler, hızlandırılmış incelemeye uygun olabilir. Uygun değişiklikler için hızlandırılmış inceleme başlıklı makaleyi inceleyin.

Statik kuralları ve kural kümelerini etkinleştirme ve devre dışı bırakma

Hem tek tek statik kurallar hem de eksiksiz statik kural kümeleri çalışma zamanında etkinleştirilebilir veya devre dışı bırakılabilir.

Etkinleştirilen statik kurallar ve kural kümeleri, tarayıcı oturumları arasında korunur. Her ikisi de uzantı güncellemelerinde kalıcı olmaz. Bu nedenle, güncellemeden sonra yalnızca kural dosyalarınızda bırakmayı seçtiğiniz kurallar kullanılabilir.

Performansı korumak amacıyla aynı anda etkinleştirilebilecek kural ve kural grubu sayısı da sınırlıdır. Etkinleştirilebilecek ek kural sayısını kontrol etmek için getAvailableStaticRuleCount() numaralı telefonu arayın. Kural sınırları hakkında bilgi edinmek için Kural sınırları başlıklı makaleyi inceleyin.

Statik kuralları etkinleştirmek veya devre dışı bırakmak için updateStaticRules() numaralı telefonu arayın. Bu yöntem, etkinleştirilecek veya devre dışı bırakılacak kuralların kimlik dizilerini içeren bir UpdateStaticRulesOptions nesnesi alır. Kimlikler, Ruleset sözlüğünün "id" anahtarı kullanılarak tanımlanır. En fazla 5.000 devre dışı bırakılmış statik kural olabilir.

Statik kural kümelerini etkinleştirmek veya devre dışı bırakmak için updateEnabledRulesets() numaralı telefonu arayın. Bu yöntem, etkinleştirilecek veya devre dışı bırakılacak kural kümelerinin kimlik dizilerini içeren bir UpdateRulesetOptions nesnesi alır. Kimlikler, Ruleset sözlüğünün "id" anahtarı kullanılarak tanımlanır.

Kural oluşturma

Türden bağımsız olarak, bir kural aşağıdaki şekilde gösterildiği gibi dört alanla başlar. "id" ve "priority" tuşları bir sayı alırken "action" ve "condition" tuşları çeşitli engelleme ve yönlendirme koşulları sağlayabilir. Aşağıdaki kural, "foo.com" kaynağından gelen ve alt dize olarak "abc" içeren tüm URL'lere yönelik komut dosyası isteklerini engeller.

{
  "id" : 1,
  "priority": 1,
  "action" : { "type" : "block" },
  "condition" : {
    "urlFilter" : "abc",
    "initiatorDomains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
}

URL eşleştirme

Declarative Net Request, URL'leri kalıp eşleme söz dizimi veya normal ifadelerle eşleştirme olanağı sunar.

URL filtresi söz dizimi

Bir kuralın "condition" anahtarı, belirtilen bir alan altındaki URL'lerde işlem yapmak için "urlFilter" anahtarına izin verir. Kalıp eşleştirme jetonlarını kullanarak kalıplar oluşturursunuz. Aşağıda birkaç örnek verilmiştir.

urlFilter Eşleşmeler Eşleşmez
"abc" https://abcd.comhttps://example.com/abcd https://ab.com
"abc*d" https://abcd.comhttps://example.com/abcxyzd https://abc.com
"| a.example.com" https://a.example.com/https://b.a.example.com/xyzhttps://a.example.company
"|https*" https://example.com http://example.com/http://https.com
"example*^123|" https://example.com/123http://abc.com/example?123 https://example.com/1234https://abc.com/example0123

Normal ifadeler

Koşullarda normal ifadeler de kullanılabilir. "regexFilter" anahtarını inceleyin. Bu koşullara uygulanan sınırlar hakkında bilgi edinmek için Normal ifadeler kullanan kurallar başlıklı makaleyi inceleyin.

İyi URL koşulları yazma

Kuralları yazarken her zaman alanın tamamıyla eşleşecek şekilde yazmaya özen gösterin. Aksi takdirde, kuralınız beklenmedik durumlarda eşleşebilir. Örneğin, kalıp eşleştirme söz dizimini kullanırken:

Şunları kullanabilirsiniz:

Benzer şekilde, normal ifadeyi sabitlemek için ^ ve / karakterlerini kullanın. Örneğin, ^https:\/\/www\.google\.com\/, https://www.google.com adresindeki herhangi bir yolla eşleşir.

Kural değerlendirmesi

DNR kuralları, tarayıcı tarafından ağ isteği yaşam döngüsünün çeşitli aşamalarında uygulanır.

İstekten önce

Bir istek yapılmadan önce, uzantı eşleşen bir kural ile isteği engelleyebilir veya yönlendirebilir (şemayı HTTP'den HTTPS'ye yükseltme dahil).

Tarayıcı, her uzantı için eşleşen kuralların listesini belirler. modifyHeaders işlemi içeren kurallar daha sonra ele alınacağından buraya dahil edilmemiştir. Ayrıca, responseHeaders koşuluna sahip kurallar daha sonra (yanıt başlıkları kullanılabilir olduğunda) değerlendirilir ve dahil edilmez.

Ardından, Chrome her uzantı için istek başına en fazla bir aday seçer. Chrome, eşleşen tüm kuralları önceliğe göre sıralayarak eşleşen bir kural bulur. Aynı önceliğe sahip kurallar, işleme göre sıralanır (allow veya allowAllRequests > block > upgradeScheme > redirect).

Aday bir allow veya allowAllRequests kuralıysa ya da isteğin yapıldığı çerçeve daha önce bu uzantıdan daha yüksek veya eşit öncelikli bir allowAllRequests kuralıyla eşleştiyse istek "izin verilir" ve uzantının istek üzerinde herhangi bir etkisi olmaz.

Birden fazla uzantı bu isteği engellemek veya yönlendirmek isterse tek bir işlem seçilir. Chrome bunu, kuralları block > redirect veya upgradeScheme > allow ya da allowAllRequests sırasına göre sıralayarak yapar. İki kural aynı türdeyse Chrome, en son yüklenen uzantının kuralını seçer.

Chrome, istek üst bilgilerini sunucuya göndermeden önce üst bilgiler, eşleşen modifyHeaders kurallarına göre güncellenir.

Chrome, tek bir uzantıda eşleşen tüm modifyHeaders kurallarını bularak yapılacak değişikliklerin listesini oluşturur. Eskiden olduğu gibi, yalnızca eşleşen allow veya allowAllRequests kurallarından daha yüksek önceliğe sahip kurallar dahil edilir.

Bu kurallar, Chrome tarafından daha yakın zamanda yüklenen bir uzantının kuralları her zaman daha eski bir uzantının kurallarından önce değerlendirilecek şekilde uygulanır. Ayrıca, bir uzantıdaki daha yüksek öncelikli kurallar, aynı uzantıdaki daha düşük öncelikli kurallardan önce uygulanır. Özellikle uzantılar arasında bile:

Yanıt alındıktan sonra

Yanıt başlıkları alındıktan sonra Chrome, responseHeaders koşuluna sahip kuralları değerlendirir.

Bu kuralları action ve priority'ye göre sıralayıp eşleşen bir allow veya allowAllRequests kuralı tarafından gereksiz hale getirilen kuralları hariç tuttuktan sonra (bu işlem, "İstekten önce" bölümündeki adımlarla aynı şekilde gerçekleşir) Chrome, isteği bir uzantı adına engelleyebilir veya yönlendirebilir.

Bir istek bu aşamaya ulaştıysa isteğin zaten sunucuya gönderildiğini ve sunucunun istek gövdesi gibi verileri aldığını unutmayın. Yanıt üstbilgileri koşulu içeren bir engelleme veya yönlendirme kuralı yine de çalışır ancak isteği gerçekten engelleyemez veya yönlendiremez.

Engelleme kuralı söz konusu olduğunda, bu durum, isteği yapan sayfanın engellenmiş bir yanıt alması ve Chrome'un isteği erken sonlandırmasıyla ele alınır. Yönlendirme kuralı söz konusu olduğunda Chrome, yönlendirilen URL'ye yeni bir istek gönderir. Bu davranışların uzantınızın gizlilik beklentilerini karşılayıp karşılamadığını değerlendirin.

İstek engellenmez veya yönlendirilmezse Chrome, modifyHeaders kurallarını uygular. Yanıt başlıklarında değişiklik yapma, "İstek başlıkları gönderilmeden önce" bölümünde açıklandığı şekilde çalışır. İstek başlıklarında yapılan değişiklikler, istek zaten gönderildiği için herhangi bir etki yaratmaz.

Güvenli kurallar

Güvenli kurallar, block, allow,allowAllRequests veya upgradeScheme işlemi olan kurallar olarak tanımlanır. Bu kurallar, artırılmış dinamik kural kotasına tabidir.

Kural sınırları

Kuralların tarayıcıda yüklenmesi ve değerlendirilmesi performans açısından ek yük oluşturur. Bu nedenle, API kullanılırken bazı sınırlar geçerlidir. Sınırlar, kullandığınız kuralın türüne bağlıdır.

Statik kurallar

Statik kurallar, manifest dosyasında belirtilen kural dosyalarında tanımlanan kurallardır. Bir uzantı, "rule_resources" manifest anahtarı kapsamında en fazla 100 statik kural grubu belirtebilir ancak bu kural gruplarından yalnızca 50'si aynı anda etkinleştirilebilir. İkincisine MAX_NUMBER_OF_ENABLED_STATIC_RULESETS denir. Bu kural kümeleri toplu olarak en az 30.000 kural içerir. Buna GUARANTEED_MINIMUM_STATIC_RULES denir.

Bundan sonra kullanılabilecek kural sayısı, kullanıcının tarayıcısına yüklenen tüm uzantılar tarafından kaç kuralın etkinleştirildiğine bağlıdır. Bu numarayı çalışma zamanında getAvailableStaticRuleCount() numarasını arayarak bulabilirsiniz. Kod örnekleri bölümünde bununla ilgili bir örnek görebilirsiniz.

Oturum kuralları

Bir uzantıda en fazla 5.000 oturum kuralı olabilir. Bu, MAX_NUMBER_OF_SESSION_RULES olarak gösterilir.

Chrome 120'den önce, birleştirilmiş 5.000 dinamik ve oturum kuralı sınırı vardı.

Dinamik kurallar

Bir uzantıda en az 5.000 dinamik kural olabilir. Bu, MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES olarak gösterilir.

Chrome 121'den itibaren, güvenli dinamik kurallar için 30.000 kural sınırı uygulanmaktadır. Bu sınır, MAX_NUMBER_OF_DYNAMIC_RULES olarak gösterilir. 5.000 sınırı içinde eklenen güvenli olmayan kurallar da bu sınıra dahil edilir.

Chrome 120'den önce, 5.000 birleşik dinamik ve oturum kuralı sınırı vardı.

Normal ifadeler kullanan kurallar

Tüm kural türlerinde normal ifadeler kullanılabilir ancak her türden toplam normal ifade kuralı sayısı 1.000'i aşamaz. Buna MAX_NUMBER_OF_REGEX_RULES adı verilir.

Ayrıca, her kural derlendikten sonra 2 KB'tan küçük olmalıdır. Bu, kuralın karmaşıklığıyla kabaca ilişkilidir. Bu sınırı aşan bir kural yüklemeye çalışırsanız aşağıdaki gibi bir uyarı görürsünüz ve kural yok sayılır.

rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.

Service worker'larla etkileşimler

Bildirimsel ağ isteği yalnızca ağ yığınına ulaşan istekler için geçerlidir. Bu, HTTP önbelleğinden gelen yanıtları içerir ancak bir hizmet çalışanının onfetch işleyicisinden geçen yanıtları içermeyebilir. declarativeNetRequest, hizmet çalışanı tarafından oluşturulan veya CacheStorage adresinden alınan yanıtları etkilemez ancak bir hizmet çalışanında yapılan fetch() çağrılarını etkiler.

Web'de erişilebilen kaynaklar

Bir declarativeNetRequest kuralı, herkese açık bir kaynak isteğinden web'de erişilemeyen bir kaynağa yönlendirme yapamaz. Bu durumda hata tetiklenir. Bu durum, belirtilen web'de erişilebilen kaynak, yönlendiren uzantıya ait olsa bile geçerlidir. declarativeNetRequest için kaynakları bildirmek üzere manifest dosyasının "web_accessible_resources" dizisini kullanın.

Ekleme işlemi yalnızca şu istek başlıkları için desteklenir: accept, accept-encoding, accept-language, access-control-request-headers, cache-control, connection, content-language, cookie, forwarded, if-match, if-none-match, keep-alive, range, te, trailer, transfer-encoding, upgrade, user-agent, via, want-digest, x-forwarded-for. Bu izin verilenler listesi büyük/küçük harfe duyarlıdır (449152902 numaralı hata).

Tarayıcı, bir istek veya yanıt üstbilgisine ekleme yaparken mümkün olduğunda uygun ayırıcıyı kullanır.

Örnekler

Kod örnekleri

Dinamik kuralları güncelleme

Aşağıdaki örnekte updateDynamicRules() işlevinin nasıl çağrılacağı gösterilmektedir. updateSessionRules() için de aynı prosedür uygulanır.

// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

Statik kural kümelerini güncelleme

Aşağıdaki örnekte, kullanılabilir kural kümelerinin sayısı ve etkinleştirilen statik kural kümelerinin maksimum sayısı dikkate alınarak kural kümelerinin nasıl etkinleştirileceği ve devre dışı bırakılacağı gösterilmektedir. Bu işlemi, ihtiyacınız olan statik kural sayısı izin verilen sayıyı aştığında yaparsınız. Bu özelliğin çalışması için bazı kural kümelerinizin yüklenmesi, bazılarının ise devre dışı bırakılması (manifest dosyasında "Enabled" ayarının false olarak belirlenmesi) gerekir.

async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
  // Create the options structure for the call to updateEnabledRulesets()
  let options = { enableRulesetIds: enableRulesetIds }
  // Get the number of enabled static rules
  const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();
  // Compare rule counts to determine if anything needs to be disabled so that
  // new rules can be enabled
  const proposedCount = enableRulesetIds.length;
  if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}

Kural örnekleri

Aşağıdaki örneklerde, Chrome'un bir uzantıdaki kurallara nasıl öncelik verdiği gösterilmektedir. Bu kuralları incelerken önceliklendirme kurallarını ayrı bir pencerede açmak isteyebilirsiniz.

"priority" anahtarı

Bu örneklerde *://*.example.com/* için ana makine izni gerekir.

Belirli bir URL'nin önceliğini belirlemek için (geliştirici tarafından tanımlanan) "priority" anahtarına, "action" anahtarına ve "urlFilter" anahtarına bakın. Bu örnekler, altlarında gösterilen örnek kural dosyasına atıfta bulunur.

https://google.com adresine gitme

Bu URL'yi kapsayan iki kural var: 1 ve 4 kimlikli kurallar. "block" işlemleri, "redirect" işlemlerinden daha yüksek önceliğe sahip olduğundan 1 kimlikli kural uygulanır. Diğer kurallar daha uzun URL'ler için olduğundan geçerli değildir.

https://google.com/1234 adresine gitme

Daha uzun URL nedeniyle, 2 kimlikli kural artık 1 ve 4 kimlikli kurallara ek olarak eşleşiyor. "allow", "block" ve "redirect"'den daha yüksek önceliğe sahip olduğundan 2 kimlikli kural uygulanır.

https://google.com/12345 adresine gitme

Bu URL, dört kuralın tümüyle eşleşiyor. Geliştirici tarafından tanımlanan önceliği gruptaki en yüksek öncelik olduğundan 3 kimlikli kural uygulanır.

[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {"urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "allow" },
    "condition": { "urlFilter": "||google.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 3,
    "priority": 2,
    "action": { "type": "block" },
    "condition": { "urlFilter": "||google.com/12345", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 4,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
    "condition": { "urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
]

Yönlendirmeler

Aşağıdaki örnekte, *://*.example.com/* için ana makine izni gerekir.

Aşağıdaki örnekte, example.com'dan gelen bir isteğin nasıl uzantının kendi içindeki bir sayfaya yönlendirileceği gösterilmektedir. Uzantı yolu /a.jpg, chrome-extension://EXTENSION_ID/a.jpg olarak çözümlenir. Burada EXTENSION_ID, uzantınızın kimliğidir. Bu özelliğin çalışması için manifest, /a.jpg uygulamasını web'de erişilebilen kaynak olarak bildirmelidir.

{
  "id": 1,
  "priority": 1,
  "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
  "condition": {
    "urlFilter": "||https://www.example.com/",
    "resourceTypes": ["main_frame"]
  }
}

Aşağıdaki örnekte, example.com'un bir alt alan adına yönlendirmek için "transform" anahtarı kullanılıyor. example.com'dan gelen tüm şemalı istekleri yakalamak için bir alan adı sabitleyicisi ("||") kullanılıyor. "transform" içindeki "scheme" anahtarı, alt alan adına yönlendirmelerde her zaman "https" kullanılacağını belirtiyor.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "transform": { "scheme": "https", "host": "new.example.com" }
    }
  },
  "condition": {
    "urlFilter": "||example.com/",
    "resourceTypes": ["main_frame"]
  }
}

Aşağıdaki örnekte, https://www.abc.xyz.com/path adresinden https://abc.xyz.com/path adresine yönlendirmek için normal ifadeler kullanılmaktadır. "regexFilter" anahtarında, noktaların nasıl kaçırıldığına ve yakalama grubunun "abc" veya "def"i nasıl seçtiğine dikkat edin. "regexSubstitution" anahtarı, "\1" kullanılarak normal ifadenin döndürülen ilk eşleşmesini belirtir. Bu durumda, yönlendirilen URL'den "abc" yakalanır ve yerine yerleştirilir.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "regexSubstitution": "https://\\1.xyz.com/"
    }
  },
  "condition": {
    "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
    "resourceTypes": [
      "main_frame"
    ]
  }
}

Aşağıdaki örnek, hem ana çerçevedeki hem de alt çerçevelerdeki tüm çerezleri kaldırır.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "modifyHeaders",
    "requestHeaders": [{ "header": "cookie", "operation": "remove" }]
  },
  "condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}

Türler

DomainType

Bu, isteğin kaynaklandığı çerçeveye göre birinci taraf mı yoksa üçüncü taraf mı olduğunu açıklar. Bir isteğin, isteğin kaynaklandığı çerçeveyle aynı alana (eTLD+1) sahip olması durumunda birinci taraf isteği olduğu söylenir.

Enum

"firstParty"
Ağ isteği, kaynaklandığı çerçeveye ait birinci taraf isteğidir.

"thirdParty"
Ağ isteği, kaynaklandığı çerçeveye göre üçüncü taraftır.

ExtensionActionOptions

Chrome 88 ve sonraki sürümler

Özellikler

GetDisabledRuleIdsOptions

Chrome 111 veya daha yeni bir sürüm

Özellikler

GetRulesFilter

Chrome 111 veya daha yeni bir sürüm

Özellikler

Chrome 128 veya daha yeni bir sürüm

Özellikler

Chrome 86 ve sonraki sürümler

Bu, "modifyHeaders" kuralı için olası işlemleri açıklar.

Enum

"append"
Belirtilen üstbilgi için yeni bir giriş ekler. Bir isteğin üstbilgileri değiştirilirken bu işlem yalnızca belirli üstbilgiler için desteklenir.

"set"
Belirtilen başlık için yeni bir değer ayarlar ve aynı ada sahip mevcut başlıkları kaldırır.

"remove"
Belirtilen başlığa ait tüm girişleri kaldırır.

IsRegexSupportedResult

Chrome 87 veya daha yeni bir sürüm

Özellikler

MatchedRule

Özellikler

MatchedRuleInfo

Özellikler

MatchedRuleInfoDebug

Özellikler

MatchedRulesFilter

Özellikler

Chrome 86 ve sonraki sürümler

Özellikler

QueryKeyValue

Özellikler

QueryTransform

Özellikler

Redirect

Özellikler

RegexOptions

Chrome 87 veya daha yeni bir sürüm

Özellikler

RequestDetails

Özellikler

RequestMethod

Chrome 91 veya daha yeni bir sürüm

Bu, bir ağ isteğinin HTTP istek yöntemini açıklar.

Enum

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

Bu, ağ isteğinin kaynak türünü açıklar.

Enum

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

Özellikler

RuleAction

Özellikler

RuleActionType

Belirli bir RuleCondition eşleşirse yapılacak işlem türünü açıklar.

Enum

"block"
Ağ isteğini engelle.

"redirect"
Ağ isteğini yönlendirin.

"allow"
Ağ isteğine izin verin. İstek, kendisiyle eşleşen bir izin verme kuralı varsa engellenmez.

"upgradeScheme"
İstek http veya ftp ise ağ isteği URL'sinin düzenini https'ye yükseltin.

"modifyHeaders"
Ağ isteğindeki istek/yanıt başlıklarını değiştirin.

"allowAllRequests"
Çerçeve isteğinin kendisi de dahil olmak üzere, çerçeve hiyerarşisi içindeki tüm isteklere izin verin.

RuleCondition

Özellikler

RuleConditionKeys

Enum

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

Özellikler

RulesMatchedDetails

Özellikler

TabActionCountUpdate

Chrome 89 ve sonraki sürümler

Özellikler

TestMatchOutcomeResult

Chrome 103 veya daha yeni bir sürüm

Özellikler

TestMatchRequestDetails

Chrome 103 veya daha yeni bir sürüm

Özellikler

UnsupportedRegexReason

Chrome 87 veya daha yeni bir sürüm

Belirli bir normal ifadenin neden desteklenmediğini açıklar.

Enum

"syntaxError"
Normal ifade sözdizimi açısından hatalı veya RE2 söz diziminde kullanılamayan özellikler kullanıyor.

"memoryLimitExceeded"
Normal ifade, bellek sınırını aşıyor.

UpdateRuleOptions

Chrome 87 veya daha yeni bir sürüm

Özellikler

UpdateRulesetOptions

Chrome 87 veya daha yeni bir sürüm

Özellikler

UpdateStaticRulesOptions

Chrome 111 veya daha yeni bir sürüm

Özellikler

URLTransform

Özellikler

Özellikler

DYNAMIC_RULESET_ID

Uzantı tarafından eklenen dinamik kurallar için kural grubu kimliği.

GETMATCHEDRULES_QUOTA_INTERVAL

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules görüşmelerinin yapılabileceği, dakika cinsinden belirtilen zaman aralığı. Ek aramalar hemen başarısız olur ve runtime.lastError ayarlanır. Not: Kullanıcı hareketiyle ilişkili getMatchedRules çağrıları kotaya dahil değildir.

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 ve sonraki sürümler

Etkinleştirilmiş statik kural kümelerinde bir uzantıya garanti edilen minimum statik kural sayısı. Bu sınırın üzerindeki tüm kurallar, genel statik kural sınırına dahil edilir.

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

getMatchedRules işlevinin GETMATCHEDRULES_QUOTA_INTERVAL süresi içinde çağrılabileceği sayı.

MAX_NUMBER_OF_DYNAMIC_RULES

Bir uzantının ekleyebileceği maksimum dinamik kural sayısı.

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Bir uzantının aynı anda etkinleştirebileceği maksimum statik Rulesets sayısı.

MAX_NUMBER_OF_REGEX_RULES

Bir uzantının ekleyebileceği maksimum normal ifade kuralı sayısı. Bu sınır, dinamik kurallar kümesi ve kural kaynakları dosyasında belirtilenler için ayrı ayrı değerlendirilir.

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 ve sonraki sürümler

Bir uzantının ekleyebileceği maksimum oturum kapsamlı kural sayısı.

MAX_NUMBER_OF_STATIC_RULESETS

Bir uzantının "rule_resources" manifest anahtarının bir parçası olarak belirtebileceği maksimum statik Rulesets sayısı.

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 ve sonraki sürümler

Bir uzantının ekleyebileceği maksimum "güvenli olmayan" dinamik kural sayısı.

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 ve sonraki sürümler

Bir uzantının ekleyebileceği maksimum "güvenli olmayan" oturum kapsamlı kural sayısı.

SESSION_RULESET_ID

Chrome 90 veya daha yeni bir sürüm

Uzantı tarafından eklenen oturum kapsamlı kurallar için kural grubu kimliği.

Yöntemler

getAvailableStaticRuleCount()

Chrome 89 ve sonraki sürümler

chrome.declarativeNetRequest.getAvailableStaticRuleCount(): Promise

Bir uzantının genel statik kural sınırına ulaşılmadan önce etkinleştirebileceği statik kural sayısını döndürür.

İadeler

getDisabledRuleIds()

Chrome 111 veya daha yeni bir sürüm

chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
): Promise<number[]>

Belirtilen Ruleset içinde şu anda devre dışı olan statik kuralların listesini döndürür.

Parametreler

İadeler

getDynamicRules()

chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

Uzantı için geçerli dinamik kurallar grubunu döndürür. Arayanlar, filter belirterek getirilen kurallar listesini isteğe bağlı olarak filtreleyebilir.

Parametreler

İadeler

getEnabledRulesets()

chrome.declarativeNetRequest.getEnabledRulesets(): Promise<string[]>

Etkinleştirilmiş statik kural kümelerinin geçerli kümesinin kimliklerini döndürür.

İadeler

getMatchedRules()

chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
): Promise<RulesMatchedDetails>

Uzantı için eşleşen tüm kuralları döndürür. Arayanlar, filter belirterek eşleşen kurallar listesini isteğe bağlı olarak filtreleyebilir. Bu yöntem yalnızca "declarativeNetRequestFeedback" izni olan veya filter içinde belirtilen tabId için "activeTab" izni verilmiş uzantılar tarafından kullanılabilir. Not: Etkin bir dokümanla ilişkilendirilmeyen ve beş dakikadan uzun süre önce eşleştirilen kurallar döndürülmez.

Parametreler

İadeler

getSessionRules()

Chrome 90 veya daha yeni bir sürüm

chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

Uzantı için geçerli oturum kapsamlı kurallar grubunu döndürür. Arayanlar, filter belirterek getirilen kurallar listesini isteğe bağlı olarak filtreleyebilir.

Parametreler

İadeler

isRegexSupported()

Chrome 87 veya daha yeni bir sürüm

chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
): Promise<IsRegexSupportedResult>

Belirtilen normal ifadenin regexFilter kural koşulu olarak desteklenip desteklenmeyeceğini kontrol eder.

Parametreler

İadeler

setExtensionActionOptions()

Chrome 88 ve sonraki sürümler

chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise

Sekmeler için işlem sayısının, uzantı işleminin rozet metni olarak gösterilip gösterilmeyeceğini yapılandırır ve bu işlem sayısının artırılması için bir yol sağlar.

Parametreler

İadeler

testMatchOutcome()

Chrome 103 veya daha yeni bir sürüm

chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
): Promise<TestMatchOutcomeResult>

Uzantının declarativeNetRequest kurallarından herhangi birinin varsayımsal bir istekle eşleşip eşleşmeyeceğini kontrol eder. Not: Bu özellik yalnızca uzantı geliştirme sırasında kullanılmak üzere tasarlandığından yalnızca paketi açılmış uzantılar için kullanılabilir.

Parametreler

İadeler

updateDynamicRules()

chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
): Promise

Uzantının mevcut dinamik kurallarını değiştirir. Önce options.removeRuleIds içinde listelenen kimliklere sahip kurallar kaldırılır, ardından options.addRules içinde verilen kurallar eklenir. Notlar:

Parametreler

İadeler

updateEnabledRulesets()

chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
): Promise

Uzantı için etkinleştirilen statik kural kümelerini günceller. Önce options.disableRulesetIds içinde listelenen kimliklere sahip kural kümeleri kaldırılır, ardından options.enableRulesetIds içinde listelenen kural kümeleri eklenir. Etkinleştirilen statik kurallar kümelerinin oturumlar arasında kalıcı olduğunu ancak uzantı güncellemeleri arasında kalıcı olmadığını unutmayın. Yani rule_resources manifest anahtarı, her uzantı güncellemesinde etkinleştirilen statik kurallar kümelerini belirler.

Parametreler

İadeler

updateSessionRules()

Chrome 90 veya daha yeni bir sürüm

chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
): Promise

Uzantı için mevcut oturum kapsamlı kurallar grubunu değiştirir. Önce options.removeRuleIds içinde listelenen kimliklere sahip kurallar kaldırılır, ardından options.addRules içinde verilen kurallar eklenir. Notlar:

Parametreler

İadeler

updateStaticRules()

Chrome 111 veya daha yeni bir sürüm

chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise

Ruleset içindeki statik kuralları tek tek devre dışı bırakır ve etkinleştirir. Devre dışı bırakılmış bir Ruleset'a ait kurallarda yapılan değişiklikler, bir sonraki etkinleştirme işleminde geçerlilik kazanır.

Parametreler

İadeler

Etkinlikler

onRuleMatchedDebug

chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
  callback: function,
)

Bir kural bir istekle eşleştiğinde tetiklenir. Yalnızca hata ayıklama amacıyla kullanılmak üzere tasarlandığından, yalnızca "declarativeNetRequestFeedback" izni olan açılmış uzantılarda kullanılabilir.

Parametreler