chrome.declarativeNetRequest

Opis

Interfejs API chrome.declarativeNetRequest służy do blokowania lub modyfikowania żądań sieciowych przez określenie reguł deklaratywnych. Dzięki temu rozszerzenia mogą modyfikować żądania sieciowe bez ich przechwytywania i wyświetlania treści, co zapewnia większą prywatność.

Uprawnienia

declarativeNetRequest
declarativeNetRequestWithHostAccess

Uprawnienia „declarativeNetRequest” i „declarativeNetRequestWithHostAccess” zapewniają te same możliwości. Różnica między nimi polega na tym, kiedy trzeba poprosić o uprawnienia lub je przyznać.

"declarativeNetRequest"
Aktywuje ostrzeżenie o uprawnieniach podczas instalacji, ale zapewnia niejawny dostęp do reguł allow, allowAllRequests i block. Używaj go, gdy to możliwe, aby uniknąć prośby o pełny dostęp do hostów.
"declarativeNetRequestFeedback"
Udostępnia funkcje debugowania dotyczące rozpakowanych rozszerzeń, w szczególności getMatchedRules() i onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
Ostrzeżenie o uprawnieniach nie jest wyświetlane podczas instalacji, ale przed wykonaniem jakichkolwiek działań na hoście musisz poprosić o uprawnienia hosta. Jest to przydatne, gdy chcesz użyć deklaratywnych reguł żądań netto w rozszerzeniu, które ma już uprawnienia hosta bez generowania dodatkowych ostrzeżeń.

Dostępność

Chrome 84 lub nowszy

Plik manifestu

Oprócz uprawnień opisanych powyżej niektóre typy zestawów reguł, a także statyczne zestawy reguł, wymagają zadeklarowania klucza manifestu "declarative_net_request", który powinien być słownikiem z pojedynczym kluczem o nazwie "rule_resources". Ten klucz jest tablicą zawierającą słowniki typu Ruleset, jak pokazano poniżej. Pamiętaj, że nazwa „Ruleset” (Zestaw reguł) nie pojawia się w pliku JSON manifestu, ponieważ jest to tylko tablica. Statyczne zestawy reguł zostały opisane w dalszej części tego dokumentu.

{
  "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/*"
  ],
  ...
}

Pojęcia i wykorzystanie

Aby użyć tego interfejsu API, określ co najmniej 1 zestaw reguł. Zestaw reguł zawiera tablicę reguł. Pojedyncza reguła może wykonywać jedną z tych czynności:

  • Blokuj żądanie sieciowe.
  • Uaktualnij schemat (z HTTP do https).
  • Zapobiegaj blokowaniu żądania, negując wszystkie pasujące zablokowane reguły.
  • Przekieruj żądanie sieciowe.
  • modyfikować nagłówki żądania lub odpowiedzi;

Istnieją 3 typy zestawów reguł, którymi zarządzasz w nieco inny sposób.

Dynamiczna
Podczas korzystania z rozszerzenia działają w czasie sesji przeglądarki i uaktualniania rozszerzeń, a w czasie ich używania są zarządzane za pomocą JavaScriptu.
Sesja
Wyczyść, gdy przeglądarka się wyłączy i po zainstalowaniu nowej wersji rozszerzenia. Reguły sesji są zarządzane przez JavaScript, gdy używane jest rozszerzenie.
Statyczny
Pakiety, instalowane i aktualizowane podczas instalowania lub uaktualniania rozszerzenia. Reguły statyczne są przechowywane w plikach reguł w formacie JSON i są widoczne w pliku manifestu.

W kilku kolejnych sekcjach znajdziesz szczegółowe informacje o typach zestawów reguł.

Zestawy reguł dynamicznych i ograniczonych do sesji

Zbiory reguł dynamicznych i sesji są zarządzane za pomocą JavaScriptu, gdy używane jest rozszerzenie.

  • Reguły dynamiczne pozostają niezmienne podczas sesji przeglądarki i uaktualniania rozszerzeń.
  • Reguły sesji są czyszczone po wyłączeniu przeglądarki i zainstalowaniu nowej wersji rozszerzenia.

Każdy z tych typów zestawów reguł może zawierać tylko 1 typ. Rozszerzenie może dynamicznie dodawać i usuwać reguły, wywołując parametry updateDynamicRules() i updateSessionRules(), o ile limity reguł nie zostaną przekroczone. Informacje o limitach reguł znajdziesz w artykule Limity reguł. Przykład znajdziesz w sekcji przykładowy kod.

Statyczne zestawy reguł

W przeciwieństwie do reguł dynamicznych i reguł dotyczących sesji reguły statyczne są pakowane, instalowane i aktualizowane podczas instalowania lub uaktualniania rozszerzenia. Są one przechowywane w plikach reguł w formacie JSON, co wskazuje rozszerzenie za pomocą kluczy "declarative_net_request" i "rule_resources" w sposób opisany powyżej, a także co najmniej 1 słownika Ruleset. Słownik Ruleset zawiera ścieżkę do pliku reguły, identyfikator zestawu reguł zawartych w pliku oraz informacje o tym, czy zestaw jest włączony czy wyłączony. Ostatnie dwa są ważne przy automatycznym włączaniu lub wyłączaniu zestawu reguł.

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

Aby przetestować pliki reguł, rozpakuj rozszerzenie. Błędy i ostrzeżenia dotyczące nieprawidłowych reguł statycznych są wyświetlane tylko w przypadku rozszerzeń bez pakietu. Nieprawidłowe reguły statyczne w pakietach rozszerzeń są ignorowane.

Przyspieszona weryfikacja

Zmiany w statycznych zestawach reguł mogą kwalifikować się do przyspieszonego sprawdzenia. Zapoznaj się z sekcją Szybsze sprawdzanie kwalifikujących się zmian.

Włączanie i wyłączanie reguł statycznych i zbiorów reguł

Zarówno pojedyncze reguły statyczne, jak i pełne statyczne zestawy reguł mogą być włączane lub wyłączane w czasie działania.

Zestaw włączonych reguł statycznych i zestawów reguł jest zachowywany przez wszystkie sesje przeglądarki. Żadne z nich nie są zachowywane przy aktualizacjach rozszerzeń, co oznacza, że po aktualizacji dostępne są tylko reguły, które zostawisz w plikach reguł.

Ze względu na wydajność obowiązują też limity liczby reguł i zestawów reguł, które można włączyć jednocześnie. Zadzwoń pod numer getAvailableStaticRuleCount(), aby sprawdzić, ile dodatkowych reguł można włączyć. Informacje o limitach reguł znajdziesz w artykule Limity reguł.

