chrome.declarativeNetRequest

Opis

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

Uprawnienia

declarativeNetRequest
declarativeNetRequestWithHostAccess

Uprawnienia „declarativeNetRequest” i „declarativeNetRequestWithHostAccess” dają te same możliwości. Różnice między nimi polegają na tym, kiedy uprawnienia są wymagane lub przyznane.

"declarativeNetRequest"
Wywołuje 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ąć konieczności prośby o pełny dostęp do hostów.
"declarativeNetRequestFeedback"
Włącza funkcje debugowania w przypadku rozszerzeń bez pakietu, w szczególności getMatchedRules() i onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
Ostrzeżenie o uprawnieniach nie jest wyświetlane w czasie instalacji, ale zanim wykonasz jakiekolwiek działanie na hoście, musisz poprosić o uprawnienia hosta. Jest to przydatne, gdy chcesz użyć deklaratywnej reguły żądania netto w rozszerzeniu, które ma już uprawnienia hosta bez generowania dodatkowych ostrzeżeń.

Dostępność

Chrome 84 i nowsze wersje

Plik manifestu

Oprócz opisanych powyżej uprawnień niektóre typy zestawów reguł (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 to tablica zawierająca słowniki typu Ruleset, jak pokazano poniżej. (Zwróć uwagę, że nazwa „Zestaw reguł” nie pojawia się w pliku JSON pliku manifestu, ponieważ jest to jedynie tablica). Statyczne zestawy reguł zostały objaśnione 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 zastosowanie

Aby użyć tego interfejsu API, określ co najmniej 1 zestaw reguł. Zestaw reguł zawiera tablicę reguł. Pojedyncza reguła ma jeden z tych parametrów:

  • Zablokuj żądanie sieciowe.
  • Uaktualnij schemat (http do https).
  • Aby zapobiec blokowaniu żądania, neguj pasujące reguły zablokowane.
  • Przekieruj żądanie sieciowe.
  • Zmodyfikuj nagłówki żądania lub odpowiedzi.

Istnieją 3 typy zestawów reguł, którymi można zarządzać w nieco inny sposób.

Dynamiczna
Zostaną zachowane przez wszystkie sesje przeglądarki i uaktualnienia rozszerzeń, a zarządzanie nimi odbywa się za pomocą JavaScriptu, gdy używane jest rozszerzenie.
Sesja
Zostaną usunięte, gdy przeglądarka wyłącza się i zainstalowana jest nowa wersja rozszerzenia. Reguły sesji są zarządzane za pomocą JavaScriptu, 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ą wymienione w pliku manifestu.

W kilku następnych sekcjach szczegółowo opisujemy typy zestawów reguł.

Dynamiczne i ograniczone do sesji zestawy reguł

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

  • Reguły dynamiczne pozostają aktywne niezależnie od sesji przeglądarki i uaktualnień 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ł istnieje tylko po jednym. Rozszerzenie może dynamicznie dodawać i usuwać reguły, wywołując updateDynamicRules() i updateSessionRules(), o ile limity reguł nie zostaną przekroczone. Informacje o limitach reguł znajdziesz w artykule Ograniczenia reguł. Przykład znajdziesz w sekcji przykładowy kod.

Statyczne zestawy reguł

W odróżnieniu od 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, które są wskazane rozszerzeniu za pomocą kluczy "declarative_net_request" i "rule_resources" jak opisano powyżej, a także co najmniej 1 słownika Ruleset. Słownik Ruleset zawiera ścieżkę do pliku reguły, identyfikator zawartego w pliku reguł zestawu reguł oraz informację o tym, czy zestaw reguł jest włączony czy wyłączony. Dwa ostatnie 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ł, załaduj rozszerzenie bez pakietu. 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 rozszerzeniach w pakiecie są ignorowane.

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

Zarówno pojedyncze reguły statyczne, jak i całe zestawy reguł statycznych mogą być włączone lub wyłączone w czasie działania.

Zestaw włączonych reguł statycznych i zestawów reguł jest zachowywany pomiędzy sesjami przeglądarki. Żadna z nich nie jest zachowywana po aktualizacji rozszerzeń, co oznacza, że po aktualizacji dostępne są tylko reguły pozostawione w plikach reguł.

Ze względu na wydajność istnieją też ograniczenia dotyczące liczby reguł i zestawów reguł, które można włączyć jednocześnie. Zadzwoń pod numer getAvailableStaticRuleCount(), aby sprawdzić liczbę dodatkowych reguł, które można włączyć. Informacje o limitach reguł znajdziesz w artykule Ograniczenia reguł.

Aby włączyć lub wyłączyć statyczne reguły, wywołaj updateStaticRules(). Ta metoda pobiera obiekt UpdateStaticRulesOptions zawierający tablice identyfikatorów reguł do włączenia lub wyłączenia. Identyfikatory są definiowane za pomocą klucza "id" w słowniku Ruleset.

Aby włączyć lub wyłączyć statyczne rulesets, wywołaj updateEnabledRulesets(). Ta metoda pobiera obiekt UpdateRulesetOptions zawierający tablice identyfikatorów zestawów reguł do włączenia lub wyłączenia. Identyfikatory są definiowane za pomocą klucza "id" w słowniku Ruleset.

Tworzenie reguł

Niezależnie od typu reguła rozpoczyna się od 4 pól, tak jak to pokazano poniżej. Klawisze "id" i "priority" pobierają liczby, ale "action" i "condition" mogą zapewniać kilka warunków blokowania i przekierowania. Poniższa reguła blokuje wszystkie żądania skryptu pochodzące z adresu "foo.com" do dowolnego adresu URL, którego podłańcuch jest "abc".

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

Pasujące znaki urlFilter

Klucz "condition" reguły umożliwia użycie klucza "urlFilter" do wykonywania działań na adresach URL w określonej domenie. Wzorce możesz tworzyć za pomocą tokenów dopasowywania do 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

Określanie priorytetów reguł

Reguły są wywoływane przez żądania wysyłane ze stron internetowych. Jeśli do danego żądania pasuje wiele reguł, reguły muszą mieć priorytet. Z tej sekcji dowiesz się, jak są ustalane priorytety. Określanie priorytetów odbywa się dwuetapowo.

  1. Priorytety są określane w przypadku reguł w rozszerzeniu.
  2. Jeśli do żądania można zastosować regułę więcej niż jednego rozszerzenia, priorytet jest określany dla wszystkich rozszerzeń, które pasują do konkretnego żądania.

Takie dopasowanie: reguły, które nadają priorytet konkretnemu rozszerzeniu, będą miały wyższy priorytet niż reguły innych rozszerzeń.

Określanie priorytetów reguł w ramach rozszerzenia

W ramach pojedynczego rozszerzenia ustalanie priorytetów jest realizowane w ten sposób:

  1. Zwracana jest reguła o najwyższym priorytecie zdefiniowanym przez dewelopera (czyli pole "priority").

  2. Jeśli istnieje więcej niż 1 reguła o najwyższym priorytecie określonym przez programistę, reguły mają priorytet w polu "action" w takiej kolejności:

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

  3. Jeśli typem działania nie jest block ani redirect, sprawdzane są wszystkie pasujące reguły modifyHeaders. Pamiętaj, że jeśli istnieją reguły, których priorytet zdefiniowany przez dewelopera jest niższy niż priorytet określony w allow i allowAllRequests, zostaną one zignorowane.

  4. Jeśli wiele reguł modyfikuje ten sam nagłówek, zmiana zależy od zdefiniowanego przez dewelopera pola "priority" i określonych operacji.

    • Jeśli reguła dołącza do nagłówka, reguły o niższym priorytecie mogą dołączać tylko do tego nagłówka. Operacje ustawiania i usuwania są niedozwolone.
    • Jeśli reguła ustawia nagłówek, wtedy reguły o niższym priorytecie mogą dołączać tylko do tego nagłówka. Nie są dozwolone żadne inne modyfikacje.
    • Jeśli reguła usuwa nagłówek, reguły o niższym priorytecie nie mogą go już modyfikować.

Określanie priorytetów reguł dla rozszerzeń

Jeśli tylko jedno rozszerzenie ma regułę, która pasuje do żądania, jest ona stosowana. Jeśli jednak do żądania pasuje więcej niż jedno rozszerzenie, używany jest następujący proces:

  1. Priorytet reguł jest ustalany w polu "action" w takiej kolejności:

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

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

Ograniczenia reguł

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

Reguły statyczne

Reguły statyczne to reguły określone w plikach reguł zadeklarowanych w pliku manifestu. Rozszerzenie może określić w kluczu manifestu "rule_resources" maksymalnie 100 statycznych rulesets, ale jednocześnie można włączyć tylko 50 z tych zestawów reguł. Ten drugi rodzaj danych nosi nazwę MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Łącznie te zestawy reguł mają gwarancję co najmniej 30 tys. reguł. Nazywa się GUARANTEED_MINIMUM_STATIC_RULES.

Liczba dostępnych reguł zależy od tego, ile reguł włączonych przez wszystkie rozszerzenia zainstalowane w przeglądarce użytkownika. Możesz go sprawdzić w czasie działania, dzwoniąc pod numer getAvailableStaticRuleCount(). Przykład znajdziesz w sekcji przykładowy kod.

Reguły sesji

Rozszerzenie może mieć maksymalnie 5000 reguł sesji. Jest on widoczny jako MAX_NUMBER_OF_SESSION_RULES.

Przed wersją Chrome 120 łącznie obowiązywał limit 5 tys. reguł dynamicznych i reguł dotyczących sesji.

Reguły dynamiczne

Rozszerzenie może mieć co najmniej 5000 reguł dynamicznych. Jest on widoczny jako MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

Począwszy od wersji Chrome 121 dostępny jest większy limit 30 tys. reguł dla bezpiecznych reguł dynamicznych wyświetlanych jako MAX_NUMBER_OF_DYNAMIC_RULES. Bezpieczne reguły to reguły z działaniem block, allow, allowAllRequests lub upgradeScheme. Do tego limitu wliczają się też wszystkie niebezpieczne reguły dodane w ramach limitu 5000 osób.

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

Reguły używające wyrażeń regularnych

Wszystkie typy reguł mogą korzystać z wyrażeń regularnych, jednak łączna liczba reguł każdego typu nie może przekroczyć 1000. Jest to tzw. MAX_NUMBER_OF_REGEX_RULES.

Poza tym każda reguła musi mieć mniej niż 2 KB po skompilowaniu. Odpowiada to 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

DeklaratativeNetRequest ma zastosowanie tylko do żądań docierających do stosu sieciowego. Obejmuje to odpowiedzi z pamięci podręcznej HTTP, ale mogą nie zawierać odpowiedzi, które przechodzą przez moduł obsługi onfetch skryptu service worker. deklarativeNetRequest nie ma wpływu na odpowiedzi generowane przez mechanizm Service Worker lub pobierane z CacheStorage, ale ma wpływ na wywołania fetch() wykonywane w skrypcie service worker.

Zasoby dostępne w internecie

Reguła deklarativeNetRequest 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 podany zasób dostępny z internetu należy do rozszerzenia przekierowującego. Aby zadeklarować zasoby na potrzeby żądania deklarativeNetRequest, użyj tablicy "web_accessible_resources" pliku manifestu.

Przykłady

Przykłady kodu

Aktualizowanie reguł dynamicznych

Poniższy przykład pokazuje, jak wywołać updateDynamicRules(). Procedura 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
});

