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

declarativeNetRequestFeedback
host_permissions

Dostępność

Chrome 84 i nowsze .

Plik manifestu

Oprócz uprawnień opisanych powyżej niektóre typy zestawów reguł, a w szczególności 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.

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 reguły, 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. Poniżej przedstawiamy 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.

Ograniczenia reguł

Wczytywanie i ocenianie reguł w przeglądarce wiąże się z dużą wydajnością, więc podczas korzystania z tego interfejsu 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. Rozszerzenie może zawierać maksymalnie 50 statycznych reguł w kluczu manifestu "rule_resources", ale jednocześnie można włączyć tylko 10 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 tys. 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 dynamiczne i reguły sesji

Limity stosowane w regułach dynamicznych i regułach dotyczących sesji są prostsze niż w regułach statycznych. Łączna liczba w obu przypadkach nie może przekraczać 5000. Jest to tzw. MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES.

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

Wyrażenia regularne mogą być używane w przypadku wszystkich typów reguł. jednak łączna liczba reguł 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 complext 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 obejmować odpowiedzi przekazywanych przez moduł obsługi onfetch skryptu service worker. declarativeNetRequest nie wpłynie na odpowiedzi generowane przez skrypt service worker oraz pobrane z 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.

„Priorytet”, klawisz

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ż są przeznaczone dla dłuższych adresów URL.
Nawigacja do strony https://google.com/1234
Ze względu na dłuższy adres URL reguła z identyfikatorem 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 kod służy do przekierowania do subdomeny example.com za pomocą klucza "transform". Wykorzystuje kotwicę nazwy domeny („||”) do przechwytywania żądań z dowolnym schematem z example.com. Klucz "scheme" w zasadzie "transform" określa, że przekierowania do subdomeny zawsze używają przedrostka „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ę, że w kluczu "regexFilter" zmienia się znaczenie kropek i że grupa przechwytywania wybiera „abc” czy „def”. Klucz "regexSubstitution" określa pierwsze zwrócone dopasowanie wyrażenia regularnego z użyciem „\1”. W tym przypadku: „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łówki

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 i nowsze .

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 w wersji 89 lub nowszej .

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

GetDisabledRuleIdsOptions

Chrome w wersji 111 lub nowszej .

Właściwości

  • rulesetId

    ciąg znaków

    Identyfikator odpowiadający statycznemu elementowi Ruleset.

GetRulesFilter

Chrome w wersji 111 lub nowszej .

Właściwości

  • ruleIds

    liczba[] opcjonalnie

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

HeaderInfo

Chrome w wersji 128 lub nowszej .

Właściwości

  • excludedValues

    string[] opcjonalnie

    Jeśli ten warunek zostanie określony, ten warunek nie zostanie spełniony, jeśli nagłówek istnieje, ale jego wartość zawiera co najmniej jeden element na tej liście. Wykorzystuje tę samą składnię wzorca dopasowania co values.

  • nagłówek

    ciąg znaków

    Nazwa nagłówka. Ten warunek pasuje do nazwy tylko wtedy, gdy nie określono ani values, ani excludedValues.

  • wartości

    string[] opcjonalnie

    Jeśli zostanie określony, ten warunek zostanie dopasowany, jeśli wartość nagłówka pasuje do co najmniej jednego wzorca na tej liście. Obsługuje dopasowanie wartości nagłówka bez rozróżniania wielkości liter oraz następujące konstrukcje:

    '*' : odpowiada dowolnej liczbie znaków.

    '?' : dopasowuje zero lub jeden znak.

    „*” i „?” można zamienić na ukośnik lewy, np. „\*” i „\?”,

HeaderOperation

Chrome 86 i nowsze .

Opisuje możliwe operacje polecenia „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 i nowsze .

Właściwości

  • isSupported

    wartość logiczna

  • 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

    ciąg znaków

    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

  • żądanie

    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 i nowsze .

Właściwości

  • nagłówek

    ciąg znaków

    Nazwa nagłówka do zmodyfikowania.

  • operacja

    HeaderOperation

    Operacja do wykonania na nagłówku.

  • wartość

    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

    ciąg znaków

  • replaceOnly

    Wartość logiczna opcjonalna

    Chrome w wersji 94 lub nowszej .

    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.

  • wartość

    ciąg znaków

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 i nowsze .

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

    ciąg znaków

    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. wartość dodatnia wskazuje identyfikator ramki podrzędnej, w której zachodzi żądanie. 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, ciąg znaków „null” .

  • method

    ciąg znaków

    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

    ciąg znaków

    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.

  • Typ zasobu żądania.

  • URL

    ciąg znaków

    Adres URL żądania.

RequestMethod

Chrome w wersji 91 lub nowszej .

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

Typ wyliczeniowy

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"inna"

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"

"inna"

Rule