Aby włączyć lub wyłączyć statyczne reguły, wywołaj updateStaticRules(). Ta metoda przyjmuje obiekt UpdateStaticRulesOptions, który zawiera tablice identyfikatorów reguł do włączenia lub wyłączenia. Identyfikatory definiuje się za pomocą klucza "id" w słowniku Ruleset.

Aby włączyć lub wyłączyć statyczne rulesets, wywołaj updateEnabledRulesets(). Ta metoda przyjmuje obiekt UpdateRulesetOptions, który zawiera tablice identyfikatorów zestawów reguł do włączenia lub wyłączenia. Identyfikatory definiuje się za pomocą klucza "id" w słowniku Ruleset.

Utwórz reguły

Bez względu na typ reguła zaczyna się od czterech pól, jak pokazano poniżej. Klucze "id" i "priority" zabierają wartość liczbową, a klucze "action" i "condition" mogą określać kilka warunków blokowania i przekierowania. Poniższa reguła blokuje wszystkie żądania skryptu wysyłane z adresu "foo.com" do dowolnego adresu URL z podłańcuchem "abc".

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

Pasujące znaki urlFilter

Klucz "condition" reguły zezwala kluczowi "urlFilter" na wykonywanie działań na adresach URL w określonej domenie. Wzory możesz tworzyć za pomocą tokenów dopasowywania wzorców. Oto kilka przykładów:

urlFilter Odpowiada Nie pasuje
"abc" https://abcd.com
https://example.com/abcd		 https://ab.com
"abc*d" https://abcd.com
https://example.com/abcxyzd		 https://abc.com
"||a.example.com" https://a.example.com/
https://b.a.example.com/xyz		 https://example.com/
"|https*" https://example.com http://example.com/
http://https.com
"example*^123|" https://example.com/123
http://abc.com/example?123		 https://example.com/1234
https://abc.com/example0123

Nadawanie priorytetów regułom

Reguły są wywoływane przez żądania wysyłane ze stron internetowych. Jeśli do jednego żądania pasuje wiele reguł, należy nadać im priorytet. Z tej sekcji dowiesz się, jak są traktowane priorytetowo. Określanie priorytetów przebiega dwuetapowo.

  1. Priorytet jest określany dla reguł w rozszerzeniu.
  2. Jeśli więcej niż jedno rozszerzenie może stosować regułę do żądania, priorytet jest określany dla wszystkich rozszerzeń, które pasują do danego żądania.

Taki sposób dopasowywania: reguła, którą ma dane rozszerzenie, będzie mieć wyższy priorytet względem reguł z innych rozszerzeń.

Nadawanie priorytetów regułom w rozszerzeniu

W ramach pojedynczego rozszerzenia priorytety są ustalane w ten sposób:

  1. Zwracana jest reguła o najwyższym priorytecie zdefiniowanym przez programistę (czyli z polem "priority").

  2. Jeśli istnieje więcej niż 1 reguła o najwyższym priorytecie zdefiniowanym przez programistę, nadaje się ona priorytetom w polu "action" w następującej kolejności:

    1. allow
    2. allowAllRequests
    3. block
    4. upgradeScheme
    5. redirect

  3. Jeśli typ działania jest inny niż block lub redirect, sprawdzane są wszystkie pasujące reguły modifyHeaders. Pamiętaj, że jeśli istnieją reguły o priorytecie zdefiniowanym przez programistę niższym niż priorytet określony dla allow i allowAllRequests, są one ignorowane.

  4. Jeśli wiele reguł modyfikuje ten sam nagłówek, modyfikacje są określane przez zdefiniowane przez dewelopera pole "priority" oraz przez określone operacje.

    • Jeśli reguła jest dołączana do nagłówka, to reguły o niższym priorytecie mogą dołączać tylko do tego nagłówka. Operacje ustawiania i usuwania nie są dozwolone.
    • Jeśli reguła ustawia nagłówek, to reguły o niższym priorytecie mogą dołączać tylko do tego nagłówka. Inne modyfikacje nie są dozwolone.
    • Jeśli reguła usuwa nagłówek, reguły o niższym priorytecie nie mogą go dalej modyfikować.

Nadawanie priorytetów regułom między rozszerzeniami

Jeśli tylko jedno rozszerzenie ma regułę pasującą do żądania, jest ona stosowana. Jeśli jednak do żądania pasuje więcej niż jedno rozszerzenie, zostanie zastosowany ten proces:

  1. Priorytety są ustalane w polu "action" w następującej kolejności:

    1. block
    2. redirect lub upgradeScheme
    3. allow lub allowAllRequests

  2. Jeśli pasuje więcej niż 1 reguła, pierwszeństwo ma ostatnio zainstalowane rozszerzenie.

Bezpieczne reguły

Bezpieczne reguły to reguły z działaniem block, allow, allowAllRequests lub upgradeScheme. Reguły te podlegają zwiększonym limitom reguł dynamicznych.

Ograniczenia reguł

Wczytywanie i ocenianie reguł w przeglądarce wiąże się z dużą wydajnością, więc podczas korzystania z interfejsu API obowiązują pewne ograniczenia. Limity zależą od typu używanej reguły.

Reguły statyczne

Reguły statyczne to reguły określone w plikach reguł zadeklarowanych w pliku manifestu. W kluczu manifestu "rule_resources" rozszerzenie może zawierać maksymalnie 100 statycznych rulesets, ale jednocześnie można włączyć tylko 50 z tych zestawów reguł. Ta ostatnia nazywa się MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Łącznie dla tych zestawów reguł musi istnieć co najmniej 30 000 reguł. Jest to tzw. GUARANTEED_MINIMUM_STATIC_RULES.

Liczba dostępnych reguł zależy od tego, ile reguł są włączonych przez wszystkie rozszerzenia zainstalowane w przeglądarce użytkownika. Aby go znaleźć w czasie działania, zadzwoń pod numer getAvailableStaticRuleCount(). Przykład znajdziesz w sekcji przykładowy kod.

Reguły sesji

Rozszerzenie może mieć maksymalnie 5000 reguł sesji. Ta wartość jest widoczna jako MAX_NUMBER_OF_SESSION_RULES.

Przed wersją Chrome 120 obowiązywał limit 5000 reguł dynamicznych i reguł sesji.

Reguły dynamiczne

Rozszerzenie może mieć co najmniej 5000 reguł dynamicznych. Ta wartość jest widoczna jako MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

Od wersji Chrome 121 obowiązuje większy limit 30 tys. reguł dla bezpiecznych reguł dynamicznych (MAX_NUMBER_OF_DYNAMIC_RULES). Wszystkie niebezpieczne reguły, które zostaną dodane do limitu 5000 razy, również będą wliczane do tego limitu.