Aktualizowanie statycznych zestawów 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 statycznych zestawów reguł. Należy to zrobić, gdy liczba potrzebnych reguł statycznych przekracza dozwoloną liczbę. Aby te zestawy reguł działały, należy zainstalować niektóre zestawy reguł (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. Warto je otworzyć w osobnym oknie z regułami ustalania priorytetów.

Klawisz „Priority”

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

Aby określić priorytet poszczególnych adresów URL, przeanalizuj następujące klucze: "priority" (zdefiniowane przez programistę), "action" i "urlFilter". Te przykłady dotyczą przykładowego pliku reguł pokazanego pod nimi.

Wejdź na https://google.com
Ten adres URL obejmuje 2 reguły: reguły o identyfikatorach 1 i 4. Obowiązuje reguła o identyfikatorze 1, 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.
Wejdź na https://google.com/1234
Z powodu dłuższego adresu URL reguła o identyfikatorze 2 będzie teraz pasować do reguł o identyfikatorach 1 i 4. Obowiązuje reguła o identyfikatorze 2, bo element "allow" ma wyższy priorytet niż zasady "block" i "redirect".
Wejdź na https://google.com/12345
Wszystkie 4 reguły pasują do tego adresu URL. Obowiązuje reguła o identyfikatorze 3, ponieważ jej priorytet zdefiniowany przez programistę ma najwyższy priorytet z grupy.
[
  {
    "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

Poniższy przykład wymaga uprawnień hosta dla użytkownika *://*.example.com/*.

Z przykładu poniżej dowiesz się, jak przekierować żądanie z example.com na stronę wewnątrz rozszerzenia. Ścieżka rozszerzenia /a.jpg prowadzi do chrome-extension://EXTENSION_ID/a.jpg, gdzie EXTENSION_ID to identyfikator rozszerzenia. Aby to zadział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"]
  }
}

W poniższym przykładzie użyto klucza "transform" do przekierowania do subdomeny example.com. Wykorzystuje on kotwicę nazwy domeny („||”) do przechwytywania żądań z dowolnym schematem z example.com. Klucz "scheme" w elemencie "transform" określa, że przekierowania do subdomeny zawsze będą używać „https”.

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

Poniższy przykład pokazuje przekierowanie z https://www.abc.xyz.com/path do https://abc.xyz.com/path za pomocą wyrażeń regularnych. Zwróć uwagę, jak w kluczu "regexFilter" zmienia się znaczenie kropek, a grupa przechwytywania wybiera „abc” lub „def”. Klucz "regexSubstitution" określa pierwsze zwrócone dopasowanie wyrażenia regularnego z użyciem parametru „\1”. W tym przypadku element „abc” jest przechwytywany z przekierowującego adresu URL i umieszczany w jego podstawie.

{
  "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,

Z przykładu poniżej widać wszystkie pliki cookie zarówno z ramki głównej, jak i z ramek podrzędnych.

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

Typy

DomainType

Określa, czy żądanie pochodzi od Ciebie, czy od strony trzeciej w ramach ramki, z której pochodzi. Żądanie jest uznawane za własne, jeśli ma tę samą domenę (eTLD + 1) co ramka, z której pochodzi żądanie.

Typ wyliczeniowy

„Własne”
Żądanie sieciowe jest własne w ramce, z której pochodzi.

"thirdParty"
Żądanie sieci pochodzi od firmy zewnętrznej do ramki, z której pochodzi.

ExtensionActionOptions

Chrome 88 i nowsze wersje

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 zachowywane we wszystkich sesjach.

  • tabUpdate

    TabActionCountUpdate opcjonalnie

    Chrome 89 i nowsze wersje

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

GetDisabledRuleIdsOptions

Chrome 111 i nowsze wersje

Właściwości

  • rulesetId

    string,

    Identyfikator odpowiadający statycznemu elementowi Ruleset.

GetRulesFilter

Chrome 111 i nowsze wersje

Właściwości

  • ruleIds

    number[] opcjonalny

    Jeśli podasz wartość, uwzględnione zostaną tylko reguły o pasujących identyfikatorach.

HeaderOperation

Chrome 86 i nowsze wersje

Opisuje możliwe operacje na regule „modifyHeaders”.

Typ wyliczeniowy

"append"
Dodaje nowy wpis dla określonego nagłówka. Ta operacja nie jest obsługiwana w nagłówkach żądań.

"set"
Ustawia nową wartość dla określonego nagłówka, usuwając wszystkie istniejące nagłówki o tej samej nazwie.

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

IsRegexSupportedResult

Chrome 87 i nowsze wersje

Właściwości

  • isSupported

    boolean

  • powód

    UnsupportedRegexReason opcjonalnie

    Określa przyczynę, dla której wyrażenie regularne nie jest obsługiwane. Podana tylko wtedy, gdy isSupported ma wartość false (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, która pochodzi ze zbioru reguł dynamicznych, wartość ta 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 karta jest nadal aktywna. Inne: -1.

  • timeStamp

    Liczba

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

MatchedRuleInfoDebug

Właściwości

MatchedRulesFilter

Właściwości

  • minTimeStamp

    Liczba opcjonalnie

    Jeśli jest określony, dopasowuje reguły tylko po podanej sygnaturze czasowej.

  • tabId

    Liczba opcjonalnie

    Jeśli określono, dopasowuje reguły tylko dla danej karty. Dopasowuje reguły niepowiązane z żadną aktywną kartą, jeśli ma wartość -1.

ModifyHeaderInfo

Chrome 86 i nowsze wersje

Właściwości

  • nagłówek

    string,

    Nazwa nagłówka do modyfikacji.

  • operacja

    HeaderOperation

    Operacja do wykonania na nagłówku.

  • value

    ciąg znaków opcjonalny

    Nowa wartość nagłówka. Należy określić dla operacji append i set.

QueryKeyValue

Właściwości

  • klucz

    string,

  • replaceOnly

    wartość logiczna opcjonalna

    Chrome 94 i nowsze wersje

    Jeśli ma wartość true (prawda), klucz zapytania jest zastępowany tylko wtedy, gdy już istnieje. W przeciwnym razie zostanie też dodany klucz, 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 do dodania lub zastąpienia.

  • removeParams

    string[] opcjonalny

    Lista kluczy zapytania do usunięcia.

Redirect

Właściwości

  • extensionPath

    ciąg znaków opcjonalny

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

  • regexSubstitution

    ciąg znaków opcjonalny

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

  • przekształcenie

    URLTransform (opcjonalnie)

    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 wersje

Właściwości

  • isCaseSensitive

    wartość logiczna opcjonalna

    Określa, czy w podanym elemencie regex wielkość liter ma znaczenie. Wartość domyślna to true (prawda).

  • wyrażenie regularne

    string,

    Wyrażenie regularne do sprawdzenia.

  • requireCapturing

    wartość logiczna opcjonalna

    Określa, czy określony obiekt 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 i nowsze wersje

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

  • documentLifecycle

    DocumentLifecycle opcjonalnie

    Chrome 106 i nowsze wersje

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

  • frameId

    Liczba

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

  • frameType

    Opcjonalne FrameType.

    Chrome 106 i nowsze wersje

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

  • inicjator

    ciąg znaków opcjonalny

    Źródło, z którego zainicjowano żądanie. Nie zmienia się w wyniku przekierowania. Jeśli źródło jest nieprzezroczyste, zostanie użyty ciąg „null”.

  • method

    string,

    Standardowa metoda HTTP.

  • parentDocumentId

    ciąg znaków opcjonalny

    Chrome 106 i nowsze wersje

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

  • parentFrameId

    Liczba

    Identyfikator ramki, która opakowuje ramkę, która wysłała żądanie. Jeśli nie istnieje ramka nadrzędna, ustaw wartość -1.

  • requestId

    string,

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

  • tabId

    Liczba

    Identyfikator karty, na której występuje żą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 i nowsze wersje

Opisuje metodę żądania HTTP w żądaniu sieciowym.

Typ wyliczeniowy

"get"

"head"

"post"

"put"

ResourceType

Opisuje on typ zasobu żądania sieciowego.

Typ wyliczeniowy

"main_frame"

"sub_frame"

"script"

"object"

"xmlhttprequest"

"csp_report"

"media"

"websocket"

Rule

Właściwości

  • działanie

    RuleAction

    Działanie, które ma zostać wykonane w przypadku zgodności z regułą.

  • Warunek, pod którym ta reguła jest wyzwalana.

  • id

    Liczba

    Unikalny identyfikator reguły. Obowiązkowa, powinna wynosić >= 1.

  • kampanii

    Liczba opcjonalnie

    Priorytet reguły. Domyślna wartość to 1. Gdy należy podać wartość, powinna być >= 1.

RuleAction

Właściwości

  • Przekieruj

    Przekierowanie opcjonalnie

    Opisuje sposób wykonywania przekierowania. Dotyczy tylko reguł przekierowania.

  • requestHeaders

    ModifyHeaderInfo[] opcjonalny

    Chrome 86 i nowsze wersje

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

  • responseHeaders

    ModifyHeaderInfo[] opcjonalny

    Chrome 86 i nowsze wersje

    Nagłówki odpowiedzi do zmodyfikowania w związku z żądaniem. Tej opcji można użyć tylko wtedy, gdy element RuleActionType ma wartość „modifyHeaders”.

  • Niestandardowy typ treści

    RuleActionType

    Typ działania do wykonania.

RuleActionType

Opisuje działanie, które ma zostać wykonane, gdy jest spełniony dany warunek reguły.

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 do niego reguła zezwalająca.

"upgradeScheme"
Zmień schemat adresu URL żądania sieciowego na https, jeśli żądanie to http lub ftp.

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

"allowAllRequests"
Akceptuj 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łasne czy zewnętrzne w domenie, z której pochodzi. Jeśli ten argument zostanie pominięty, wszystkie żądania zostaną zaakceptowane.

  • domeny

    string[] opcjonalny

    Wycofane od Chrome 101

    Zamiast niej użyj initiatorDomains.

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

  • excludedDomains

    string[] opcjonalny

    Wycofane od Chrome 101

    Zamiast niej użyj excludedInitiatorDomains.

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

  • excludedInitiatorDomains

    string[] opcjonalny

    Chrome 101 i nowsze wersje

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

    Uwagi:

    • Subdomeny takie jak „a.example.com” również są dozwolone.
    • Wpisy mogą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania punycode.
    • Adres ten jest zgodny z adresem URL inicjatora żądania, a nie z adresem URL tego żądania.
    • Subdomeny wymienionych domen są również wykluczone.
  • excludedRequestDomains

    string[] opcjonalny

    Chrome 101 i nowsze wersje

    Reguła nie będzie dopasowywana do żądań sieciowych, gdy domeny będą pasować do jednej z nich na liście excludedRequestDomains. Jeśli lista jest pusta lub pominięta, żadne domeny nie są wykluczone. Ma pierwszeństwo przed requestDomains.

    Uwagi:

    • Subdomeny takie jak „a.example.com” również są dozwolone.
    • Wpisy mogą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania punycode.
    • Subdomeny wymienionych domen są również wykluczone.
  • excludedRequestMethods

    RequestMethod[] opcjonalny

    Chrome 91 i nowsze wersje

    Lista metod żądań, których reguła nie będzie pasować. Należy określić tylko jedną z tych wartości: requestMethods i excludedRequestMethods. Jeśli żadna z tych metod nie zostanie określona, dopasowywane są wszystkie metody żądań.

  • excludedResourceTypes

    ResourceType[] opcjonalny

    Lista typów zasobów, do których reguła nie będzie pasować. Należy określić tylko jedną z tych wartości: resourceTypes i excludedResourceTypes. Jeśli nie podasz żadnej z nich, wszystkie typy zasobów oprócz „main_frame” będą blokowane.

  • excludedTabIds

    number[] opcjonalny

    Chrome 92 i nowsze wersje

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

  • initiatorDomains

    string[] opcjonalny

    Chrome 101 i nowsze wersje

    Reguła będzie dopasowywać tylko żądania sieciowe pochodzące z listy initiatorDomains. W przypadku pominięcia listy reguła będzie stosowana do żądań ze wszystkich domen. Pusta lista jest niedozwolona.

    Uwagi:

    • Subdomeny takie jak „a.example.com” również są dozwolone.
    • Wpisy mogą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania punycode.
    • Adres ten jest zgodny z adresem URL inicjatora żądania, a nie z adresem URL tego żądania.
    • Dopasowywane są również subdomeny wymienionych domen.
  • isUrlFilterCaseSensitive

    wartość logiczna opcjonalna

    Określa, czy w polu urlFilter czy regexFilter (w zależności od tego, co jest określone) rozróżniana jest wielkość liter. Wartość domyślna to false (fałsz).

  • regexFilter

    ciąg znaków opcjonalny

    Wyrażenie regularne dopasowane do adresu URL żądania sieciowego. Jest on zgodny ze składnią RE2.

    Uwaga: można określić tylko jedną wartość urlFilter lub regexFilter.

    Uwaga: pole regexFilter może zawierać tylko znaki ASCII. Jest on dopasowywany do adresu URL, w którym host jest kodowany w formacie punycode (w przypadku domen międzynarodowych), a wszelkie inne znaki spoza zestawu ASCII są zakodowane w formacie UTF-8.

  • requestDomains

    string[] opcjonalny

    Chrome 101 i nowsze wersje

    Reguła będzie dopasowywać żądania sieciowe tylko wtedy, gdy domena jest zgodna z domeną z listy requestDomains. W przypadku pominięcia listy reguła będzie stosowana do żądań ze wszystkich domen. Pusta lista jest niedozwolona.

    Uwagi:

    • Subdomeny takie jak „a.example.com” również są dozwolone.
    • Wpisy mogą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania punycode.
    • Dopasowywane są również subdomeny wymienionych domen.
  • requestMethods

    RequestMethod[] opcjonalny

    Chrome 91 i nowsze wersje

    Lista metod żądań HTTP, które może pasować do reguły. Pusta lista jest niedozwolona.

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

  • resourceTypes

    ResourceType[] opcjonalny

    Lista typów zasobów, które mogą być dopasowywane przez regułę. Pusta lista jest niedozwolona.

    Uwaga: to pole należy określić w przypadku reguł allowAllRequests i może zawierać tylko typy zasobów sub_frame oraz main_frame.

  • tabIds

    number[] opcjonalny

    Chrome 92 i nowsze wersje

    Lista elementów tabs.Tab.id, do których powinna pasować reguła. 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 pasujący do adresu URL żądania sieciowego. Obsługiwane konstrukcje:

    '*' : symbol wieloznaczny: odpowiada dowolnej liczbie znaków.

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

    „||” : kotwica nazwy domeny: jeśli jest używana na początku wzorca, określa początek (subdomeny) adresu URL.

    '^' : znak separatora: odpowiada dowolnemu znakowi oprócz litery, cyfr lub jednego z tych znaków: _, -, . lub %. Odpowiada też końcowi adresu URL.

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

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

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

    Uwaga: można określić tylko jedną wartość urlFilter lub regexFilter.

    Uwaga: pole urlFilter może zawierać tylko znaki ASCII. Jest on dopasowywany do adresu URL, w którym host jest kodowany w formacie punycode (w przypadku domen międzynarodowych), a wszelkie inne znaki spoza zestawu ASCII są zakodowane w formacie UTF-8. Jeśli na przykład URL żądania to http://abc.р określany?q=dimension, urlFilter zostanie dopasowany 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 zaczynają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 i nowsze wersje

Właściwości

  • Zwiększ

    Liczba

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

  • tabId

    Liczba

    Karta, na której chcesz zaktualizować liczbę działań.

TestMatchOutcomeResult

Chrome 103 i nowsze wersje

Właściwości

  • matchedRules

    MatchedRule[]

    Reguły (jeśli występują) pasujące do hipotetycznego żądania.

TestMatchRequestDetails

Chrome 103 i nowsze wersje

Właściwości

  • inicjator

    ciąg znaków opcjonalny

    Adres URL inicjatora (jeśli występuje) hipotetycznego żądania.

  • method

    RequestMethod opcjonalny

    Standardowa metoda HTTP hipotetycznego żądania. W przypadku żądań HTTP przyjmuje domyślnie wartość „get” i jest ignorowana w przypadku żądań innych niż HTTP.

  • tabId

    Liczba opcjonalnie

    Identyfikator karty, na której występuje 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 i nowsze wersje

Opisuje przyczynę, dla której dane wyrażenie regularne nie jest obsługiwane.

Typ wyliczeniowy

"syntaxError"
Wyrażenie regularne ma nieprawidłową składnię lub wykorzystuje funkcje niedostępne w składni RE2.

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

UpdateRuleOptions

Chrome 87 i nowsze wersje

Właściwości

  • addRules

    Rule (Reguła) [] opcjonalny

    Reguły do dodania.

  • removeRuleIds

    number[] opcjonalny

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

UpdateRulesetOptions

Chrome 87 i nowsze wersje

Właściwości

  • disableRulesetIds

    string[] opcjonalny

    Zestaw identyfikatorów odpowiadających statycznemu elementowi Ruleset, które należy wyłączyć.

  • enableRulesetIds

    string[] opcjonalny

    Zestaw identyfikatorów odpowiadający statycznemu elementowi Ruleset, który należy włączyć.

UpdateStaticRulesOptions

Chrome 111 i nowsze wersje

Właściwości

  • disableRuleIds

    number[] opcjonalny

    Zestaw identyfikatorów odpowiadających regułom w Ruleset, które mają zostać wyłączone.

  • enableRuleIds

    number[] opcjonalny

    Zestaw identyfikatorów odpowiadających regułom w Ruleset, które mają być włączone.

  • rulesetId

    string,

    Identyfikator odpowiadający statycznemu elementowi Ruleset.

URLTransform

Właściwości

  • fragment

    ciąg znaków opcjonalny

    Nowy fragment żądania. Pole powinno być puste. W takim przypadku istniejący fragment zostanie wyczyszczony lub powinien zaczynać się od znaku „#”.

  • organizator

    ciąg znaków opcjonalny

    Nowy host żądania.

  • hasło

    ciąg znaków opcjonalny

    Nowe hasło do żądania.

  • ścieżka

    ciąg znaków opcjonalny

    Nowa ścieżka żądania. Jeśli jest pusta, bieżąca ścieżka zostanie wyczyszczona.

  • port

    ciąg znaków opcjonalny

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

  • zapytanie

    ciąg znaków opcjonalny

    Nowe zapytanie dotyczące żądania. Pole powinno być puste. W takim przypadku istniejące zapytanie zostanie wyczyszczone lub powinno zaczynać się od „?”.

  • queryTransform

    Opcjonalnie QueryTransform

    Dodawaj, usuwaj lub zastępuj 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 żądania.

Właściwości

DYNAMIC_RULESET_ID

Identyfikator zestawu reguł dla reguł dynamicznych dodanych przez rozszerzenie.

Wartość

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Przedział czasu (w minutach), w którym można wykonywać połączenia MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules. Dodatkowe połączenia nie będą natychmiast działać i zostaną skonfigurowane runtime.lastError. Uwaga: wywołania getMatchedRules powiązane z gestem użytkownika są zwolnione z limitu.

Wartość

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 i nowsze wersje

Minimalna liczba reguł statycznych gwarantowanych przez rozszerzenie we wszystkich włączonych statycznych zestawach reguł. Reguły powyżej tego limitu wliczają się do limitu globalnych reguł statycznych.

Wartość

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Liczba wywołań metody getMatchedRules w okresie GETMATCHEDRULES_QUOTA_INTERVAL.

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

Maksymalna liczba statycznych elementów Rulesets, które rozszerzenie może włączyć jednocześnie.

Wartość

50

MAX_NUMBER_OF_REGEX_RULES

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

Wartość

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 i nowsze wersje

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

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

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

Wartość

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 i nowsze wersje

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

Wartość

5000

SESSION_RULESET_ID

Chrome 90 i nowsze

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ć, zanim zostanie osiągnięty limit globalnych reguł statycznych.

Parametry

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (count: number)=>void

    • liczba

      Liczba

Akcje powrotne

  • Obietnica<number>

    Chrome 91 i nowsze wersje

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

getDisabledRuleIds()

Obietnica Chrome w wersji 111 lub nowszej 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

Zwraca listę reguł statycznych, które są obecnie wyłączone w obrębie danego elementu Ruleset.

Parametry

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

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (disabledRuleIds: number[])=>void

    • disabledRuleIds

      liczba[]

Akcje powrotne

  • Obietnica<number[]>

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

getDynamicRules()

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

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

Parametry

  • filter

    Opcjonalnie GetRulesFilter

    Chrome 111 i nowsze wersje

    Obiekt do filtrowania listy pobranych reguł.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (rules: Rule[])=>void

Akcje powrotne

  • Obietnica<Reguła[]>

    Chrome 91 i nowsze wersje

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

getEnabledRulesets()

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

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

Parametry

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (rulesetIds: string[])=>void

    • rulesetIds

      string[]

Akcje powrotne

  • Obietnica<string[]>

    Chrome 91 i nowsze wersje

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

getMatchedRules()

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

Zwraca wszystkie reguły pasujące do rozszerzenia. Wywołujący mogą opcjonalnie filtrować listę dopasowanych reguł, określając element filter. Ta metoda jest dostępna tylko w przypadku rozszerzeń z uprawnieniem "declarativeNetRequestFeedback" lub uprawnieniem "activeTab" dla elementu tabId określonego w filter. Uwaga: reguły niepowiązane z aktywnym dokumentem, które zostały dopasowane ponad pięć minut temu, nie zostaną zwrócone.

Parametry

Akcje powrotne

  • Chrome 91 i nowsze wersje

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

getSessionRules()

Obietnica Chrome w wersji 90 lub nowszej 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

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

Parametry

  • filter

    Opcjonalnie GetRulesFilter

    Chrome 111 i nowsze wersje

    Obiekt do filtrowania listy pobranych reguł.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (rules: Rule[])=>void

Akcje powrotne

  • Obietnica<Reguła[]>

    Chrome 91 i nowsze wersje

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

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

Akcje powrotne

  • Chrome 91 i nowsze wersje

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

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, oraz umożliwia zwiększanie tej liczby.

Parametry

  • wywołanie zwrotne

    funkcja opcjonalnie

    Chrome 89 i nowsze wersje

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 91 i nowsze wersje

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

testMatchOutcome()

Obietnica Chrome w wersji 103 lub nowszej 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

Sprawdza, czy któraś z reguł deklaratywnych NetRequest rozszerzenia pasuje do hipotetycznego żądania. Uwaga: opcja dostępna tylko w przypadku rozszerzeń bez pakietu, ponieważ należy jej używać wyłącznie podczas tworzenia rozszerzeń.

Parametry

Akcje powrotne

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

updateDynamicRules()

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

Modyfikuje bieżący zestaw reguł dynamicznych rozszerzenia. Reguły o identyfikatorach wymienione w kolumnie options.removeRuleIds zostaną najpierw usunięte, a potem dodane zostaną reguły podane w polu options.addRules. Uwagi:

  • Ta aktualizacja to pojedyncza operacja niepodzielna: wszystkie określone reguły zostaną dodane i usunięte albo zostanie zwrócony błąd.
  • Te reguły obowiązują przy wszystkich sesjach przeglądarki i aktualizacjach rozszerzeń.
  • Reguł statycznych określonych w pakiecie rozszerzeń nie można usunąć za pomocą tej funkcji.
  • MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES to maksymalna liczba połączonych reguł dynamicznych i reguł sesji, które może dodać rozszerzenie.

Parametry

  • Chrome 87 i nowsze wersje
  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 91 i nowsze wersje

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

updateEnabledRulesets()

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

Aktualizuje zestaw włączonych statycznych zestawów reguł dla rozszerzenia. Zestawy reguł z identyfikatorami wymienionymi w zasadzie options.disableRulesetIds zostaną najpierw usunięte, a potem dodane zostaną zestawy reguł wymienione w zasadzie options.enableRulesetIds. Pamiętaj, że zestaw włączonych statycznych zestawów reguł jest zachowywany w wielu sesjach, ale nie podczas aktualizacji rozszerzeń, np. klucz pliku manifestu rule_resources określa zestaw włączonych statycznych zestawów reguł przy każdej aktualizacji rozszerzenia.

Parametry

  • Chrome 87 i nowsze wersje
  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 91 i nowsze wersje

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

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 wymienione w kolumnie options.removeRuleIds zostaną najpierw usunięte, a potem dodane zostaną reguły podane w polu options.addRules. Uwagi:

  • Ta aktualizacja to pojedyncza operacja niepodzielna: wszystkie określone reguły zostaną dodane i usunięte albo zostanie zwrócony błąd.
  • Reguły te nie są zachowywane w wielu sesjach, a ich kopie zapasowe są zapisywane w pamięci.
  • MAX_NUMBER_OF_DYNAMIC_AND_SESSION_RULES to maksymalna liczba połączonych reguł dynamicznych i reguł sesji, które może dodać rozszerzenie.

Parametry

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 91 i nowsze wersje

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

updateStaticRules()

Obietnica Chrome w wersji 111 lub nowszej 
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łączonego elementu Ruleset zaczną obowiązywać po następnym włączeniu tej funkcji.

Parametry

Akcje powrotne

  • Promise<void>

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

Wydarzenia

onRuleMatchedDebug

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

Uruchamiane, gdy reguła zostanie dopasowana do żądania. Ta opcja jest dostępna tylko w przypadku rozszerzeń bez pakietu z uprawnieniem "declarativeNetRequestFeedback", ponieważ jest przeznaczona wyłącznie do debugowania.

Parametry