Właściwości

  • działanie

    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 i nowsze .

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

  • responseHeaders

    ModifyHeaderInfo[] opcjonalny

    Chrome 86 i nowsze .

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

  • 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 należącym do użytkownika czy od firmy zewnętrznej. Jeśli go pominiesz, wszystkie żądania zostaną zaakceptowane.

  • domeny

    string[] opcjonalnie

    Wycofane od Chrome 101

    Zamiast tego użyj initiatorDomains

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

  • excludedDomains

    string[] opcjonalnie

    Wycofane 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 i nowsze wersje .

    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:

    • Subdomen, takich jak „a.example.com” są 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 i nowsze wersje .

    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:

    • Subdomen, takich jak „a.example.com” są 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 w wersji 91 lub nowszej .

    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 określono żadnego z nich, wszystkie typy zasobów oprócz „main_frame” są zablokowane.

  • excludedResponseHeaders

    HeaderInfo[] opcjonalny

    Chrome w wersji 128 lub nowszej .

    Reguła nie jest zgodna, jeśli żądanie spełnia dowolny warunek nagłówka odpowiedzi z tej listy (jeśli został określony). Jeśli określono zarówno excludedResponseHeaders, jak i responseHeaders, właściwość excludedResponseHeaders ma pierwszeństwo.

  • excludedTabIds

    liczba[] opcjonalnie

    Chrome w wersji 92 lub nowszej .

    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 i nowsze wersje .

    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:

    • Subdomen, takich jak „a.example.com” są 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 porównywany z adresem 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 i nowsze wersje .

    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:

    • Subdomen, takich jak „a.example.com” są 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 w wersji 91 lub nowszej .

    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.

  • responseHeaders

    HeaderInfo[] opcjonalny

    Chrome 128 i nowsze wersje .

    Reguła jest stosowana, jeśli żądanie pasuje do dowolnego warunku nagłówka odpowiedzi z tej listy (jeśli został określony).

  • tabIds

    liczba[] opcjonalnie

    Chrome w wersji 92 lub nowszej .

    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 porównywany z adresem 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

    wartość logiczna

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

  • id

    ciąg znaków

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

  • ścieżka

    ciąg znaków

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

RulesMatchedDetails

Właściwości

TabActionCountUpdate

Chrome w wersji 89 lub nowszej .

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 i nowsze wersje .

Właściwości

  • matchedRules

    MatchedRule[]

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

TestMatchRequestDetails

Chrome 103 i nowsze wersje .

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 ignorowane w przypadku żądań innych niż HTTP.

  • responseHeaders

    obiekt opcjonalny

    Oczekujący

    Nagłówki podawane w hipotetycznej odpowiedzi, jeśli przed wysłaniem żądanie nie zostanie zablokowane ani przekierowane. Reprezentowany jako obiekt mapujący nazwę nagłówka na listę wartości ciągu znaków. Jeśli nie podasz żadnej wartości, hipotetyczna odpowiedź zwróci puste nagłówki odpowiedzi, które mogą pasować do reguł pasujących do nieistniejących nagłówków. Na przykład: {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • 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ą.

  • Typ zasobu hipotetycznego żądania.

  • URL

    ciąg znaków

    Adres URL hipotetycznego żądania.

UnsupportedRegexReason

Chrome 87 i nowsze .

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 i nowsze .

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 i nowsze .

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 w wersji 111 lub nowszej .

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

    ciąg znaków

    Identyfikator odpowiadający statycznemu elementowi Ruleset.

URLTransform

Właściwości

  • fragment

    ciąg znaków opcjonalny

    Nowy fragment żądania. Powinien być pusty – w takim przypadku istniejący fragment zostanie wyczyszczony. lub powinien się zaczynać od znaku „#”.

  • host

    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 powinien zaczynać się 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 w wersji 89 lub nowszej .

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 w wersji 94 lub nowszej .

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 w wersji 120 lub nowszej .

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 w wersji 120 lub nowszej .

Maksymalna liczba niebezpiecznych treści reguł dynamicznych, które może dodawać rozszerzenie.

Wartość

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome w wersji 120 lub nowszej .

Maksymalna liczba niebezpiecznych treści reguł ograniczonych do sesji, które może dodawać rozszerzenie.

Wartość

5000

SESSION_RULESET_ID

Chrome w wersji 90 lub nowszej .

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

Wartość

"_session"

Metody

getAvailableStaticRuleCount()

Obietnica Chrome w wersji 89 lub nowszej 
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

  • Promise<number>

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

getDisabledRuleIds()

Obietnica Chrome w wersji 111 i nowszych 
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 tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

getDynamicRules()

Obietnica .
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 w wersji 111 lub nowszej .

    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 w wersji 91 lub nowszej .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

getEnabledRulesets()

Obietnica .
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

  • Promise&lt;string[]&gt;

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

getMatchedRules()

Obietnica .
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

  • Promise&lt;RulesMatchedDetails&gt;

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

getSessionRules()

Obietnica Chrome w wersji 90 lub nowszej 
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 w wersji 111 lub nowszej .

    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 w wersji 91 lub nowszej .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

isRegexSupported()

Obietnica Chrome w wersji 87 lub nowszej 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

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

Parametry

Zwroty

  • Promise&lt;IsRegexSupportedResult&gt;

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

setExtensionActionOptions()

Obietnica Chrome w wersji 88 lub nowszej 
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 w wersji 89 lub nowszej .

    Parametr callback wygląda tak: 

    () => void
    .

Zwroty

  • Obietnica<void>

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

testMatchOutcome()

Obietnica Chrome w wersji 103 lub nowszej 
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 tworzenia rozszerzeń.

Parametry

Zwroty

  • Promise&lt;TestMatchOutcomeResult&gt;

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

updateDynamicRules()

Obietnica .
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 i nowsze .
  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void
    .

Zwroty

  • Obietnica<void>

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

updateEnabledRulesets()

Obietnica .
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 i nowsze .
  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void
    .

Zwroty

  • Obietnica<void>

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

updateSessionRules()

Obietnica Chrome w wersji 90 lub nowszej 
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

  • Obietnica<void>

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

updateStaticRules()

Obietnica Chrome w wersji 111 i nowszych 
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

  • Obietnica<void>

    Obietnice są obsługiwane tylko na platformie Manifest V3 i nowszych, inne platformy muszą używać wywołań zwrotnych.

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