Przed wersją Chrome 120 obowiązywał limit 5000 reguł dynamicznych i reguł sesji.

Reguły korzystające z wyrażeń regularnych

Wszystkie typy reguł mogą używać wyrażeń regularnych, ale łączna liczba reguł dotyczących wyrażeń regularnych każdego typu nie może przekraczać 1000. Jest to tzw. MAX_NUMBER_OF_REGEX_RULES.

Dodatkowo każda reguła po skompilowaniu musi mieć mniej niż 2 KB. Wynika to w przybliżeniu ze złożoności reguły. Jeśli spróbujesz wczytać regułę, która przekracza ten limit, zobaczysz ostrzeżenie podobne do tego poniżej, a reguła zostanie zignorowana.

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

Interakcje z mechanizmami Service Worker

Parametr declarativeNetRequest obowiązuje tylko w przypadku żądań, które docierają do stosu sieciowego. Obejmuje to odpowiedzi z pamięci podręcznej HTTP, ale może nie uwzględniać odpowiedzi przekazywanych przez moduł obsługi onfetch skryptu service worker. declarativeNetRequest nie wpłynie na odpowiedzi generowane przez skrypt service worker ani pobierane z poziomu CacheStorage, ale wpłynie na wywołania fetch() wykonywane w skrypcie service worker.

Zasoby dostępne przez internet

Reguła declarativeNetRequest nie może przekierowywać z żądania zasobu publicznego do zasobu, który nie jest dostępny w internecie. Spowoduje to wyświetlenie błędu. Dzieje się tak nawet wtedy, gdy określony zasób dostępny w internecie należy do rozszerzenia przekierowującego. Aby zadeklarować zasoby na potrzeby funkcji declarativeNetRequest, użyj tablicy "web_accessible_resources" pliku manifestu.

Przykłady

Przykłady kodu

Zaktualizuj reguły dynamiczne

Z przykładu poniżej dowiesz się, jak wywołać funkcję updateDynamicRules(). Procedura dla elementu updateSessionRules() jest taka sama.

// 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
});

Zaktualizuj statyczne zestawy reguł

Poniższy przykład pokazuje, jak włączać i wyłączać zestawy reguł z uwzględnieniem liczby dostępnych i maksymalnej liczby włączonych zestawów reguł statycznych. Zrobisz to, gdy liczba reguł statycznych, których potrzebujesz, przekracza dozwoloną liczbę. Aby tak się stało, niektóre z Twoich zestawów reguł powinny być zainstalowane z wyłączonymi niektórymi z nich (w pliku manifestu ustaw "Enabled" na false).

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);
}

Przykłady reguł

Poniższe przykłady pokazują, jak Chrome nadaje priorytet regułom w rozszerzeniu. Aby je przejrzeć, otwórz w osobnym oknie reguły ustalania priorytetów.

Klucz „priorytetu”

Te przykłady wymagają uprawnień hosta do *://*.example.com/*.

Aby określić priorytet konkretnego adresu URL, użyj kluczy "priority" (zdefiniowanych przez programistę), kluczy "action" i "urlFilter". Podane przykłady odnoszą się do przykładowego pliku reguł widocznego pod nimi.

Przejście na stronę https://google.com
Ten adres URL obejmuje 2 reguły: reguły o identyfikatorach 1 i 4. Reguła o identyfikatorze 1 jest stosowana, ponieważ działania "block" mają wyższy priorytet niż działania "redirect". Pozostałe reguły nie mają zastosowania, ponieważ dotyczą dłuższych adresów URL.
Nawigacja do strony https://google.com/1234
Ze względu na dłuższy adres URL reguła o identyfikatorze 2 pasuje teraz do reguł o identyfikatorach 1 i 4. Reguła o identyfikatorze 2 jest stosowana, ponieważ zasada "allow" ma wyższy priorytet niż "block" i "redirect".
Nawigacja do strony https://google.com/12345
Wszystkie 4 reguły pasują do tego adresu URL. Reguła o identyfikatorze 3 jest stosowana, ponieważ jej priorytet zdefiniowany przez dewelopera jest najwyższym w grupie.
[
  {
    "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"] }
  },
]

Przekierowania

Ten przykład wymaga uprawnień hosta do uprawnienia *://*.example.com/*.

Z przykładu poniżej dowiesz się, jak przekierować żądanie z domeny example.com na stronę w samym rozszerzeniu. Ścieżka rozszerzenia /a.jpg prowadzi do: chrome-extension://EXTENSION_ID/a.jpg, gdzie EXTENSION_ID to identyfikator rozszerzenia. Aby to działało, plik manifestu powinien zadeklarować /a.jpg jako zasób dostępny przez internet.

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

Poniższy fragment używa klucza "transform" do przekierowania do subdomeny example.com. Wykorzystuje kotwicę nazwy domeny („||”) do przechwytywania żądań z dowolnym schematem z example.com. Klucz "scheme" w elemencie "transform" określa, że przekierowania do subdomeny zawsze używają „https”.

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

Następujący przykład pokazuje przekierowanie z https://www.abc.xyz.com/path do https://abc.xyz.com/path z użyciem wyrażeń regularnych. Zwróć uwagę na zmianę znaczenia kropek w kluczu "regexFilter" oraz że grupa przechwytywania ma ustawienie „abc” lub „def”. Klucz "regexSubstitution" określa pierwsze zwrócone dopasowanie wyrażenia regularnego z użyciem „\1”. W tym przypadku zapis „abc” jest przechwytywany z przekierowanego adresu URL i umieszczany w zastąpieniu.

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

nagłówków,

Poniższy przykład pokazuje usunięcie wszystkich plików cookie zarówno z ramki głównej, jak i wszystkich ramek podrzędnych.

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

Typy

DomainType

Wskazuje, czy żądanie jest własne czy pochodzące od innej firmy. Żądanie jest uznawane za własne, jeśli ma tę samą domenę (eTLD+1) co ramka, z której pochodzi.

Typ wyliczeniowy

"firstParty"
Żądanie sieciowe jest własne dla ramki, z której pochodzi.

"thirdParty"
Żądanie sieci jest usługą zewnętrzną względem ramki, z której pochodzi.

ExtensionActionOptions

Chrome 88 lub nowszy

Właściwości

  • displayActionCountAsBadgeText

    Wartość logiczna opcjonalna

    Określa, czy automatycznie wyświetlać liczbę działań na stronie jako tekst plakietki rozszerzenia. To ustawienie jest zapamiętywane w kolejnych sesjach.

  • tabUpdate

    Opcjonalne TabActionCountUpdate

    Chrome 89 lub nowszy

    Szczegóły dotyczące dostosowywania liczby działań na karcie.

