chrome.declarativeNetRequest

Opis

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

Uprawnienia

declarativeNetRequest
declarativeNetRequestWithHostAccess

Uprawnienia „declarativeNetRequest” i „declarativeNetRequestWithHostAccess” zapewniają te same możliwości. Różnica między nimi polega na tym, kiedy uprawnienia są wymagane lub przyznawane.

"declarativeNetRequest"
Podczas instalacji wywołuje ostrzeżenie o uprawnieniach, ale zapewnia niejawny dostęp do reguł allow, allowAllRequests i block. Jeśli to możliwe, używaj tej opcji, aby uniknąć konieczności proszenia organizatorów o pełny dostęp.
"declarativeNetRequestFeedback"
Włącza funkcje debugowania rozpakowanych rozszerzeń, w szczególności getMatchedRules() i onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
Ostrzeżenie o uprawnieniach nie jest wyświetlane podczas instalacji, ale przed wykonaniem jakiegokolwiek działania na hoście musisz poprosić o uprawnienia hosta. Jest to odpowiednie, gdy chcesz używać reguł deklaratywnych żądań sieciowych w rozszerzeniu, które ma już uprawnienia hosta, bez generowania dodatkowych ostrzeżeń.

Dostępność

Chrome 84 lub nowsza

Plik manifestu