GetDisabledRuleIdsOptions

Chrome 111 lub nowszy

Właściwości

  • rulesetId

    string,

    Identyfikator odpowiadający statycznemu elementowi Ruleset.

GetRulesFilter

Chrome 111 lub nowszy

Właściwości

  • ruleIds

    liczba[] opcjonalnie

    Jeśli określisz reguły, uwzględnione zostaną tylko reguły z pasującymi identyfikatorami.

HeaderOperation

Chrome 86 lub nowszy

Opisuje możliwe operacje reguły „modifyHeaders”.

Typ wyliczeniowy

"append"
Dodaje nowy wpis dla określonego nagłówka. Tej operacji nie można wykonać na nagłówkach żądań.

"set"
Ustawia nową wartość określonego nagłówka i usuwa wszystkie istniejące nagłówki o tej samej nazwie.

"remove"
usuwa wszystkie wpisy określonego nagłówka.

IsRegexSupportedResult

Chrome 87 lub nowszy

Właściwości

  • isSupported

    boolean

  • powód

    UnsupportedRegexReason opcjonalny

    Określa przyczynę, dla której wyrażenie regularne nie jest obsługiwane. Wartość podawana tylko wtedy, gdy isSupported ma wartość fałsz.

MatchedRule

Właściwości

  • ruleId

    Liczba

    Identyfikator pasującej reguły.

  • rulesetId

    string,

    Identyfikator Ruleset, do którego należy ta reguła. W przypadku reguły pochodzącej ze zbioru reguł dynamicznych wartość będzie równa DYNAMIC_RULESET_ID.

MatchedRuleInfo

Właściwości

  • reguła

    MatchedRule

  • tabId

    Liczba

    Identyfikator tabId karty, z której pochodzi żądanie, jeśli jest nadal aktywna. W innym przypadku – 1.

  • timeStamp

    Liczba

    Czas dopasowania reguły. Sygnatury czasowe będą odpowiadały konwencji JavaScriptu dotyczącej czasu, czyli liczby milisekund od początku epoki.

MatchedRuleInfoDebug

Właściwości

  • Poproś

    RequestDetails

    Szczegółowe informacje o żądaniu, w którego przypadku reguła została dopasowana.

  • reguła

    MatchedRule

MatchedRulesFilter

Właściwości

  • minTimeStamp

    liczba opcjonalnie

    Jeśli jest określony, pasuje tylko do reguł po podanej sygnaturze czasowej.

  • tabId

    liczba opcjonalnie

    Jeśli zostanie określona, będzie pasować tylko do reguł dla danej karty. Pasuje do reguł, które nie są powiązane z żadną aktywną kartą, jeśli ustawiona jest wartość -1.

ModifyHeaderInfo

Chrome 86 lub nowszy

Właściwości

  • nagłówek

    string,

    Nazwa nagłówka do zmodyfikowania.

  • operacja

    HeaderOperation

    Operacja do wykonania na nagłówku.

  • value

    ciąg znaków opcjonalny

    Nowa wartość nagłówka. Musi być określony w przypadku operacji append i set.

QueryKeyValue

Właściwości

  • klucz

    string,

  • replaceOnly

    Wartość logiczna opcjonalna

    Chrome 94 lub nowszy

    Jeśli ma wartość prawda, klucz zapytania jest zastępowany tylko wtedy, gdy już istnieje. W przeciwnym razie klucz jest dodawany, jeśli go nie ma. Wartość domyślna to fałsz.

  • value

    string,

QueryTransform

Właściwości

  • addOrReplaceParams

    QueryKeyValue[] opcjonalny

    Lista par klucz-wartość zapytania, które mają zostać dodane lub zastąpione.

  • removeParams

    string[] opcjonalnie

    Lista kluczy zapytania do usunięcia.

Redirect

Właściwości

  • extensionPath

    ciąg znaków opcjonalny

    Ścieżka względem katalogu rozszerzenia. Musi zaczynać się od „/”.

  • regexSubstitution

    ciąg znaków opcjonalny

    Wzorzec zastępowania dla reguł, które określają regexFilter. Pierwsze dopasowanie elementu regexFilter w adresie URL zostanie zastąpione tym wzorcem. W regexSubstitution do wstawiania odpowiednich grup przechwytywania można użyć cyfr po ukośniku odwrotnym (\1–\9). \0 oznacza cały pasujący tekst.

  • przekształcenie

    Opcjonalny URLTransform

    Przekształcenia adresów URL do wykonania.

  • URL

    ciąg znaków opcjonalny

    Przekierowanie. Przekierowania do adresów URL JavaScript są niedozwolone.

RegexOptions

Chrome 87 lub nowszy

Właściwości

  • isCaseSensitive

    Wartość logiczna opcjonalna

    Określa, czy w określonym regex jest rozróżniana wielkość liter. Wartość domyślna to true (prawda).

  • wyrażenie regularne

    string,

    Wyrażenie regularne do sprawdzenia.

  • requireCapturing

    Wartość logiczna opcjonalna

    Określa, czy regex wymaga przechwytywania. Przechwytywanie jest wymagane tylko w przypadku reguł przekierowania, które określają działanie regexSubstition. Wartość domyślna to false (fałsz).

RequestDetails

Właściwości

  • documentId

    ciąg znaków opcjonalny

    Chrome 106 lub nowszy

    Unikalny identyfikator dokumentu ramki, jeśli żądanie dotyczy ramki.

  • documentLifecycle

    Opcjonalny DocumentLifecycle

    Chrome 106 lub nowszy

    Cykl życia dokumentu z ramką, jeśli to żądanie dotyczy ramki.

  • frameId

    Liczba

    Wartość 0 oznacza, że żądanie jest realizowane w ramce głównej, a wartość dodatnia oznacza identyfikator ramki podrzędnej, w której dane żądanie jest realizowane. Jeśli wczytany jest dokument ramki (podrzędnej) (type to main_frame lub sub_frame), frameId wskazuje identyfikator ramki, a nie ramki zewnętrznej. Identyfikatory ramek są unikalne w obrębie danej karty.

  • frameType

    Opcjonalny FrameType

    Chrome 106 lub nowszy

    Typ ramki, jeśli żądanie dotyczy ramki.

  • inicjator

    ciąg znaków opcjonalny

    Źródło, w którym zainicjowano żądanie. Nie zmienia się to w przypadku przekierowań. Jeśli źródło jest nieprzezroczyste, używany jest ciąg znaków „null”.

  • method

    string,

    Standardowa metoda HTTP.

  • parentDocumentId

    ciąg znaków opcjonalny

    Chrome 106 lub nowszy

    Unikalny identyfikator dokumentu nadrzędnego ramki, jeśli żądanie dotyczy ramki i ma element nadrzędny.

  • parentFrameId

    Liczba

    Identyfikator ramki otaczającej klatkę, z której wysłano żądanie. Jeśli nie ma ramki nadrzędnej, ustaw wartość -1.

  • requestId

    string,

    Identyfikator żądania. Identyfikatory żądań są unikalne w obrębie sesji przeglądarki.

  • tabId

    Liczba

    Identyfikator karty, na której zachodzi żądanie. Jeśli żądanie nie jest związane z kartą, ustaw wartość –1.

  • Niestandardowy typ treści

    ResourceType

    Typ zasobu żądania.

  • URL

    string,

    Adres URL żądania.

RequestMethod

Chrome 91 lub nowszy

Opisuje metodę żądania HTTP żądania sieciowego.

Typ wyliczeniowy

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

ResourceType

Opisuje typ zasobu żądania sieciowego.

Typ wyliczeniowy

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

Rule

Właściwości

  • działaniu

    RuleAction

    Działanie, które należy podjąć w przypadku dopasowania tej reguły.

  • Warunek, który powoduje uruchomienie tej reguły.

  • id

    Liczba

    Identyfikator jednoznacznie identyfikujący regułę. Obowiązkowy i powinien wynosić >= 1.

  • kampanii

    liczba opcjonalnie

    Priorytet reguły. Domyślna wartość to 1. W przypadku określenia tego parametru powinien to być >= 1.

RuleAction

Właściwości

  • Przekieruj

    Przekierowanie opcjonalne

    Opisuje sposób wykonywania przekierowania. Może mieć zastosowanie tylko w przypadku reguł przekierowania.

  • requestHeaders

    ModifyHeaderInfo[] opcjonalny

    Chrome 86 lub nowszy

    Nagłówki żądania do zmodyfikowania. Tej formuły można użyć tylko wtedy, gdy RuleActionType ma wartość „modifyHeaders”.

  • responseHeaders

    ModifyHeaderInfo[] opcjonalny

    Chrome 86 lub nowszy

    Nagłówki odpowiedzi, które mają być zmodyfikowane dla żądania. Tej formuły można użyć tylko wtedy, gdy RuleActionType ma wartość „modifyHeaders”.

  • Niestandardowy typ treści

    RuleActionType

    Typ działania do wykonania.

RuleActionType

Opisuje rodzaj działania, jakie ma być wykonywane w przypadku spełnienia określonego warunku RuleCondition.

Typ wyliczeniowy

"block"
Zablokuj żądanie sieciowe.

"redirect"
Przekieruj żądanie sieciowe.

"allow"
Zezwól na żądanie sieciowe. Żądanie nie zostanie przechwycone, jeśli istnieje pasująca reguła zezwalająca.

"upgradeScheme"
Uaktualnij schemat adresu URL żądania sieciowego do HTTPS, jeśli żądanie dotyczy protokołu http lub ftp.

"modifyHeaders"
Modyfikuj nagłówki żądania/odpowiedzi z żądania sieciowego.

"allowAllRequests"
Zezwalaj na wszystkie żądania w hierarchii ramek, w tym samo żądanie ramki.

RuleCondition