Oprócz opisanych wcześniej 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 jednym kluczem o nazwie "rule_resources". Ten klucz to tablica zawierająca słowniki typu Ruleset, jak pokazano poniżej. (Pamiętaj, że nazwa „Ruleset” nie pojawia się w pliku JSON manifestu, ponieważ jest to tylko tablica). Statyczne zestawy reguł zostały omówione 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/*"   ],   ... }

Reguły i zestawy reguł

Aby używać tego interfejsu API, określ co najmniej 1 zestaw reguł. Zbiór reguł zawiera tablicę reguł. Pojedyncza reguła wykonuje jedną z tych czynności:

  • Zablokuj żądanie sieciowe.
  • Zaktualizuj schemat (z http na https).
  • Zapobiega blokowaniu żądania przez negowanie pasujących zablokowanych reguł.
  • przekierowywać żądania sieciowe,
  • modyfikować nagłówki żądań lub odpowiedzi;

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

Dynamiczne
Są zachowywane w różnych sesjach przeglądarki i po uaktualnieniu rozszerzenia. Zarządza się nimi za pomocą JavaScriptu, gdy rozszerzenie jest używane.
Sesja
Czyszczone po zamknięciu przeglądarki i zainstalowaniu nowej wersji rozszerzenia. Reguły sesji są zarządzane za pomocą JavaScriptu podczas korzystania z rozszerzenia.
Statyczny
Pakowane, instalowane i aktualizowane podczas instalowania lub uaktualniania rozszerzenia. Reguły statyczne są przechowywane w plikach reguł w formacie JSON i wymienione w pliku manifestu.

Zestawy reguł dynamicznych i ograniczonych do sesji

Zestawy reguł dynamicznych i sesji są zarządzane za pomocą JavaScriptu podczas korzystania z rozszerzenia.

  • Reguły dynamiczne są zachowywane w kolejnych sesjach przeglądarki i aktualizacjach rozszerzenia.
  • Reguły sesji są usuwane po zamknięciu przeglądarki i zainstalowaniu nowej wersji rozszerzenia.

Każdy z tych typów zbiorów reguł występuje tylko raz. Rozszerzenie może dynamicznie dodawać i usuwać reguły, wywołując funkcje updateDynamicRules() i updateSessionRules(), o ile nie przekracza limitów reguł. Informacje o limitach reguł znajdziesz w artykule Limity reguł. Przykład znajdziesz w przykładach kodu.

Statyczne zestawy reguł

W przeciwieństwie do reguł dynamicznych i 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ą wskazywane rozszerzeniu za pomocą kluczy "declarative_net_request" i "rule_resources" zgodnie z opisem powyżej, a także za pomocą co najmniej jednego słownika Ruleset. Słownik Ruleset zawiera ścieżkę do pliku reguł, identyfikator zestawu reguł zawartego w pliku oraz informację o tym, czy zestaw reguł jest włączony czy wyłączony. Dwa ostatnie są ważne, gdy włączasz lub wyłączasz zestaw reguł programowo.

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

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

Przyspieszone sprawdzanie

Zmiany w statycznych zestawach reguł mogą kwalifikować się do przyspieszonego sprawdzania. Zobacz przyspieszoną weryfikację kwalifikujących się zmian.

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

Zarówno poszczególne reguły statyczne, jak i całe zbiory reguł statycznych można włączać i wyłączać w czasie działania programu.

Zestaw włączonych reguł statycznych i zbiorów reguł jest zachowywany w kolejnych sesjach przeglądarki. Żadne z nich nie są zachowywane po aktualizacji rozszerzenia, co oznacza, że po aktualizacji dostępne są tylko reguły, które zostały w plikach reguł.

Ze względu na wydajność obowiązują 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 Limity reguł.

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

Aby włączyć lub wyłączyć statyczne zbiory reguł, wywołaj funkcję updateEnabledRulesets(). Ta metoda przyjmuje obiekt UpdateRulesetOptions, który zawiera 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 zaczyna się od 4 pól, jak pokazano poniżej. Klucze "id" i "priority" przyjmują liczbę, a klucze "action" i "condition" mogą zawierać kilka warunków blokowania i przekierowywania. Ta reguła blokuje wszystkie żądania skryptów pochodzące z "foo.com" i wysyłane do dowolnego adresu URL zawierającego "abc" jako podciąg.

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

Dopasowywanie adresów URL

Interfejs Declarative Net Request umożliwia dopasowywanie adresów URL za pomocą składni dopasowywania wzorców lub wyrażeń regularnych.

Składnia filtra adresów URL

Klucz "condition" reguły umożliwia użycie klucza "urlFilter" do działania na adresach URL w określonej domenie. Wzorce tworzy się za pomocą tokenów dopasowania do wzorca. Oto kilka przykładów:

urlFilter Dopasowania 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://a.example.company		 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

Wyrażenia regularne

Warunki mogą też korzystać z wyrażeń regularnych. Zobacz klucz "regexFilter". Aby dowiedzieć się więcej o limitach, które obowiązują w przypadku tych warunków, zapoznaj się z artykułem Reguły korzystające z wyrażeń regularnych.

Tworzenie dobrych warunków dotyczących adresu URL

Podczas tworzenia reguł należy zachować ostrożność, aby zawsze dopasowywać całą domenę. W przeciwnym razie reguła może być dopasowywana w nieoczekiwanych sytuacjach. Na przykład podczas korzystania ze składni dopasowywania wzorców:

  • google.com nieprawidłowo dopasowuje https://example.com/?param=google.com
  • ||google.com nieprawidłowo dopasowuje https://google.company
  • https://www.google.com nieprawidłowo dopasowuje https://example.com/?param=https://www.google.com

Możesz użyć:

  • ||google.com/, który pasuje do wszystkich ścieżek i wszystkich subdomen.
  • |https://www.google.com/, która pasuje do wszystkich ścieżek, ale nie do subdomen.

Podobnie używaj znaków ^ i /, aby zakotwiczyć wyrażenie regularne. Na przykład znak ^https:\/\/www\.google\.com\/ pasuje do dowolnej ścieżki na stronie https://www.google.com.

Ocena reguły

Reguły DNR są stosowane przez przeglądarkę na różnych etapach cyklu życia żądania sieciowego.

Przed przesłaniem prośby

Przed wysłaniem żądania rozszerzenie może je zablokować lub przekierować (w tym uaktualnić schemat z HTTP do HTTPS) za pomocą pasującej reguły.

W przypadku każdego rozszerzenia przeglądarka określa listę pasujących reguł. Nie uwzględniamy tu reguł z działaniem modifyHeaders, ponieważ zostaną one obsłużone później. Dodatkowo reguły z warunkiem responseHeaders będą rozpatrywane później (gdy będą dostępne nagłówki odpowiedzi) i nie są uwzględniane.

Następnie w przypadku każdego rozszerzenia Chrome wybiera co najwyżej 1 kandydata na żądanie. Chrome znajduje pasującą regułę, porządkując wszystkie pasujące reguły według priorytetu. Reguły o tym samym priorytecie są uporządkowane według działania (allow lub allowAllRequests > block > upgradeScheme > redirect).

Jeśli kandydat jest regułą allow lub allowAllRequests albo ramka, w której wysyłane jest żądanie, wcześniej pasowała do reguły allowAllRequests o wyższym lub równym priorytecie z tego rozszerzenia, żądanie jest „dozwolone”, a rozszerzenie nie będzie miało na nie wpływu.

Jeśli więcej niż 1 rozszerzenie chce zablokować lub przekierować to żądanie, wybierane jest jedno działanie. Chrome sortuje reguły w kolejności block > redirect lub upgradeScheme > allow lub allowAllRequests. Jeśli 2 reguły są tego samego typu, Chrome wybiera regułę z ostatnio zainstalowanego rozszerzenia.

Przed wysłaniem nagłówków żądań

Zanim Chrome wyśle nagłówki żądań do serwera, są one aktualizowane na podstawie pasujących reguł modifyHeaders.

W ramach jednego rozszerzenia Chrome tworzy listę modyfikacji do wykonania, wyszukując wszystkie pasujące reguły modifyHeaders. Podobnie jak wcześniej uwzględniane są tylko reguły o wyższym priorytecie niż pasujące reguły allow lub allowAllRequests.

Chrome stosuje te reguły w taki sposób, że reguły z niedawno zainstalowanego rozszerzenia są zawsze sprawdzane przed regułami ze starszego rozszerzenia. Ponadto reguły o wyższym priorytecie z jednego rozszerzenia są zawsze stosowane przed regułami o niższym priorytecie z tego samego rozszerzenia. Warto zauważyć, że nawet w przypadku rozszerzeń:

  • Jeśli reguła dodaje informacje do nagłówka, reguły o niższym priorytecie mogą dodawać informacje tylko do tego nagłówka. Operacje ustawiania i usuwania są niedozwolone.
  • Jeśli reguła ustawia nagłówek, tylko reguły o niższym priorytecie z tego samego rozszerzenia mogą do niego dodawać informacje. Nie można wprowadzać żadnych innych modyfikacji.
  • Jeśli reguła usunie nagłówek, reguły o niższym priorytecie nie będą mogły go dalej modyfikować.

Po otrzymaniu odpowiedzi

Po otrzymaniu nagłówków odpowiedzi Chrome ocenia reguły z warunkiem responseHeaders.

Po posortowaniu tych reguł według action i priority oraz wykluczeniu reguł, które stały się zbędne z powodu pasującej reguły allow lub allowAllRequests (odbywa się to identycznie jak w przypadku kroków opisanych w sekcji „Przed wysłaniem żądania”), Chrome może zablokować lub przekierować żądanie w imieniu rozszerzenia.

Pamiętaj, że jeśli żądanie dotarło do tego etapu, zostało już wysłane do serwera, a serwer otrzymał dane, takie jak treść żądania. Reguła blokowania lub przekierowania z warunkiem nagłówków odpowiedzi nadal będzie działać, ale nie będzie mogła zablokować ani przekierować żądania.

W przypadku reguły blokowania strona, która wysłała żądanie, otrzymuje odpowiedź o zablokowaniu, a Chrome wcześnie przerywa żądanie. W przypadku reguły przekierowania Chrome wysyła nowe żądanie do przekierowanego adresu URL. Zastanów się, czy te zachowania są zgodne z oczekiwaniami użytkowników dotyczącymi prywatności.

Jeśli żądanie nie zostanie zablokowane ani przekierowane, Chrome zastosuje reguły modifyHeaders. Stosowanie modyfikacji nagłówków odpowiedzi działa w taki sam sposób jak opisano w sekcji „Przed wysłaniem nagłówków żądania”. Wprowadzanie zmian w nagłówkach żądań nie przynosi żadnego efektu, ponieważ żądanie zostało już wysłane.

Bezpieczne reguły

Bezpieczne reguły to reguły z działaniem block, allow, allowAllRequests lub upgradeScheme. W przypadku tych reguł obowiązuje zwiększony limit reguł dynamicznych.

Ograniczenia reguł

Wczytywanie i ocenianie reguł w przeglądarce wiąże się z obciążeniem wydajności, dlatego podczas korzystania z interfejsu API obowiązują pewne limity. 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 określać maksymalnie 100 statycznych zestawów reguł w ramach klucza manifestu "rule_resources", ale jednocześnie można włączyć tylko 50 z nich. Ten drugi typ nazywa się MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Łącznie te zestawy reguł gwarantują co najmniej 30 tys. reguł. Jest to tzw. GUARANTEED_MINIMUM_STATIC_RULES.

Liczba reguł dostępnych po tym czasie zależy od tego, ile reguł jest włączonych przez wszystkie rozszerzenia zainstalowane w przeglądarce użytkownika. Ten numer możesz sprawdzić w czasie działania programu, wywołując funkcję getAvailableStaticRuleCount(). Przykład znajdziesz w przykładach kodu.

Reguły sesji

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

W wersjach Chrome wcześniejszych niż 120 obowiązywał limit 5000 reguł dynamicznych i sesji łącznie.

Reguły dynamiczne

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

Od Chrome 121 dostępny jest większy limit 30 tys. reguł dla bezpiecznych reguł dynamicznych, które są udostępniane jako MAX_NUMBER_OF_DYNAMIC_RULES. Wszystkie niebezpieczne reguły dodane w ramach limitu 5000 reguł również będą wliczane do tego limitu.

W wersjach Chrome wcześniejszych niż 120 obowiązywał łączny limit 5000 reguł dynamicznych i sesji.

Reguły, które używają wyrażeń regularnych

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

Po skompilowaniu każda reguła musi mieć rozmiar mniejszy niż 2 KB. Jest to w przybliżeniu powiązane ze złożonością reguły. Jeśli spróbujesz wczytać regułę, która przekracza ten limit, pojawi się ostrzeżenie podobne do poniższego, 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 instancjami roboczymi usługi

Deklaratywne żądanie sieciowe ma zastosowanie tylko do żądań, które docierają do stosu sieciowego. Obejmuje to odpowiedzi z pamięci podręcznej HTTP, ale może nie obejmować odpowiedzi, które przechodzą przez moduł obsługi onfetch w usłudze Service Worker. Interfejs declarativeNetRequest nie ma wpływu na odpowiedzi generowane przez usługę Service Worker ani pobierane z CacheStorage, ale ma wpływ na wywołania fetch() wykonywane w usłudze Service Worker.

Zasoby dostępne w internecie

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

Modyfikacja nagłówka

Operacja dołączania jest obsługiwana tylko w przypadku tych nagłówków: accept, accept-encoding, accept-language, access-control-request-headers, cache-control, connection, content-language, cookie, forwarded, if-match, if-none-match, keep-alive, range, te, trailer, transfer-encoding, upgrade, user-agent, via, want-digest, x-forwarded-for.

Przykłady

Przykłady kodu

Aktualizowanie reguł dynamicznych

Poniższy przykład pokazuje, jak wywołać updateDynamicRules(). Procedura w przypadku 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ł. Zrobisz to, gdy liczba potrzebnych reguł statycznych przekroczy dozwoloną liczbę. Aby to działało, niektóre zestawy reguł powinny być zainstalowane, a niektóre wyłączone (ustawienie "Enabled" na false w pliku manifestu).

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 ustala priorytety reguł w rozszerzeniu. Podczas sprawdzania reguł możesz otworzyć reguły priorytetyzacji w osobnym oknie.

Klucz „priority”

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

Aby określić priorytet danego adresu URL, sprawdź klucze "priority", "action" i "urlFilter" (zdefiniowane przez dewelopera). Przykłady te odnoszą się do przykładowego pliku reguł pokazanego poniżej.

Przejście na stronę https://google.com
Ten adres URL obejmują 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.
Przejście na stronę https://google.com/1234
Ze względu na dłuższy adres URL reguła o identyfikatorze 2 pasuje teraz do reguł o identyfikatorach 1 i 4. Zastosowana zostanie reguła o identyfikatorze 2, ponieważ priorytet "allow" jest wyższy niż priorytety "block" i "redirect".
Przejście na stronę https://google.com/12345
Do tego adresu URL pasują wszystkie 4 reguły. Zastosowana zostanie reguła o identyfikatorze 3, ponieważ jej priorytet zdefiniowany przez dewelopera jest najwyższy 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

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

W przykładzie poniżej pokazujemy, jak przekierować żądanie z domeny example.com na stronę w ramach samego rozszerzenia. Ścieżka rozszerzenia /a.jpg jest przekształcana w chrome-extension://EXTENSION_ID/a.jpg, gdzie EXTENSION_ID to identyfikator rozszerzenia. Aby to działało, w pliku manifestu należy zadeklarować /a.jpg jako zasób dostępny w internecie.

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

Poniższy przykład używa klucza "transform" do przekierowania do subdomeny example.com. Używa kotwicy nazwy domeny („||”), aby przechwytywać żądania z dowolnym schematem z domeny example.com. Klucz "scheme" w "transform" określa, że przekierowania do subdomeny będą zawsze używać protokołu „https”.

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

W przykładzie poniżej użyto wyrażeń regularnych do przekierowania z https://www.abc.xyz.com/path na https://abc.xyz.com/path. W kluczu "regexFilter" zwróć uwagę, że kropki są poprzedzone znakiem ucieczki, a grupa przechwytująca wybiera „abc” lub „def”. Klucz "regexSubstitution" określa pierwsze zwrócone dopasowanie wyrażenia regularnego przy użyciu „\1”. W tym przypadku ciąg „abc” jest pobierany z przekierowanego adresu URL i umieszczany w podstawieniu.

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

W przykładzie poniżej usuwane są wszystkie pliki cookie z głównej ramki 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

Określa, czy żądanie jest własne czy pochodzi od osoby trzeciej w ramce, w której zostało wygenerowane. Żądanie jest uznawane za pochodzące z tej samej domeny, jeśli ma taką samą domenę (eTLD+1) jak ramka, w której zostało wygenerowane.

Typ wyliczeniowy

„firstParty”
Żądanie sieciowe jest własne w stosunku do ramki, w której zostało wygenerowane.

„thirdParty”
Żądanie sieciowe pochodzi od innej firmy niż ramka, w której zostało wygenerowane.

ExtensionActionOptions

Chrome 88 lub nowsza

Właściwości

  • displayActionCountAsBadgeText

    wartość logiczna opcjonalna

    Określa, czy liczba działań na stronie ma być automatycznie wyświetlana jako tekst plakietki rozszerzenia. To ustawienie jest zachowywane między sesjami.

  • tabUpdate

    TabActionCountUpdate [opcjonalnie]

    Chrome 89 lub nowszy

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

GetDisabledRuleIdsOptions

Chrome 111 lub nowsza

Właściwości

  • rulesetId

    ciąg znaków

    Identyfikator odpowiadający statycznemu Ruleset.

GetRulesFilter

Chrome 111 lub nowsza

Właściwości

  • ruleIds

    number[] opcjonalny

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

HeaderInfo

Chrome 128 lub nowsza

Właściwości

  • excludedValues

    string[] opcjonalne

    Jeśli ten warunek jest określony, nie zostanie dopasowany, jeśli nagłówek istnieje, ale jego wartość zawiera co najmniej 1 element z tej listy. Używa tej samej składni wzorca dopasowania co values.

  • nagłówek

    ciąg znaków

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

  • wartości

    string[] opcjonalne

    Jeśli ten warunek jest określony, jest on spełniony, gdy wartość nagłówka pasuje do co najmniej jednego wzorca na tej liście. Obsługuje dopasowywanie wartości nagłówka bez uwzględniania wielkości liter oraz te konstrukcje:

    „*” : odpowiada dowolnej liczbie znaków.

    „?” : dopasowuje zero lub jeden znak.

    Znaki „*” i „?” można poprzedzić ukośnikiem, np. „\*” i „\?”.

HeaderOperation

Chrome w wersji 86 lub nowszej

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

Typ wyliczeniowy

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

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

„remove”
Usuwa wszystkie wpisy dla określonego nagłówka.

IsRegexSupportedResult

Chrome w wersji 87 lub nowszej

Właściwości

  • isSupported

    Wartość logiczna

  • powód,

    UnsupportedRegexReason opcjonalny

    Określa przyczynę, dla której wyrażenie regularne nie jest obsługiwane. Podawany tylko wtedy, gdy wartość parametru isSupported to 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 z zestawu reguł dynamicznych wartość ta będzie równa DYNAMIC_RULESET_ID.

MatchedRuleInfo

Właściwości

  • reguła

    MatchedRule

  • tabId

    liczba

    Identyfikator karty, z której pochodzi żądanie, jeśli karta jest nadal aktywna. W przeciwnym razie –1.

  • timeStamp

    liczba

    Czas, w którym reguła została dopasowana. Sygnatury czasowe będą zgodne z konwencją JavaScript dotyczącą czasu, czyli liczbą milisekund od początku epoki.

MatchedRuleInfoDebug

Właściwości

MatchedRulesFilter

Właściwości

  • minTimeStamp

    number opcjonalny

    Jeśli podano, dopasowuje tylko reguły po określonej sygnaturze czasowej.

  • tabId

    number opcjonalny

    Jeśli podasz tę wartość, będą dopasowywane tylko reguły na danej karcie. Dopasowuje reguły, które nie są powiązane z żadną aktywną kartą, jeśli wartość jest ustawiona na -1.

ModifyHeaderInfo

Chrome w wersji 86 lub nowszej

Właściwości

  • nagłówek

    ciąg znaków

    Nazwa nagłówka do zmodyfikowania.

  • operacja

    HeaderOperation

    Operacja, która ma zostać wykonana na nagłówku.

  • wartość

    string 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 94 lub nowsza

    Jeśli wartość to „true”, klucz zapytania jest zastępowany tylko wtedy, gdy już występuje. W przeciwnym razie klucz jest dodawany, jeśli go brakuje. Wartość domyślna to fałsz.

  • wartość

    ciąg znaków

QueryTransform

Właściwości

  • addOrReplaceParams

    QueryKeyValue[] opcjonalnie

    Lista par klucz-wartość zapytania do dodania lub zastąpienia.

  • removeParams

    string[] opcjonalne

    Lista kluczy zapytań do usunięcia.

Redirect

Właściwości

  • extensionPath

    string opcjonalny

    Ścieżka względna katalogu rozszerzenia. Powinien zaczynać się od znaku „/”.

  • regexSubstitution

    string opcjonalny

    Wzorzec zastępowania w przypadku reguł, które określają regexFilter. Pierwsze dopasowanie regexFilter w adresie URL zostanie zastąpione tym wzorcem. W regexSubstitution można używać cyfr z ukośnikiem odwrotnym (\1–\9), aby wstawiać odpowiednie grupy przechwytywania. \0 odnosi się do całego pasującego tekstu.

  • przekształcenie

    URLTransform opcjonalny

    Przekształcenia adresu URL do wykonania.

  • URL

    string opcjonalny

    Adres URL przekierowania. Przekierowania do adresów URL JavaScript są niedozwolone.

RegexOptions

Chrome w wersji 87 lub nowszej

Właściwości

  • isCaseSensitive

    wartość logiczna opcjonalna

    Określa, czy w przypadku podanego parametru regex ma być uwzględniana 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 podany element regex wymaga przechwycenia. Przechwytywanie jest wymagane tylko w przypadku reguł przekierowania, które określają działanie regexSubstition. Wartość domyślna to fałsz.

RequestDetails

Właściwości

  • documentId

    string opcjonalny

    Chrome 106 lub nowsza

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

  • documentLifecycle

    DocumentLifecycle opcjonalny

    Chrome 106 lub nowsza

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

  • frameId

    liczba

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

  • frameType

    FrameType opcjonalny

    Chrome 106 lub nowsza

    Rodzaj ramki, jeśli to żądanie dotyczy ramki.

  • inicjator,

    string opcjonalny

    Pochodzenie, z którego zostało zainicjowane żądanie. Nie zmienia się on w przypadku przekierowań. Jeśli jest to nieprzezroczyste źródło, używany jest ciąg znaków „null”.

  • method

    ciąg znaków

    Standardowa metoda HTTP.

  • parentDocumentId

    string opcjonalny

    Chrome 106 lub nowsza

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

  • parentFrameId

    liczba

    Identyfikator ramki, która zawiera ramkę wysyłającą żądanie. Jeśli nie ma ramki nadrzędnej, ustaw wartość -1.

  • requestId

    ciąg znaków

    Identyfikator żądania. Identyfikatory żądań są unikalne w ramach sesji przeglądarki.

  • tabId

    liczba

    Identyfikator karty, na której następuje żądanie. Ustaw wartość -1, jeśli żądanie nie jest powiązane z kartą.

  • Typ zasobu żądania.

  • URL

    ciąg znaków

    Adres URL żądania.

RequestMethod

Chrome 91 lub nowsza

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

Typ wyliczeniowy

„connect”

„delete”

„get”

„head”

„options”

„patch”

„post”

„put”

„other”

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”

„other”

Rule

Właściwości

  • działanie

    RuleAction

    Działanie, które należy podjąć, jeśli treść pasuje do tej reguły.

  • warunek

    RuleCondition

    Warunek, który wywołuje tę regułę.

  • id

    liczba

    Identyfikator, który jednoznacznie identyfikuje regułę. Wymagany i musi być >= 1.

  • kampanii

    number opcjonalny

    Priorytet reguły. Domyślna wartość to 1. Jeśli wartość jest określona, powinna być >= 1.

RuleAction

Właściwości

  • Przekieruj

    Przekierowanie opcjonalne

    Opisuje, jak powinno przebiegać przekierowanie. Dotyczy tylko reguł przekierowania.

  • requestHeaders

    ModifyHeaderInfo[] opcjonalnie

    Chrome w wersji 86 lub nowszej

    Nagłówki żądania do zmodyfikowania. Prawidłowe tylko wtedy, gdy RuleActionType to „modifyHeaders”.

  • responseHeaders

    ModifyHeaderInfo[] opcjonalnie

    Chrome w wersji 86 lub nowszej

    Nagłówki odpowiedzi do zmodyfikowania w przypadku żądania. Prawidłowe tylko wtedy, gdy RuleActionType to „modifyHeaders”.

  • Typ działania do wykonania.

RuleActionType

Opisuje rodzaj działania, które należy podjąć, jeśli dany warunek reguły zostanie spełniony.

Typ wyliczeniowy

„block”
Blokuje żądanie sieciowe.

„redirect”
Przekieruj żądanie sieciowe.

„allow”
Zezwól na żądanie sieciowe. Jeśli istnieje pasująca reguła zezwalająca, żądanie nie zostanie przechwycone.

„upgradeScheme”
Zaktualizuj schemat adresu URL żądania sieciowego do https, jeśli żądanie jest typu http lub ftp.

„modifyHeaders”
Modyfikowanie nagłówków żądania lub odpowiedzi w żądaniu sieciowym.

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

RuleCondition

Właściwości

  • domainType

    DomainType opcjonalny

    Określa, czy żądanie sieciowe jest własne czy pochodzi od innej firmy w domenie, z której zostało wysłane. Jeśli go pominiesz, wszystkie prośby zostaną zaakceptowane.

  • domeny

    string[] opcjonalne

    Wycofane w Chrome 101

    Użyj w zamian elementu initiatorDomains

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

  • excludedDomains

    string[] opcjonalne

    Wycofane w Chrome 101

    Użyj w zamian elementu excludedInitiatorDomains

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

  • excludedInitiatorDomains

    string[] opcjonalne

    Chrome 101 lub nowsza

    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 to pierwszeństwo przed initiatorDomains.

    Uwagi:

    • Dozwolone są też subdomeny, np. „a.example.com”.
    • Wpisy muszą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania Punycode.
    • Dopasowanie następuje do inicjatora żądania, a nie do adresu URL żądania.
    • Wykluczane są też subdomeny wymienionych domen.
  • excludedRequestDomains

    string[] opcjonalne

    Chrome 101 lub nowsza

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

    Uwagi:

    • Dozwolone są też subdomeny, np. „a.example.com”.
    • Wpisy muszą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania Punycode.
    • Wykluczane są też subdomeny wymienionych domen.
  • excludedRequestMethods

    RequestMethod[] opcjonalny

    Chrome 91 lub nowsza

    Lista metod żądań, do których reguła nie będzie pasować. Należy określić tylko jedną z wartości requestMethods lub excludedRequestMethods. Jeśli nie podasz żadnej z tych wartości, będą pasować wszystkie metody żądania.

  • excludedResourceTypes

    ResourceType[] opcjonalnie

    Lista typów zasobów, do których reguła nie będzie pasować. Należy określić tylko jedną z wartości resourceTypes lub excludedResourceTypes. Jeśli nie zostanie podany żaden z tych typów, wszystkie typy zasobów z wyjątkiem „main_frame” zostaną zablokowane.

  • excludedResponseHeaders

    HeaderInfo[] opcjonalnie

    Chrome 128 lub nowsza

    Reguła nie pasuje, jeśli żądanie pasuje do dowolnego warunku nagłówka odpowiedzi na tej liście (jeśli jest określony). Jeśli określone są zarówno właściwość excludedResponseHeaders, jak i właściwość responseHeaders, pierwszeństwo ma właściwość excludedResponseHeaders.

  • excludedTabIds

    number[] opcjonalny

    Chrome 92 lub nowsza

    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ł o zakresie sesji.

  • initiatorDomains

    string[] opcjonalne

    Chrome 101 lub nowsza

    Reguła będzie pasować tylko do żądań sieciowych pochodzących z listy initiatorDomains. Jeśli lista zostanie pominięta, reguła zostanie zastosowana do żądań ze wszystkich domen. Pusta lista jest niedozwolona.

    Uwagi:

    • Dozwolone są też subdomeny, np. „a.example.com”.
    • Wpisy muszą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania Punycode.
    • Dopasowanie następuje do inicjatora żądania, a nie do adresu URL żądania.
    • Dopasowywane są też subdomeny wymienionych domen.
  • isUrlFilterCaseSensitive

    wartość logiczna opcjonalna

    Określa, czy w atrybucie urlFilter lub regexFilter (w zależności od tego, który z nich został określony) jest rozróżniana wielkość liter. Wartość domyślna to fałsz.

  • regexFilter

    string opcjonalny

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

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

    Uwaga: regexFilter musi składać się wyłącznie ze znaków ASCII. Jest on dopasowywany do adresu URL, w którym host jest zakodowany w formacie punycode (w przypadku domen międzynarodowych), a wszystkie inne znaki spoza ASCII są zakodowane w formacie UTF-8.

  • requestDomains

    string[] opcjonalne

    Chrome 101 lub nowsza

    Reguła będzie pasować tylko do żądań sieciowych, gdy domena będzie pasować do jednej z domen na liście requestDomains. Jeśli lista zostanie pominięta, reguła zostanie zastosowana do żądań ze wszystkich domen. Pusta lista jest niedozwolona.

    Uwagi:

    • Dozwolone są też subdomeny, np. „a.example.com”.
    • Wpisy muszą zawierać tylko znaki ASCII.
    • W przypadku domen międzynarodowych używaj kodowania Punycode.
    • Dopasowywane są też subdomeny wymienionych domen.
  • requestMethods

    RequestMethod[] opcjonalny

    Chrome 91 lub nowsza

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

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

  • resourceTypes

    ResourceType[] opcjonalnie

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

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

  • responseHeaders

    HeaderInfo[] opcjonalnie

    Chrome 128 lub nowsza

    Reguła jest dopasowywana, jeśli żądanie spełnia dowolny warunek nagłówka odpowiedzi na tej liście (jeśli jest określony).

  • tabIds

    number[] opcjonalny

    Chrome 92 lub nowsza

    Lista tabs.Tab.id, do których ma 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ł o zakresie sesji.

  • urlFilter

    string opcjonalny

    Wzorzec, który jest porównywany z adresem URL żądania sieciowego. Obsługiwane konstrukcje:

    „*”: symbol wieloznaczny, który odpowiada dowolnej liczbie znaków.

    '|' : lewy/prawy punkt zakotwiczenia: jeśli jest używany na którymkolwiek końcu wzorca, określa odpowiednio początek lub koniec adresu URL.

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

    „^”: znak separatora. Odpowiada wszystkiemu z wyjątkiem litery, cyfry lub jednego z tych znaków: _, -, . lub %. Dopasowuje też koniec adresu URL.

    Dlatego urlFilter składa się z tych części: (opcjonalny lewy/nazwa domeny) + wzorzec + (opcjonalny prawy).

    Jeśli zostanie pominięty, dopasowywane są wszystkie adresy URL. Pusty ciąg znaków jest niedozwolony.

    Wzorzec zaczynający się od ||* jest niedozwolony. Zamiast niej używaj zasady *.

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

    Uwaga: urlFilter musi składać się wyłącznie ze znaków ASCII. Jest on dopasowywany do adresu URL, w którym host jest zakodowany w formacie punycode (w przypadku domen międzynarodowych), a wszystkie inne znaki spoza ASCII są zakodowane w formacie UTF-8. Jeśli na przykład adres URL żądania to http://abc.рф?q=ф, wzorzec urlFilter zostanie dopasowany 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, który jednoznacznie identyfikuje zestaw reguł. Identyfikatory zaczynające się od znaku „_” są zarezerwowane do użytku wewnętrznego.

  • ścieżka

    ciąg znaków

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

RulesMatchedDetails

Właściwości

TabActionCountUpdate

Chrome 89 lub nowszy

Właściwości

  • Zwiększ

    liczba

    Wartość, o którą należy zwiększyć liczbę działań na karcie. Wartości ujemne zmniejszają liczbę.

  • tabId

    liczba

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

TestMatchOutcomeResult

Chrome 103 lub nowsza

Właściwości

  • matchedRules

    MatchedRule[]

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

TestMatchRequestDetails

Chrome 103 lub nowsza

Właściwości

  • inicjator,

    string opcjonalny

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

  • method

    RequestMethod opcjonalny

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

  • responseHeaders

    obiekt opcjonalny

    Chrome 129 lub nowsza

    Nagłówki hipotetycznej odpowiedzi, jeśli żądanie nie zostanie zablokowane ani przekierowane przed wysłaniem. Reprezentowane jako obiekt, który mapuje nazwę nagłówka na listę wartości ciągów tekstowych. Jeśli nie zostanie określona, hipotetyczna odpowiedź zwróci puste nagłówki odpowiedzi, które mogą pasować do reguł dopasowujących się do nieistnienia nagłówków. Na przykład: {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

  • tabId

    number opcjonalny

    Identyfikator karty, na której ma miejsce hipotetyczne żądanie. Nie musi odpowiadać rzeczywistemu identyfikatorowi karty. Domyślna wartość to -1, co oznacza, że żądanie nie jest powiązane z kartą.

  • Typ zasobu hipotetycznego żądania.

  • URL

    ciąg znaków

    Adres URL hipotetycznego żądania.

UnsupportedRegexReason

Chrome w wersji 87 lub nowszej

Wyjaśnia, dlaczego dane wyrażenie regularne nie jest obsługiwane.

Typ wyliczeniowy

„syntaxError”
Wyrażenie regularne jest nieprawidłowe pod względem składni lub używa funkcji niedostępnych w składni RE2.

„memoryLimitExceeded”
Wyrażenie regularne przekracza limit pamięci.

UpdateRuleOptions

Chrome w wersji 87 lub nowszej

Właściwości

  • addRules

    Rule[] opcjonalny

    Reguły do dodania.

  • removeRuleIds

    number[] opcjonalny

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

UpdateRulesetOptions

Chrome w wersji 87 lub nowszej

Właściwości

  • disableRulesetIds

    string[] opcjonalne

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

  • enableRulesetIds

    string[] opcjonalne

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

UpdateStaticRulesOptions

Chrome 111 lub nowsza

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

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

  • rulesetId

    ciąg znaków

    Identyfikator odpowiadający statycznemu Ruleset.

URLTransform

Właściwości

  • fragment

    string opcjonalny

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

  • host

    string opcjonalny

    Nowy host żądania.

  • hasło

    string opcjonalny

    Nowe hasło do żądania.

  • ścieżka

    string opcjonalny

    Nowa ścieżka żądania. Jeśli to pole jest puste, istniejąca ścieżka zostanie wyczyszczona.

  • port

    string opcjonalny

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

  • zapytanie

    string opcjonalny

    Nowe zapytanie dotyczące prośby. Powinien być pusty (w takim przypadku istniejące zapytanie zostanie wyczyszczone) lub zaczynać się od znaku „?”.

  • queryTransform

    QueryTransform opcjonalne

    Dodawanie, usuwanie i zastępowanie par klucz-wartość w zapytaniu.

  • schemat

    string opcjonalny

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

  • nazwa użytkownika

    string opcjonalny

    Nowa nazwa użytkownika w żądaniu.

Właściwości

DYNAMIC_RULESET_ID

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

Wartość

„_dynamic”

GETMATCHEDRULES_QUOTA_INTERVAL

Przedział czasu, w którym można nawiązywać połączenia MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules, podany w minutach. Dodatkowe wywołania natychmiast się nie powiodą i ustawią wartość runtime.lastError. Uwaga: getMatchedRules wywołania powiązane z gestem użytkownika są wyłączone z limitu.

Wartość

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 lub nowszy

Minimalna liczba reguł statycznych gwarantowanych rozszerzeniu w ramach włączonych zestawów reguł statycznych. Wszystkie reguły powyżej tego limitu będą wliczane do globalnego limitu reguł statycznych.

Wartość

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Określa, ile razy można wywołać funkcję 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 lub nowsza

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

Wartość

50

MAX_NUMBER_OF_REGEX_RULES

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

Wartość

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 lub nowsza

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

Wartość

5000

MAX_NUMBER_OF_STATIC_RULESETS

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

Wartość

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 lub nowsza

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

Wartość

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 lub nowsza

Maksymalna liczba reguł o zasięgu sesji, które rozszerzenie może dodać.

Wartość

5000

SESSION_RULESET_ID

Chrome w wersji 90 lub nowszej

Identyfikator zestawu reguł dla reguł o zakresie sesji dodanych przez rozszerzenie.

Wartość

"_session"

Metody

getAvailableStaticRuleCount()

Chrome 89 lub nowszy 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(): Promise<number>

Zwraca liczbę reguł statycznych, które rozszerzenie może włączyć, zanim zostanie osiągnięty globalny limit reguł statycznych.

Zwroty

  • Promise<number>

    Chrome 91 lub nowsza

getDisabledRuleIds()

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

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

Parametry

Zwroty

  • Promise<number[]>

getDynamicRules()

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

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

Parametry

  • filtr

    GetRulesFilter opcjonalny

    Chrome 111 lub nowsza

    Obiekt do filtrowania listy pobranych reguł.

Zwroty

  • Promise<Rule[]>

    Chrome 91 lub nowsza

getEnabledRulesets()

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

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

Zwroty

  • Promise<string[]>

    Chrome 91 lub nowsza

getMatchedRules()

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

Zwraca wszystkie reguły pasujące do rozszerzenia. Rozmówcy mogą opcjonalnie filtrować listę pasujących reguł, określając filter. Ta metoda jest dostępna tylko dla rozszerzeń z uprawnieniem "declarativeNetRequestFeedback" lub z uprawnieniem "activeTab" przyznanym dla tabId określonego w filter. Uwaga: reguły, które nie są powiązane z aktywnym dokumentem i zostały dopasowane ponad 5 minut temu, nie zostaną zwrócone.

Parametry

Zwroty

getSessionRules()

Chrome w wersji 90 lub nowszej 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

Zwraca bieżący zestaw reguł w zakresie sesji dla rozszerzenia. Rozmówcy mogą opcjonalnie filtrować listę pobranych reguł, określając filter.

Parametry

  • filtr

    GetRulesFilter opcjonalny

    Chrome 111 lub nowsza

    Obiekt do filtrowania listy pobranych reguł.

Zwroty

  • Promise<Rule[]>

    Chrome 91 lub nowsza

isRegexSupported()

Chrome w wersji 87 lub nowszej 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
): Promise<IsRegexSupportedResult>

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

Parametry

  • regexOptions

    RegexOptions

    Wyrażenie regularne do sprawdzenia.

Zwroty

setExtensionActionOptions()

Chrome 88 lub nowsza 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise<void>

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

Parametry

Zwroty

  • Promise<void>

    Chrome 91 lub nowsza

testMatchOutcome()

Chrome 103 lub nowsza 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
): Promise<TestMatchOutcomeResult>

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

Parametry

Zwroty

updateDynamicRules()

chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
): Promise<void>

Modyfikuje bieżący zestaw reguł dynamicznych rozszerzenia. Najpierw usuwane są reguły z identyfikatorami wymienionymi w options.removeRuleIds, a potem dodawane są reguły podane w options.addRules. Uwagi:

  • Ta aktualizacja jest wykonywana jako pojedyncza operacja niepodzielna: wszystkie określone reguły są dodawane i usuwane albo zwracany jest błąd.
  • Te reguły są zachowywane w kolejnych sesjach przeglądarki i aktualizacjach rozszerzenia.
  • Nie można usunąć za pomocą tej funkcji reguł statycznych określonych w pakiecie rozszerzenia.
  • 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

Zwroty

  • Promise<void>

    Chrome 91 lub nowsza

updateEnabledRulesets()

chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
): Promise<void>

Aktualizuje zestaw włączonych statycznych zbiorów reguł dla rozszerzenia. Najpierw usuwane są zestawy reguł z identyfikatorami wymienionymi w options.disableRulesetIds, a potem dodawane są zestawy reguł wymienione w options.enableRulesetIds. Pamiętaj, że zestaw włączonych statycznych zbiorów reguł jest zachowywany między sesjami, ale nie między aktualizacjami rozszerzenia. Oznacza to, że klucz manifestu rule_resources określa zestaw włączonych statycznych zbiorów reguł przy każdej aktualizacji rozszerzenia.

Parametry

Zwroty

  • Promise<void>

    Chrome 91 lub nowsza

updateSessionRules()

Chrome w wersji 90 lub nowszej 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
): Promise<void>

Modyfikuje bieżący zestaw reguł o zakresie sesji dla rozszerzenia. Najpierw usuwane są reguły z identyfikatorami wymienionymi w options.removeRuleIds, a potem dodawane są reguły podane w options.addRules. Uwagi:

  • Ta aktualizacja jest wykonywana jako pojedyncza operacja niepodzielna: wszystkie określone reguły są dodawane i usuwane albo zwracany jest błąd.
  • Te reguły nie są zachowywane między sesjami i są przechowywane w pamięci.
  • MAX_NUMBER_OF_SESSION_RULES to maksymalna liczba reguł sesji, które może dodać rozszerzenie.

Parametry

Zwroty

  • Promise<void>

    Chrome 91 lub nowsza

updateStaticRules()

Chrome 111 lub nowsza 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise<void>

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

Parametry

Zwroty

  • Promise<void>

Wydarzenia

onRuleMatchedDebug

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

Uruchamiane, gdy reguła pasuje do żądania. Dostępne tylko w przypadku rozpakowanych rozszerzeń z uprawnieniem "declarativeNetRequestFeedback", ponieważ jest przeznaczone wyłącznie do debugowania.

Parametry