Właściwości

  • domainType

    Opcjonalny DomainType

    Określa, czy żądanie sieciowe jest w domenie, z której pochodzi, jest żądaniem własnym czy od osoby trzeciej. Jeśli go pominiesz, wszystkie żądania zostaną zaakceptowane.

  • domeny

    string[] opcjonalnie

    Funkcja wycofana od Chrome 101

    Zamiast tego użyj initiatorDomains

    Reguła będzie dopasowywać tylko żądania sieciowe pochodzące z listy domains.

  • excludedDomains

    string[] opcjonalnie

    Funkcja wycofana od Chrome 101

    Zamiast tego użyj excludedInitiatorDomains

    Reguła nie będzie dopasowywać żądań sieciowych pochodzących z listy excludedDomains.

  • excludedInitiatorDomains

    string[] opcjonalnie

    Chrome 101 lub nowszy

    Reguła nie będzie dopasowywać żądań sieciowych pochodzących z listy excludedInitiatorDomains. Jeśli lista jest pusta lub pominięta, żadne domeny nie zostaną wykluczone. Ma to pierwszeństwo przed zasadą initiatorDomains.

    Uwagi:

    • Subdomeny, takie jak „a.example.com”, są również dozwolone.
    • Wpisy mogą się składać tylko z znaków ASCII.
    • Używaj kodowania punycode w domenach umiędzynarodowionych.
    • Ten identyfikator pasuje do inicjatora żądania, a nie do adresu URL żądania.
    • Subdomeny wymienionych domen również są wykluczone.
  • excludedRequestDomains

    string[] opcjonalnie

    Chrome 101 lub nowszy

    Reguła nie będzie dopasowywać żądań sieciowych, jeśli domena odpowiada jednej z domen na liście excludedRequestDomains. Jeśli lista jest pusta lub pominięta, żadne domeny nie zostaną wykluczone. Ma to pierwszeństwo przed zasadą requestDomains.

    Uwagi:

    • Subdomeny, takie jak „a.example.com”, są również dozwolone.
    • Wpisy mogą się składać tylko z znaków ASCII.
    • Używaj kodowania punycode w domenach umiędzynarodowionych.
    • Subdomeny wymienionych domen również są wykluczone.
  • excludedRequestMethods

    RequestMethod[] opcjonalny

    Chrome 91 lub nowszy

    Lista metod żądań, które nie pasują do reguły. Należy określić tylko jedną z tych właściwości: requestMethods lub excludedRequestMethods. Jeśli żadna z nich nie zostanie określona, dopasowywane będą wszystkie metody żądań.

  • excludedResourceTypes

    ResourceType[] opcjonalny

    Lista typów zasobów, które nie pasują do reguły. Należy określić tylko jedną z tych właściwości: resourceTypes lub excludedResourceTypes. Jeśli nie podasz żadnego z tych typów, zablokowane będą wszystkie typy zasobów z wyjątkiem „main_frame”.

  • excludedTabIds

    liczba[] opcjonalnie

    Chrome 92 lub nowszy

    Lista tabs.Tab.id, do których reguła nie powinna pasować. Identyfikator tabs.TAB_ID_NONE wyklucza żądania, które nie pochodzą z karty. Obsługiwane tylko w przypadku reguł ograniczonych do sesji.

  • initiatorDomains

    string[] opcjonalnie

    Chrome 101 lub nowszy

    Reguła będzie dopasowywać tylko żądania sieciowe pochodzące z listy initiatorDomains. Jeśli pominiesz listę, reguła będzie stosowana do żądań ze wszystkich domen. Pusta lista jest niedozwolona.

    Uwagi:

    • Subdomeny, takie jak „a.example.com”, są również dozwolone.
    • Wpisy mogą się składać tylko z znaków ASCII.
    • Używaj kodowania punycode w domenach umiędzynarodowionych.
    • Ten identyfikator pasuje do inicjatora żądania, a nie do adresu URL żądania.
    • Subdomeny wymienionych domen również są dopasowywane.
  • isUrlFilterCaseSensitive

    Wartość logiczna opcjonalna

    Określa, czy w polu urlFilter lub regexFilter (w zależności od tego, która z nich została określona) wielkość liter ma znaczenie. Wartość domyślna to false (fałsz).

  • regexFilter

    ciąg znaków opcjonalny

    Wyrażenie regularne pasujące do adresu URL żądania sieciowego. Ma on zgodność ze składnią RE2.

    Uwaga: można określić tylko jedną z tych właściwości: urlFilter lub regexFilter.

    Uwaga: pole regexFilter może się składać tylko ze znaków ASCII. Jest on sprawdzany w odniesieniu do adresu URL, w którym host jest kodowany w formacie punycode (w przypadku domen międzynarodowych) a wszystkie inne znaki spoza zestawu ASCII są kodowane w formacie UTF-8.

  • requestDomains

    string[] opcjonalnie

    Chrome 101 lub nowszy

    Reguła będzie dopasowywać żądania sieciowe tylko wtedy, gdy domena pasuje do jednej z listy requestDomains. Jeśli pominiesz listę, reguła będzie stosowana do żądań ze wszystkich domen. Pusta lista jest niedozwolona.

    Uwagi:

    • Subdomeny, takie jak „a.example.com”, są również dozwolone.
    • Wpisy mogą się składać tylko z znaków ASCII.
    • Używaj kodowania punycode w domenach umiędzynarodowionych.
    • Subdomeny wymienionych domen również są dopasowywane.
  • requestMethods

    RequestMethod[] opcjonalny

    Chrome 91 lub nowszy

    Lista metod żądań HTTP, które mogą być dopasowane do reguły. Pusta lista jest niedozwolona.

    Uwaga: określenie warunku reguły requestMethods spowoduje też wykluczenie żądań innych niż HTTP, a określenie excludedRequestMethods – nie.

  • resourceTypes

    ResourceType[] opcjonalny

    Lista typów zasobów, które reguła może pasować. Pusta lista jest niedozwolona.

    Uwaga: ten atrybut musi być określony w regułach allowAllRequests i może zawierać wyłącznie typy zasobów sub_frame oraz main_frame.

  • tabIds

    liczba[] opcjonalnie

    Chrome 92 lub nowszy

    Lista tabs.Tab.id, która powinna pasować do reguły. Identyfikator tabs.TAB_ID_NONE pasuje do żądań, które nie pochodzą z karty. Pusta lista jest niedozwolona. Obsługiwane tylko w przypadku reguł ograniczonych do sesji.

  • urlFilter

    ciąg znaków opcjonalny

    Wzorzec dopasowywany do adresu URL żądania sieciowego. Obsługiwane konstrukcje:

    '*' : symbol wieloznaczny: dopasowuje dowolną liczbę znaków.

    '|' : kotwica lewa/prawa: jeśli zostanie użyta na końcu wzorca, określa odpowiednio początek/koniec adresu URL.

    '||' : kotwica nazwy domeny: jeśli zostanie użyta na początku wzorca, określa początek (sub-)domeny adresu URL.

    '^' : separator: powoduje wyszukanie wszystkiego oprócz litery, cyfry lub jednej z tych wartości: _, -, . i %. Ta wartość jest zgodna także z końcem adresu URL.

    Dlatego ciąg urlFilter składa się z tych elementów: (opcjonalna kotwica nazwy lewej/domeny) + wzorzec + (opcjonalna prawa kotwica).

    Jeśli go pominiesz, dopasowywane będą wszystkie adresy URL. Pusty ciąg jest niedozwolony.

    Wzorzec zaczynający się od ||* nie jest dozwolony. Użyj w zamian zasady *.

    Uwaga: można określić tylko jedną z tych właściwości: urlFilter lub regexFilter.

    Uwaga: pole urlFilter może się składać tylko ze znaków ASCII. Jest on sprawdzany w odniesieniu do adresu URL, w którym host jest kodowany w formacie punycode (w przypadku domen międzynarodowych) a wszystkie inne znaki spoza zestawu ASCII są kodowane w formacie UTF-8. Jeśli na przykład adres URL żądania to http://abc.р디?q=pojawiały się w polu urlFilter, zostaną dopasowane do adresu URL http://abc.xn--p1ai/?q=%D1%84.

Ruleset

Właściwości

  • włączone

    boolean

    Określa, czy zestaw reguł jest domyślnie włączony.

  • id

    string,

    Niepusty ciąg znaków jednoznacznie identyfikujący zestaw reguł. Identyfikatory rozpoczynające się od „_” są zarezerwowane do użytku wewnętrznego.

  • ścieżka

    string,

    Ścieżka zestawu reguł JSON względem katalogu rozszerzenia.

RulesMatchedDetails

Właściwości

TabActionCountUpdate

Chrome 89 lub nowszy

Właściwości

  • Zwiększ

    Liczba

    Kwota, o którą zwiększa się liczba działań na karcie. Wartości ujemne będą zmniejszać liczbę.

  • tabId

    Liczba

    Karta, dla której ma zostać zaktualizowana liczba działań.

TestMatchOutcomeResult

Chrome 103 lub nowszy

Właściwości

  • matchedRules

    MatchedRule[] (Reguła dopasowana)

    Reguły (jeśli występują), które pasują do hipotetycznego żądania.

TestMatchRequestDetails

Chrome 103 lub nowszy

Właściwości

  • inicjator

    ciąg znaków opcjonalny

    Adres URL inicjatora (jeśli istnieje) hipotetycznego żądania.

  • method

    Opcjonalny RequestMethod

    Standardowa metoda HTTP hipotetycznego żądania. Domyślna wartość to „get” w przypadku żądań HTTP i ignorowana w przypadku żądań innych niż HTTP.

  • tabId

    liczba opcjonalnie

    Identyfikator karty, w której zachodzi hipotetyczne żądanie. Nie musi odpowiadać faktycznemu identyfikatorowi karty. Wartość domyślna to -1, co oznacza, że żądanie nie jest związane z kartą.

  • Niestandardowy typ treści

    ResourceType

    Typ zasobu hipotetycznego żądania.

  • URL

    string,

    Adres URL hipotetycznego żądania.

UnsupportedRegexReason

Chrome 87 lub nowszy

Opisuje powód, dla którego dane wyrażenie regularne nie jest obsługiwane.

Typ wyliczeniowy

"syntaxError"
Wyrażenie regularne jest niepoprawne składniowo lub korzysta z funkcji niedostępnych w składni RE2.

"memoryLimitExceeded"
Wyrażenie regularne przekracza limit pamięci.

UpdateRuleOptions

Chrome 87 lub nowszy

Właściwości

  • addRules

    Reguła[] opcjonalna

    Reguły do dodania.

  • removeRuleIds

    liczba[] opcjonalnie

    Identyfikatory reguł do usunięcia. Nieprawidłowe identyfikatory zostaną zignorowane.

UpdateRulesetOptions

Chrome 87 lub nowszy

Właściwości

  • disableRulesetIds

    string[] opcjonalnie

    Zbiór identyfikatorów odpowiadających statycznemu elementowi Ruleset, który powinien zostać wyłączony.

  • enableRulesetIds

    string[] opcjonalnie

    Zbiór identyfikatorów odpowiadających statycznemu elementowi Ruleset, który powinien być włączony.

UpdateStaticRulesOptions

Chrome 111 lub nowszy

Właściwości

  • disableRuleIds

    liczba[] opcjonalnie

    Zestaw identyfikatorów odpowiadających regułom w elemencie Ruleset do wyłączenia.

  • enableRuleIds

    liczba[] opcjonalnie

    Zestaw identyfikatorów odpowiadających regułom w: Ruleset do włączenia.

  • rulesetId

    string,

    Identyfikator odpowiadający statycznemu elementowi Ruleset.

URLTransform

Właściwości

  • fragment

    ciąg znaków opcjonalny

    Nowy fragment żądania. To pole powinno być puste – w tym przypadku istniejący fragment zostanie wyczyszczony lub powinien się zaczynać od znaku „#”.

  • organizator

    ciąg znaków opcjonalny

    Nowy host dla żądania.

  • hasło

    ciąg znaków opcjonalny

    Nowe hasło dla żądania.

  • ścieżka

    ciąg znaków opcjonalny

    Nowa ścieżka żądania. Jeśli ta wartość jest pusta, istniejąca ścieżka zostanie wyczyszczona.

  • port

    ciąg znaków opcjonalny

    Nowy port dla żądania. Jeśli jest pusty, istniejący port jest wyczyszczony.

  • zapytanie

    ciąg znaków opcjonalny

    Nowe zapytanie dla żądania. To pole powinno być puste – w takim przypadku istniejące zapytanie zostanie wyczyszczone lub powinno się zaczynać od „?”.

  • queryTransform

    Opcjonalny QueryTransform

    Dodaj, usuń lub zastąp pary klucz-wartość zapytania.

  • schemat

    ciąg znaków opcjonalny

    Nowy schemat żądania. Dozwolone wartości to „http”, „https”, „ftp” i „chrome-extension”.

  • nazwa użytkownika

    ciąg znaków opcjonalny

    Nowa nazwa użytkownika dla prośby.

Właściwości

DYNAMIC_RULESET_ID

Identyfikator zestawu reguł dynamicznych dodanych przez rozszerzenie.

Wartość

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Przedział czasu, w którym można wykonywać połączenia MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules, określony w minutach. Dodatkowe połączenia zostaną natychmiast zakończone niepowodzeniem i ustawionym jako runtime.lastError. Uwaga: połączenia getMatchedRules związane z gestem użytkownika nie są objęte limitem.

Wartość

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 lub nowszy

Minimalna liczba reguł statycznych, które gwarantują rozszerzenie we wszystkich włączonych statycznych zestawach reguł. Wszystkie reguły powyżej tego limitu będą wliczane do globalnego limitu reguł statycznych.

Wartość

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Liczba wywołań funkcji getMatchedRules w okresie GETMATCHEDRULES_QUOTA_INTERVAL wynosi

Wartość

20

MAX_NUMBER_OF_DYNAMIC_RULES

Maksymalna liczba reguł dynamicznych, które może dodać rozszerzenie.

Wartość

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 lub nowszy

Maksymalna liczba statycznych Rulesets, które rozszerzenie może jednorazowo włączyć.

Wartość

50

MAX_NUMBER_OF_REGEX_RULES

Maksymalna liczba reguł wyrażeń regularnych, które może dodać rozszerzenie. Limit ten jest oceniany oddzielnie dla zbioru reguł dynamicznych i tych określonych w pliku zasobów reguł.

Wartość

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 lub nowszy

Maksymalna liczba reguł ograniczonych do sesji, które może dodać rozszerzenie.

Wartość

5000

MAX_NUMBER_OF_STATIC_RULESETS

Maksymalna liczba statycznych elementów Rulesets, które rozszerzenie może określić w kluczu manifestu "rule_resources".

Wartość

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 lub nowszy

Maksymalna liczba „niebezpiecznych” reguł dynamicznych, które może dodać rozszerzenie.

Wartość

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 lub nowszy

Maksymalna liczba „niebezpiecznych” reguł ograniczonych do sesji, które może dodać rozszerzenie.

Wartość

5000

SESSION_RULESET_ID

Chrome 90 lub nowszy

Identyfikator zestawu reguł dla reguł ograniczonych do sesji dodanych przez rozszerzenie.

Wartość

"_session"

Metody

getAvailableStaticRuleCount()

Obiecujemy Chrome 89 lub nowszy 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

Zwraca liczbę reguł statycznych, które rozszerzenie może włączyć przed osiągnięciem globalnego limitu reguł statycznych.

Parametry

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (count: number) => void

    • liczba

      Liczba

Zwroty

  • Obietnica<number>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są obsługiwane na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica jest realizowana z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getDisabledRuleIds()

Obiecujemy Chrome 111 lub nowszy 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

Zwraca listę reguł statycznych w danym elemencie Ruleset, które są obecnie wyłączone.

Parametry

  • Określa zestaw reguł, których ma dotyczyć zapytanie.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      liczba[]

Zwroty

  • Obietnica<number[]>

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są obsługiwane na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica jest realizowana z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getDynamicRules()

Obiecujemy 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
)

Zwraca bieżący zestaw reguł dynamicznych dla rozszerzenia. Wywołujący mogą opcjonalnie filtrować listę pobranych reguł, określając filter.

Parametry

  • filtr

    Opcjonalne GetRulesFilter

    Chrome 111 lub nowszy

    Obiekt służący do filtrowania listy pobranych reguł.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (rules: Rule[]) => void

Zwroty

  • Obietnica<Reguła[]>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są obsługiwane na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica jest realizowana z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getEnabledRulesets()

Obiecujemy 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

Zwraca identyfikatory bieżącego zestawu włączonych statycznych zestawów reguł.

Parametry

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (rulesetIds: string[]) => void

    • rulesetIds

      ciąg znaków[]

Zwroty

  • Obietnica<ciąg[]>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są obsługiwane na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica jest realizowana z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getMatchedRules()

Obiecujemy 
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
)

Zwraca wszystkie reguły dopasowane do rozszerzenia. Wywołujący mogą opcjonalnie filtrować listę dopasowanych reguł, określając filter. Ta metoda jest dostępna tylko w przypadku rozszerzeń, które mają uprawnienie "declarativeNetRequestFeedback" lub uprawnienie "activeTab" w przypadku elementu tabId określonego w zasadzie filter. Uwaga: reguły niepowiązane z aktywnym dokumentem, który został dopasowany ponad pięć minut temu, nie są zwracane.

Parametry

Zwroty

  • Chrome 91 lub nowszy

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są obsługiwane na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica jest realizowana z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getSessionRules()

Obiecujemy Chrome 90 lub nowszy 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

Zwraca bieżący zestaw reguł ograniczonych do sesji dla rozszerzenia. Wywołujący mogą opcjonalnie filtrować listę pobranych reguł, określając filter.

Parametry

  • filtr

    Opcjonalne GetRulesFilter

    Chrome 111 lub nowszy

    Obiekt służący do filtrowania listy pobranych reguł.

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (rules: Rule[]) => void

Zwroty

  • Obietnica<Reguła[]>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są obsługiwane na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica jest realizowana z tym samym typem, który jest przekazywany do wywołania zwrotnego.

isRegexSupported()

Obiecujemy Chrome 87 lub nowszy 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

Sprawdza, czy dane wyrażenie regularne będzie obsługiwane jako warunek reguły regexFilter.

Parametry

Zwroty

  • Chrome 91 lub nowszy

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są obsługiwane na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica jest realizowana z tym samym typem, który jest przekazywany do wywołania zwrotnego.

setExtensionActionOptions()

Obiecujemy Chrome 88 lub nowszy 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
)

Określa, czy liczba działań na kartach ma być wyświetlana jako tekst plakietki działania rozszerzenia, i umożliwia jej zwiększanie.

Parametry

  • wywołanie zwrotne

    funkcja optional

    Chrome 89 lub nowszy

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Promise<void>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są obsługiwane na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica jest realizowana z tym samym typem, który jest przekazywany do wywołania zwrotnego.

testMatchOutcome()

Obiecujemy Chrome 103 lub nowszy 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

Sprawdza, czy któraś z reguł declarativeNetRequest rozszerzenia pasuje do hipotetycznego żądania. Uwaga: ta opcja jest dostępna tylko w przypadku rozszerzeń bez pakietu, ponieważ jest przeznaczona do użycia wyłącznie podczas ich tworzenia.

Parametry

Zwroty

  • Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są obsługiwane na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica jest realizowana z tym samym typem, który jest przekazywany do wywołania zwrotnego.

updateDynamicRules()

Obiecujemy 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
)

Zmienia bieżący zestaw reguł dynamicznych rozszerzenia. Reguły o identyfikatorach wymienionych w tabeli options.removeRuleIds zostaną najpierw usunięte, a następnie zostaną dodane reguły podane w tabeli options.addRules. Uwagi:

  • Ta aktualizacja odbywa się jako jedna niepodzielna operacja: albo zostaną dodane i usunięte wszystkie określone reguły, albo zwracany jest błąd.
  • Te reguły są zachowywane podczas różnych sesji przeglądarki i aktualizacji rozszerzeń.
  • Reguł statycznych określonych w pakiecie rozszerzeń nie można usunąć za pomocą tej funkcji.
  • MAX_NUMBER_OF_DYNAMIC_RULES to maksymalna liczba reguł dynamicznych, które może dodać rozszerzenie. Liczba niebezpiecznych reguł nie może przekraczać MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

Parametry

  • Chrome 87 lub nowszy
  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Promise<void>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są obsługiwane na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica jest realizowana z tym samym typem, który jest przekazywany do wywołania zwrotnego.

updateEnabledRulesets()

Obiecujemy 
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
)

Aktualizuje zestaw włączonych statycznych zestawów reguł rozszerzenia. Najpierw usuwane są zestawy reguł o identyfikatorach wymienionych w tabeli options.disableRulesetIds, a potem do nich dodawane są zestawy reguł wymienione w tabeli options.enableRulesetIds. Pamiętaj, że zestaw włączonych statycznych zestawów reguł jest zachowywany między sesjami, ale nie pomiędzy aktualizacjami rozszerzeń. Oznacza to, że klucz manifestu rule_resources będzie określać zestaw włączonych statycznych zestawów reguł przy każdej aktualizacji rozszerzenia.

Parametry

  • Chrome 87 lub nowszy
  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Promise<void>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są obsługiwane na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica jest realizowana z tym samym typem, który jest przekazywany do wywołania zwrotnego.

updateSessionRules()

Obiecujemy Chrome 90 lub nowszy 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
)

Modyfikuje bieżący zestaw reguł ograniczonych do sesji dla rozszerzenia. Reguły o identyfikatorach wymienionych w tabeli options.removeRuleIds zostaną najpierw usunięte, a następnie zostaną dodane reguły podane w tabeli options.addRules. Uwagi:

  • Ta aktualizacja odbywa się jako jedna niepodzielna operacja: albo zostaną dodane i usunięte wszystkie określone reguły, albo zwracany jest błąd.
  • Reguły te nie są zachowywane między sesjami i są zapisywane w pamięci.
  • MAX_NUMBER_OF_SESSION_RULES to maksymalna liczba reguł sesji, które może dodać rozszerzenie.

Parametry

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Promise<void>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są obsługiwane na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica jest realizowana z tym samym typem, który jest przekazywany do wywołania zwrotnego.

updateStaticRules()

Obiecujemy Chrome 111 lub nowszy 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

Wyłącza i włącza poszczególne reguły statyczne w Ruleset. Zmiany w regułach należących do wyłączonej grupy Ruleset zaczną obowiązywać po jej następnym włączeniu.

Parametry

Zwroty

  • Promise<void>

    Obietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są obsługiwane na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica jest realizowana z tym samym typem, który jest przekazywany do wywołania zwrotnego.

Wydarzenia

onRuleMatchedDebug

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

Uruchamiane, gdy reguła jest zgodna z żądaniem. Ta opcja jest dostępna tylko w przypadku rozszerzeń bez pakietu z uprawnieniami "declarativeNetRequestFeedback", ponieważ jest przeznaczone wyłącznie do debugowania.

Parametry