chrome.declarativeNetRequest

Opis

Interfejs API chrome.declarativeNetRequest służy do blokowania lub modyfikowania żądań sieciowych przez określenie reguł deklaratywnych. Dzięki temu rozszerzenia mogą modyfikować żądania sieci bez ich przechwytywania i przeglądania 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 prośby o przyznanie uprawnień są wysyłane i wyrażane.

"declarativeNetRequest"
Wyświetla ostrzeżenie o uprawnieniach w momencie instalacji, ale zapewnia domyślny dostęp do reguł allow, allowAllRequests i block. Używaj tej opcji, gdy to możliwe, aby uniknąć konieczności żądania pełnego dostępu do hostów.
"declarativeNetRequestFeedback"
Włącza funkcje debugowania dla rozpakowanych rozszerzeń, w szczególności getMatchedRules() i onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
Ostrzeżenie o wymaganych uprawnieniach nie jest wyświetlane w momencie instalacji, ale przed wykonaniem jakiegokolwiek działania na hoście musisz poprosić o uprawnienia. Ta opcja jest odpowiednia, gdy chcesz użyć deklaratywnych reguł sieciowych w rozszerzeniu, które ma już uprawnienia hosta, bez generowania dodatkowych ostrzeżeń.

Dostępność

Chrome 84 lub nowszy

Plik manifestu

Oprócz opisanych wcześniej uprawnień niektóre typy reguł, w szczególności reguły statycznej, wymagają zadeklarowania klucza pliku 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. (zauważ, że nazwa „Ruleset” nie pojawia się w pliku JSON pliku manifestu, ponieważ jest to tylko tablica). Statyczne zestawy reguł są opisane w dalszej części tego dokumentu.

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

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

Zasady i zestawy zasad

Aby korzystać z tego interfejsu API, określ co najmniej 1 zbiór zasad. Zestaw reguł zawiera tablicę reguł. Pojedyncza reguła wykonuje jedną z tych czynności:

  • Blokowanie żądania sieciowego.
  • Zaktualizuj schemat (z http na https).
  • Zapobieganie blokowaniu żądania przez odwrócenie wszystkich pasujących reguł blokujących.
  • przekierowywać żądania sieciowe.
  • modyfikować nagłówki żądań ani odpowiedzi;

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

Dynamiczna
Pozostają w pamięci przez sesje przeglądarki i uaktualnienia rozszerzenia. Można nimi zarządzać za pomocą JavaScriptu, gdy rozszerzenie jest używane.
Sesja
Usuwane po wyłączeniu przeglądarki i zainstalowaniu nowej wersji rozszerzenia. Zarządzanie regułami sesji odbywa się 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.

Reguły ograniczone do sesji i reguły dynamiczne

Regułami dotyczącymi sesji i regułami dynamicznymi zarządza się za pomocą kodu JavaScript, gdy rozszerzenie jest używane.

  • Reguły dynamiczne są zachowywane w sesjach przeglądarki i uaktualnieniach rozszerzeń.
  • Reguły sesji są usuwane, gdy przeglądarka jest zamykana i gdy instalowana jest nowa wersja rozszerzenia.

Każdy z tych typów reguł występuje tylko raz. Rozszerzenie może dynamicznie dodawać do nich reguły lub je z nich usuwać, wywołując metody updateDynamicRules() i updateSessionRules(), o ile nie zostaną przekroczone limity reguł. Informacje o limitach reguł znajdziesz w sekcji Limity reguł. Przykład znajdziesz w sekcji przykłady kodu.

Statyczne zestawy reguł

W przeciwieństwie do reguł dynamicznych i sesyjnych reguły statyczne są pakowane, instalowane i aktualizowane podczas instalowania lub aktualizowania rozszerzenia. Są one przechowywane w plikach reguł w formacie JSON, które są wskazywane rozszerzeniu za pomocą kluczy "declarative_net_request" i "rule_resources" jak opisano powyżej, a także w co najmniej jednym słowniku Ruleset. Słownik Ruleset zawiera ścieżkę do pliku reguł, identyfikator reguł zawartych w tym pliku oraz informację, czy reguły są włączone czy wyłączone. Te ostatnie są ważne, gdy włączasz lub wyłączasz reguły programowo.

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

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

przyspieszone sprawdzenie,

Zmiany w regułach statycznych mogą kwalifikować się do przyspieszonego sprawdzania. przyspieszona weryfikacja odpowiednich zmian.

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

Zarówno pojedyncze reguły statyczne, jak i całkowite zestawy reguł statycznych mogą być włączane i wyłączane w czasie wykonywania.

Zestaw włączonych reguł statycznych i reguł zbiorczych jest zachowywany w przypadku kolejnych sesji przeglądarki. Żadna z nich nie jest zachowywana w ramach aktualizacji rozszerzenia, co oznacza, że po aktualizacji dostępne są tylko reguły, które zostały w niej zachowane.

Ze względu na wydajność obowiązują też ograniczenia dotyczące liczby reguł i reguł zbiorczych, które można włączyć jednocześnie. Aby sprawdzić liczbę dodatkowych reguł, które można włączyć, zadzwoń pod numer getAvailableStaticRuleCount(). Informacje o limitach reguł znajdziesz w sekcji 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" słownika Ruleset. Maksymalna liczba wyłączonych reguł statycznych to 5000.

Aby włączyć lub wyłączyć statyczne rulesets, użyj wywołania updateEnabledRulesets(). Ta metoda przyjmuje obiekt UpdateRulesetOptions, który zawiera tablice identyfikatorów reguł do włączenia lub wyłączenia. Identyfikatory są definiowane za pomocą klucza "id" słownika Ruleset.

Tworzenie reguł

Bez względu na typ reguła zaczyna się od 4 pol, jak pokazano poniżej. Klucze "id" i "priority" przyjmują liczbę, natomiast klucze "action" i "condition" mogą zawierać kilka warunków blokowania i przekierowania. Podana niżej reguła blokuje wszystkie żądania skryptu pochodzące z adresu "foo.com" wysyłane do dowolnego adresu URL zawierającego podciąg "abc".

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

Dopasowanie adresu URL

Deklaratywna sieć żądań umożliwia dopasowywanie adresów URL za pomocą składni dopasowywania wzorca lub wyrażeń regularnych.

Składnia filtra adresów URL

Klucz "condition" reguły umożliwia kluczowi "urlFilter" działanie na adresy URL w określonej domenie. Wzory tworzysz za pomocą tokenów dopasowywania 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ż zawierać wyrażenia regularne. Wyświetl klucz "regexFilter". Informacje o limitach obowiązujących w przypadku tych warunków znajdziesz w artykule Reguły korzystające z wyrażeń regularnych.

Tworzenie prawidłowych warunków adresu URL

Podczas tworzenia reguł pamiętaj, aby zawsze dopasowywać całą domenę. W przeciwnym razie reguła może być zgodna w sytuacjach nieoczekiwanych. Na przykład przy użyciu składni dopasowania wzorca:

  • google.com nieprawidłowo pasuje do https://example.com/?param=google.com
  • ||google.com nieprawidłowo pasuje do https://google.company
  • https://www.google.com nieprawidłowo pasuje do 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 i żadnych subdomen.

Podobnie, aby zakotwiczyć wyrażenie regularne, użyj znaków ^ i /. Na przykład ^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 sieci.

Przed wysłaniem prośby

Przed wysłaniem żądania rozszerzenie może je zablokować lub przekierować (w tym uaktualnić protokół z HTTP na HTTPS) za pomocą reguły dopasowywania.

W przypadku każdego rozszerzenia przeglądarka określa listę reguł dopasowania. Reguły z działaniem modifyHeaders nie są tutaj uwzględnione, ponieważ zostaną przetworzone później. Dodatkowo reguły z warunkiem responseHeaders zostaną uwzględnione później (gdy będą dostępne nagłówki odpowiedzi) i nie zostaną uwzględnione.

Następnie w przypadku każdego rozszerzenia Chrome wybiera maksymalnie 1 kandydata na prośbę. Chrome znajduje pasującą regułę, sortując wszystkie pasujące reguły według priorytetu. Reguły o takim samym priorytecie są uporządkowane według działania (allow lub allowAllRequests > block > upgradeScheme > redirect).

Jeśli kandydatem jest reguła allow lub allowAllRequests albo jeśli żądanie zostało przesłane w ramach ramki, która została wcześniej dopasowana do reguły allowAllRequests o wyższym lub równym priorytecie z tego rozszerzenia, żądanie jest „dozwolone” i rozszerzenie nie ma na nie żadnego wpływu.

Jeśli więcej niż 1 rozszerzenie chce zablokować lub przekierować to żądanie, zostanie wybrane 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ń na serwer, są one aktualizowane na podstawie reguł dopasowania modifyHeaders.

W ramach jednego rozszerzenia Chrome tworzy listę modyfikacji do wykonania, znajdując wszystkie pasujące reguły modifyHeaders. Podobnie jak wcześniej uwzględniane są tylko reguły, które mają wyższy priorytet niż dowolna pasująca reguła allow lub allowAllRequests.

Reguły te są stosowane przez Chrome w takim porządku, że reguły z niedawno zainstalowanego rozszerzenia są zawsze sprawdzane przed regułami z starszego rozszerzenia. Dodatkowo reguły o wyższym priorytecie z jednego rozszerzenia są zawsze stosowane przed regułami o niższym priorytecie z tego samego rozszerzenia. Ważne, że nawet w przypadku rozszerzeń:

  • Jeśli reguła jest dołączana do nagłówka, reguły o niższym priorytecie mogą tylko dołączać się 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łączać do niego nagłówek. Nie można wprowadzać żadnych innych modyfikacji.
  • Jeśli reguła usuwa nagłówek, reguły o niższym priorytecie nie mogą 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 wartości action i priority oraz wykluczeniu reguł, które stały się zbędne z powodu pasującej reguły allow lub allowAllRequests (to odbywa się w identyczny sposób jak w sekcji „Przed żądaniem”), 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 na serwer, który otrzymał dane, np. treść żądania. Reguła blokowania lub przekierowywania 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 jest to obsługiwane przez stronę, która wysłała żądanie, które otrzymało odpowiedź o blokadzie, a Chrome wcześnie je anulował. W przypadku reguły przekierowania Chrome wysyła nowe żądanie do przekierowanego adresu URL. Zastanów się, czy takie działania są zgodne z oczekiwaniami użytkowników dotyczącymi prywatności w przypadku Twojego rozszerzenia.

Jeśli żądanie nie zostanie zablokowane ani przekierowane, Chrome zastosuje reguły modifyHeaders. Modyfikowanie nagłówków odpowiedzi działa tak samo jak w sekcji „Przed wysłaniem nagłówków żądań”. Zmiana nagłówków żądania nie ma żadnego wpływu, ponieważ żądanie zostało już wysłane.

Reguły bezpieczeństwa

Bezpieczne reguły to reguły z działaniem block, allow, allowAllRequests lub upgradeScheme. Te reguły podlegają zwiększonej kwocie limitu reguł dynamicznych.

Ograniczenia reguł

Ładowanie i sprawdzanie reguł w przeglądarce powoduje obciążenie wydajności, dlatego podczas korzystania z interfejsu API obowiązują pewne limity. Ograniczenia zależą od typu reguły, której używasz.

Reguły statyczne

Reguły statyczne to te, które są określone w plikach reguł zadeklarowanych w pliku manifestu. W ramach klucza pliku manifestu "rule_resources" rozszerzenie może zawierać maksymalnie 100 statycznych reguł, ale jednocześnie można włączyć tylko 50 z nich. Ten ostatni nazywa się MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Łącznie te zestawy reguł zawierają co najmniej 30 tys. reguł. Jest to tzw. GUARANTEED_MINIMUM_STATIC_RULES.

Liczba dostępnych reguł zależy od liczby reguł włączonych przez wszystkie rozszerzenia zainstalowane w przeglądarce użytkownika. Ten numer możesz znaleźć w czasie wykonywania kodu, wywołując funkcję getAvailableStaticRuleCount(). Przykład znajdziesz w sekcji przykłady kodu.

Reguły sesji

Rozszerzenie może zawierać maksymalnie 5000 reguł sesji. Jest on wyświetlany jako MAX_NUMBER_OF_SESSION_RULES.

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

Reguły dynamiczne

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

Od wersji 121 Chrome limit dostępnych reguł dynamicznych bezpiecznych został zwiększony do 30 tys. reguł i jest widoczny jako MAX_NUMBER_OF_DYNAMIC_RULES. Do limitu 5000 reguł dodanych w ramach limitu 5000 reguł będą również wliczane wszystkie reguły niebezpieczne.

W wersji Chrome 120 limit łącznej liczby reguł dynamicznych i sesji wynosił 5000.

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

Wyrażenia regularne mogą występować we wszystkich typach reguł, ale łączna liczba reguł z wyrażeniami regularnymi każdego typu nie może przekraczać 1000. Jest to tzw. MAX_NUMBER_OF_REGEX_RULES.

Dodatkowo po skompilowaniu każdy reguła musi mieć rozmiar mniejszy niż 2 KB. Jest to związane z skomplikowaniem reguły. Jeśli spróbujesz załadować regułę, która przekracza ten limit, pojawi się ostrzeżenie podobne do tego, 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 usługami

Deklaratywna operacja sieciowa dotyczy tylko żądań, które docierają do stosu sieciowego. Dotyczy to odpowiedzi z pamięci podręcznej HTTP, ale może nie obejmować odpowiedzi, które przechodzą przez moduł obsługi onfetch w usługach działających w tle. declarativeNetRequest nie wpływa na odpowiedzi wygenerowane przez usługę działającą w tle lub pobrane z CacheStorage, ale wpływa na wywołania fetch() wykonane w usługach działających w tle.

Zasoby dostępne w internecie

Reguła declarativeNetRequest nie może przekierowywać żądania zasobu publicznego do zasobu, do którego nie można uzyskać dostępu przez przeglądarkę. W przeciwnym razie pojawi się błąd. Dzieje się tak nawet wtedy, gdy wskazany zasób dostępny w internecie jest własnością rozszerzenia przekierowującego. Aby zadeklarować zasoby dla deklaratywnej funkcji netRequest, użyj tablicy "web_accessible_resources" w pliku manifestu.

Modyfikowanie 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ć funkcję updateDynamicRules(). Procedura dotycząca 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ł

Ten przykład pokazuje, jak włączać i wyłączać zestawy reguł, biorąc pod uwagę liczbę dostępnych i maksymalną liczbę włączonych statycznych zestawów reguł. Robisz to, gdy liczba potrzebnych reguł statycznych przekracza dozwoloną liczbę. Aby to zadziałało, niektóre reguły powinny być zainstalowane z niektórymi regułami wyłączonymi (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 ich sprawdzania możesz otworzyć reguły priorytetów w osobnym oknie.

Klucz „priorytet”.

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

Aby określić priorytet konkretnego adresu URL, sprawdź klucz "priority" (zdefiniowany przez dewelopera), klucz "action" i klucz "urlFilter". Te przykłady odnoszą się do przykładowego pliku reguł, który znajduje się poniżej.

Nawigacja do https://google.com
Ten adres URL obejmują 2 reguły: o identyfikatorach 1 i 4. Reguła o identyfikatorze 1 jest stosowana, ponieważ działania "block" mają wyższy priorytet niż działania "redirect". Pozostałe reguły nie mają zastosowania, ponieważ dotyczą dłuższych adresów URL.
Nawigacja do https://google.com/1234
Z powodu dłuższego adresu URL reguła o identyfikatorze 2 pasuje teraz do reguł o identyfikatorach 1 i 4. Reguła o identyfikatorze 2 jest stosowana, ponieważ "allow" ma wyższy priorytet niż "block" i "redirect".
Nawigacja do https://google.com/12345
Wszystkie 4 reguły pasują do tego adresu URL. Reguła o identyfikatorze 3 jest stosowana, ponieważ jej priorytet zdefiniowany przez dewelopera jest najwyż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

Przykład poniżej wymaga uprawnień hosta do *://*.example.com/*.

Z tego przykładu dowiesz się, jak przekierować żądanie z example.com na stronę w rozszerzeniu. Ścieżka rozszerzenia /a.jpg jest przekształcana w wartość chrome-extension://EXTENSION_ID/a.jpg, gdzie EXTENSION_ID to identyfikator rozszerzenia. Aby to zadziałało, w pliku manifestu należy zadeklarować /a.jpg jako zasob internetowy.

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

W tym przykładzie klucz "transform" służy do przekierowywania na subdomenę example.com. Korzysta on z ankiety nazwy domeny („||”) do przechwytywania żądań z dowolnym schematem z domeny example.com. Klucz "scheme" w kluczu "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"]
  }
}

W tym przykładzie 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 przecinki są ujęte w cudzysłowie, a grupa ujęta w nawiasy wybiera albo „abc”, albo „def”. Klucz "regexSubstitution" określa pierwsze dopasowanie wyrażenia regularnego z użyciem parametru „\1”. W tym przypadku parametr „abc” jest pobierany z adresu URL przekierowania i umieszczany w miejscu zastępowania.

{
  "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 tym przykładzie wszystkie pliki cookie są usuwane zarówno z głównego elementu ramki, jak i z podrzędnych elementów ramki.

{
  "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 strony pierwszej czy trzeciej w ramach ramki, w której zostało wysłane. Żądanie jest uważane za własne, jeśli pochodzi z tej samej domeny (eTLD+1) co element, z którego pochodzi.

Typ wyliczeniowy

„firstParty”
Żądanie sieci jest własne w ramach ramki, w której zostało wysłane.

„thirdParty”
Żądanie sieci jest zewnętrzne w ramach ramki, w której zostało utworzone.

ExtensionActionOptions

Chrome 88 lub nowszy

Właściwości

  • displayActionCountAsBadgeText

    logiczna opcjonalna

    Określa, czy liczba działań na stronie ma być automatycznie wyświetlana jako tekst plakietki rozszerzenia. To ustawienie jest zachowywane w kolejnych sesjach.

  • tabUpdate

    TabActionCountUpdate opcjonalnie

    Chrome 89 lub nowszy

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

GetDisabledRuleIdsOptions

Chrome 111 lub nowszy

Właściwości

  • rulesetId

    ciąg znaków

    Identyfikator odpowiadający statycznej Ruleset.

GetRulesFilter

Chrome 111 lub nowszy

Właściwości

  • ruleIds

    number[] opcjonalny

    Jeśli to pole jest zaznaczone, uwzględniane są tylko reguły z pasującymi identyfikatorami.

HeaderInfo

Chrome 128+

Właściwości

  • excludedValues

    string[] opcjonalnie

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

  • nagłówek

    ciąg znaków

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

  • wartości

    string[] opcjonalnie

    Jeśli jest określony, ten warunek jest spełniony, gdy wartość nagłówka pasuje do co najmniej jednego wzorca na tej liście. Ta funkcja obsługuje dopasowywanie wartości nagłówka z pominięciem wielkości liter oraz te konstrukcje:

    „*” : odpowiada dowolnej liczbie znaków.

    „?” : odpowiada 0 lub 1 znakowi.

    Znaków „*” i „?” można używać z ukośnikiem, np. „\*” i „\?”

HeaderOperation

Chrome 86 lub nowszy

Opis możliwych operacji dla 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ść dla określonego nagłówka, usuwając wszystkie istniejące nagłówki o tej samej nazwie.

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

IsRegexSupportedResult

Chrome 87 lub nowszy

Właściwości

  • isSupported

    wartość logiczna

  • reason

    UnsupportedRegexReason opcjonalny

    Określa, dlaczego wyrażenie regularne nie jest obsługiwane. Podawane tylko wtedy, gdy isSupported ma wartość Fałsz.

MatchedRule

Właściwości

  • ruleId

    liczba

    Identyfikator pasującej reguły.

  • rulesetId

    ciąg znaków

    Identyfikator Ruleset, do którego należy ta reguła. W przypadku reguły pochodzącej 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 dopasowania reguły. Sygnatury czasowe będą odpowiadać konwencji JavaScript dotyczącej czasu, czyli liczbie milisekund od początku epoki.

MatchedRuleInfoDebug

Właściwości

MatchedRulesFilter

Właściwości

  • minTimeStamp

    number opcjonalny

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

  • tabId

    number opcjonalny

    Jeśli jest określony, pasuje tylko do reguł na danej karcie. Dopasowuje reguły, które nie są powiązane z żadną aktywną kartą, jeśli wartość wynosi -1.

ModifyHeaderInfo

Chrome 86 lub nowszy

Właściwości

  • nagłówek

    ciąg znaków

    Nazwa nagłówka, który ma zostać zmodyfikowany.

  • operacja

    HeaderOperation

    Operacja do wykonania na nagłówku.

  • wartość

    ciąg znaków opcjonalny

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

QueryKeyValue

Właściwości

  • klucz

    ciąg znaków

  • replaceOnly

    logiczna opcjonalna

    Chrome 94 lub nowszy

    Jeśli wartość to Prawda, klucz zapytania jest zastępowany tylko wtedy, gdy jest już obecny. W przeciwnym razie klucz jest też 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ść zapytań do dodania lub zastąpienia.

  • removeParams

    string[] opcjonalnie

    Lista kluczy zapytań do usunięcia.

Redirect

Właściwości

  • extensionPath

    ciąg znaków opcjonalny

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

  • regexSubstitution

    ciąg znaków opcjonalny

    Wzorzec zastępowania w przypadku reguł, które określają wartość regexFilter. Pierwszym dopasowaniem regexFilter w adresie URL zostanie zastąpiony tym wzorcem. W sekcji regexSubstitution można używać znaków z backslashem (\1–\9) do wstawiania odpowiednich grup przechwytywania. \0 odnosi się do całego pasującego tekstu.

  • przekształcenie

    URLTransform opcjonalnie

    Przekształcenia adresów URL do wykonania.

  • URL

    ciąg znaków opcjonalny

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

RegexOptions

Chrome 87 lub nowszy

Właściwości

  • isCaseSensitive

    logiczna opcjonalna

    Określa, czy w przypadku parametru regex wielkość liter ma znaczenie. Wartość domyślna to prawda.

  • wyrażenie regularne

    ciąg znaków

    Wyrażenie regularne do sprawdzenia.

  • requireCapturing

    logiczna opcjonalna

    Określa, czy określona wartość regex wymaga przechwycenia. Przechwytywanie jest wymagane tylko w przypadku reguł przekierowań, które określają działanie regexSubstition. Wartość domyślna to fałsz.

RequestDetails

Właściwości

  • documentId

    ciąg znaków opcjonalny

    Chrome 106 lub nowszy

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

  • documentLifecycle

    DocumentLifecycle opcjonalny

    Chrome 106 lub nowszy

    cykl życia dokumentu ramki, jeśli prośba dotyczy ramki.

  • frameId

    liczba

    Wartość 0 wskazuje, że żądanie występuje w ramce głównej; dodatnia wartość wskazuje identyfikator podramki, w której występuje żądanie. Jeśli wczytany jest dokument z ramką (podrzędną) (type to main_frame lub sub_frame), frameId wskazuje identyfikator tej ramki, a nie identyfikator ramki zewnętrznej. Identyfikatory ramek są niepowtarzalne w obrębie karty.

  • frameType

    FrameType opcjonalny

    Chrome w wersji 106 lub nowszej

    Typ ramki, jeśli prośba dotyczy ramki.

  • inicjator

    ciąg znaków opcjonalny

    Źródło, z którego wysłano żądanie. Nie zmienia się ona 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

    ciąg znaków opcjonalny

    Chrome 106 lub nowszy

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

  • parentFrameId

    liczba

    Identyfikator ramki, która zawiera ramkę, z której wysłano żądanie. Jeśli nie ma ramki nadrzędnej, ustaw wartość –1.

  • requestId

    ciąg znaków

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

  • tabId

    liczba

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

  • Typ zasobu żądania.

  • URL

    ciąg znaków

    Adres URL żądania.

RequestMethod

Chrome 91 lub nowszy

Określa metodę żądania HTTP żądania sieciowego.

Typ wyliczeniowy

"connect"

"delete"

„get”

„head”

„options”

„patch”

„post”

„put”

"inne"

ResourceType

Określa typ zasobu żądania sieciowego.

Typ wyliczeniowy

"main_frame"

"sub_frame"

"stylesheet"

"script"

„image”

„font”

"object"

"xmlhttprequest"

„ping”

"csp_report"

"media"

"websocket"

"webtransport"

„webbundle”

"inne"

Rule

Właściwości

  • działanie

    RuleAction

    Działanie, które należy podjąć, gdy zostanie spełniony warunek tej reguły.

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

  • id

    liczba

    Identyfikator jednoznacznie identyfikujący regułę. Wymagany. Wartość musi być większa lub równa 1.

  • kampanii

    number opcjonalny

    Priorytet reguły. Domyślna wartość to 1. Jeśli jest podana, powinna być większa lub równa 1.

RuleAction

Właściwości

  • Przekieruj

    Przekierowanie opcjonalne

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

  • requestHeaders

    ModifyHeaderInfo[] opcjonalnie

    Chrome 86 lub nowszy

    Nagłówki żądania do zmodyfikowania. Dopuszczalne tylko wtedy, gdy parametr RuleActionType ma wartość „modifyHeaders”.

  • responseHeaders

    ModifyHeaderInfo[] opcjonalnie

    Chrome 86 lub nowszy

    Nagłówki odpowiedzi do zmodyfikowania w żądaniu. Dopuszczalne tylko wtedy, gdy parametr RuleActionType ma wartość „modifyHeaders”.

  • Typ działania.

RuleActionType

Określa rodzaj działania, które ma zostać wykonane, jeśli dany warunek reguły zostanie spełniony.

Typ wyliczeniowy

„block”
Zablokuj żądanie sieci.

„redirect”
Przekieruj żądanie sieci.

„allow”
Zezwól na żądanie sieci. Żądanie nie zostanie przechwycone, jeśli pasuje do reguły zezwalającej.

"upgradeScheme"
Przekształcanie schematu adresu URL żądania sieci na https, jeśli żądanie jest w formacie http lub ftp.

„modifyHeaders”
Zmienia nagłówki żądania/odpowiedzi z żądania sieciowego.

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

RuleCondition

Właściwości

  • domainType

    DomainType opcjonalnie

    Określa, czy żądanie sieci pochodzi z domeny własnej czy zewnętrznej. Jeśli nie zostanie podany, wszystkie prośby są akceptowane.

  • domeny

    string[] opcjonalnie

    Wycofane w wersji Chrome 101

    Użyj kolumny initiatorDomains

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

  • excludedDomains

    string[] opcjonalnie

    Wycofane w wersji Chrome 101

    Użyj kolumny excludedInitiatorDomains

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

  • excludedInitiatorDomains

    string[] opcjonalnie

    Chrome 101+

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

    Uwagi:

    • Dozwolone są też domeny podrzędne, np. „a.example.com”.
    • Wpisy mogą zawierać tylko znaki ASCII.
    • W przypadku domen z międzynarodowym domenem internetowym używaj kodowania Punycode.
    • Jest ona porównywana z inicjatorem żądania, a nie z adresem URL żądania.
    • Wykluczone są też subdomeny wymienionych domen.
  • excludedRequestDomains

    string[] opcjonalnie

    Chrome 101+

    Reguła nie będzie pasować do żądań sieci, jeśli domeny pasują do domen z listy excludedRequestDomains. Jeśli lista jest pusta lub pominięta, żadne domeny nie są wykluczane. Ma ona pierwszeństwo przed zasadą requestDomains.

    Uwagi:

    • Dozwolone są też domeny podrzędne, np. „a.example.com”.
    • Wpisy mogą zawierać tylko znaki ASCII.
    • W przypadku domen z międzynarodowym domenem internetowym używaj kodowania Punycode.
    • Wykluczone są też subdomeny wymienionych domen.
  • excludedRequestMethods

    RequestMethod[] opcjonalnie

    Chrome 91 lub nowszy

    Lista metod żądań, do których reguła nie pasuje. Należy podać tylko jedną z opcji: requestMethods lub excludedRequestMethods. Jeśli nie podasz żadnej z nich, zostaną dopasowane wszystkie metody żądania.

  • excludedResourceTypes

    ResourceType[] opcjonalnie

    Lista typów zasobów, do których reguła nie pasuje. Należy podać tylko jedną z opcji: resourceTypes lub excludedResourceTypes. Jeśli nie określisz żadnej z nich, zostaną zablokowane wszystkie typy zasobów z wyjątkiem „main_frame”.

  • excludedResponseHeaders

    HeaderInfo[] opcjonalnie

    Chrome 128+

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

  • excludedTabIds

    number[] opcjonalny

    Chrome 92 lub nowszy

    Lista tabs.Tab.id, do której reguła nie powinna pasować. Identyfikator tabs.TAB_ID_NONE wyklucza żądania, które nie pochodzą z karty. Obsługiwane są tylko reguły o zakresie sesji.

  • initiatorDomains

    string[] opcjonalnie

    Chrome 101+

    Reguła będzie pasować tylko do żądań sieci pochodzących z listy initiatorDomains. Jeśli lista jest pominięta, reguła jest stosowana do żądań ze wszystkich domen. Pusty list jest niedozwolony.

    Uwagi:

    • Dozwolone są też domeny podrzędne, np. „a.example.com”.
    • Wpisy mogą zawierać tylko znaki ASCII.
    • W przypadku domen z międzynarodowym domenem internetowym używaj kodowania Punycode.
    • Jest ona porównywana z inicjatorem żądania, a nie z adresem URL żądania.
    • Dopasowywane są też subdomeny wymienionych domen.
  • isUrlFilterCaseSensitive

    logiczna opcjonalna

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

  • regexFilter

    ciąg znaków opcjonalny

    Wyrażenie regularne do dopasowania do adresu URL żądania sieci. Jest ona zgodna ze składnią RE2.

    Uwaga: można użyć tylko jednej z opcji urlFilter lub regexFilter.

    Uwaga: regexFilter musi składać się tylko z znaków ASCII. Jest on dopasowywany do adresu URL, w którym host jest zakodowany w formacie punycode (w przypadku domen z wieloma językami), a inne znaki inne niż ASCII są zakodowane w formacie URL w standardzie UTF-8.

  • requestDomains

    string[] opcjonalnie

    Chrome 101+

    Reguła będzie pasować do żądań sieci tylko wtedy, gdy domena będzie pasować do jednej z domen na liście requestDomains. Jeśli lista jest pominięta, reguła jest stosowana do żądań ze wszystkich domen. Pusty list jest niedozwolony.

    Uwagi:

    • Dozwolone są też domeny podrzędne, np. „a.example.com”.
    • Wpisy mogą zawierać tylko znaki ASCII.
    • W przypadku domen z międzynarodowym domenem internetowym używaj kodowania Punycode.
    • Dopasowywane są też subdomeny wymienionych domen.
  • requestMethods

    RequestMethod[] opcjonalnie

    Chrome 91 lub nowszy

    Lista metod żądań HTTP, do których może pasować reguła. Pusty list jest niedozwolony.

    Uwaga: podanie warunku reguły requestMethods spowoduje również wykluczenie żądań innych niż HTTP(s), podczas gdy podanie warunku excludedRequestMethods nie spowoduje takiego wykluczenia.

  • resourceTypes

    ResourceType[] opcjonalnie

    Lista typów zasobów, do których może pasować reguła. Pusty list jest niedozwolony.

    Uwaga: musisz to określić w przypadku reguł allowAllRequests i możesz uwzględnić tylko typy zasobów sub_frame i main_frame.

  • responseHeaders

    HeaderInfo[] opcjonalnie

    Chrome 128+

    Reguła pasuje, jeśli żądanie pasuje do dowolnego warunku nagłówka odpowiedzi na tej liście (jeśli jest podany).

  • tabIds

    number[] opcjonalny

    Chrome 92 lub nowszy

    Lista tabs.Tab.id, do której ma pasować reguła. Identyfikator tabs.TAB_ID_NONE pasuje do żądań, które nie pochodzą z karty. Pusty list jest niedozwolony. Obsługiwane są tylko reguły o zakresie sesji.

  • urlFilter

    ciąg znaków opcjonalny

    Wzorzec porównywany z adresem URL żądania sieci. Obsługiwane konstrukcje:

    „*”: symbol wieloznaczny odpowiadający dowolnej liczbie znaków.

    '|' : lewy/prawy punkt zakotwiczenia: jeśli jest używany na obu końcach 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 domeny (poddomeny) adresu URL.

    '^' : znak separatora: pasuje do wszystkiego oprócz litery, cyfry lub jednego z tych znaków: _, -, . lub %. Dopasowuje się też do końca adresu URL.

    Dlatego urlFilter składa się z tych części: (opcjonalna lewa/ankra nazwy domeny) + wzorzec + (opcjonalna prawa ankra).

    Jeśli nie podasz adresu URL, zostaną dopasowane wszystkie adresy URL. Pusty ciąg znaków jest niedozwolony.

    Wzór zaczynający się od ||* jest niedozwolony. Zamiast tego użyj *.

    Uwaga: można użyć tylko jednej z opcji urlFilter lub regexFilter.

    Uwaga: urlFilter musi składać się tylko z znaków ASCII. Jest on dopasowywany do adresu URL, w którym host jest zakodowany w formacie punycode (w przypadku domen z wieloma językami), a inne znaki inne niż ASCII są zakodowane w formacie URL w standardzie UTF-8. Jeśli np. adres URL żądania to http://abc.рф?q=ф, 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 jednoznacznie identyfikujący zestaw reguł. Identyfikatory zaczynające się od „_” są zarezerwowane do użytku wewnętrznego.

  • ścieżka

    ciąg znaków

    Ścieżka do 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ą zwiększa się liczbę działań na karcie. Wartości ujemne zmniejszają liczbę.

  • tabId

    liczba

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

TestMatchOutcomeResult

Chrome w wersji 103 lub nowszej

Właściwości

  • matchedRules

    MatchedRule[]

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

TestMatchRequestDetails

Chrome w wersji 103 lub nowszej

Właściwości

  • inicjator

    ciąg znaków opcjonalny

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

  • method

    RequestMethod opcjonalny

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

  • responseHeaders

    object opcjonalne

    Chrome 129 lub nowszy

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

  • tabId

    number opcjonalny

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

  • Typ zasobu hipotetycznego żądania.

  • URL

    ciąg znaków

    Adres URL hipotetycznego żądania.

UnsupportedRegexReason

Chrome 87 lub nowszy

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 używa funkcji niedostępnych w składni RE2.

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

UpdateRuleOptions

Chrome 87 lub nowszy

Właściwości

  • addRules

    Reguła[] opcjonalna

    Reguły do dodania.

  • removeRuleIds

    number[] opcjonalny

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

UpdateRulesetOptions

Chrome 87 lub nowszy

Właściwości

  • disableRulesetIds

    string[] opcjonalnie

    Zestaw identyfikatorów odpowiadających statycznej wersji Ruleset, która powinna zostać wyłączona.

  • enableRulesetIds

    string[] opcjonalnie

    Zestaw identyfikatorów odpowiadających statycznej liście Ruleset, która powinna być włączona.

UpdateStaticRulesOptions

Chrome 111 lub nowszy

Właściwości

  • disableRuleIds

    number[] opcjonalny

    Zestaw identyfikatorów odpowiadających regułom w Ruleset, które chcesz wyłączyć.

  • enableRuleIds

    number[] opcjonalny

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

  • rulesetId

    ciąg znaków

    Identyfikator odpowiadający statycznej Ruleset.

URLTransform

Właściwości

  • fragment

    ciąg znaków opcjonalny

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

  • host

    ciąg znaków opcjonalny

    Nowy gospodarz dla prośby.

  • hasło

    ciąg znaków opcjonalny

    Nowe hasło do prośby.

  • ścieżka

    ciąg znaków opcjonalny

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

  • port

    ciąg znaków opcjonalny

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

  • zapytanie

    ciąg znaków opcjonalny

    Nowe zapytanie dotyczące prośby. Może być pusty (w takim przypadku istniejące zapytanie zostanie usunięte) lub zaczynać się od znaku „?”.

  • queryTransform

    QueryTransform opcjonalnie

    Dodawaj, usuwaj i zastępuj pary klucz-wartość zapytań.

  • schemat

    ciąg znaków opcjonalny

    Nowy schemat prośby. Dozwolone wartości to „http”, „https”, „ftp” i „chrome-extension”.

  • nazwa użytkownika

    ciąg znaków opcjonalny

    Nowa nazwa użytkownika dla prośby.

Właściwości

DYNAMIC_RULESET_ID

Identyfikator zbioru 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 zostaną odrzucone od razu i ustawione jako runtime.lastError. Uwaga: wywołania getMatchedRules związane z działaniem użytkownika nie są objęte limitem.

Wartość

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 lub nowszy

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

Wartość

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Liczba wywołań funkcji getMatchedRules w okresie GETMATCHEDRULES_QUOTA_INTERVAL.

Wartość

20

MAX_NUMBER_OF_DYNAMIC_RULES

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

Wartość

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 lub nowszy

Maksymalna liczba statycznych Rulesets, które rozszerzenie może 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 w przypadku zestawu reguł dynamicznych i reguł określonych w pliku zasobów reguł.

Wartość

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120+

Maksymalna liczba reguł ograniczonych do 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+

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

Wartość

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120+

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

Wartość

5000

SESSION_RULESET_ID

Chrome 90+

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

Wartość

"_session"

Metody

getAvailableStaticRuleCount()

Obietnica Chrome 89 i nowsze wersje 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

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

Parametry

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (count: number) => void

    • liczba

      liczba

Zwroty

  • Obietnice<number>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getDisabledRuleIds()

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

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

Parametry

  • Określa zestaw reguł, do którego wysyłane jest zapytanie.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      number[]

Zwroty

  • Obietkwarzecze<number[]>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getDynamicRules()

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

Zwraca bieżący zestaw reguł dynamicznych dotyczących rozszerzenia. Użytkownicy mogą opcjonalnie filtrować listę pobrany reguł, podając filter.

Parametry

  • filtr

    GetRulesFilter opcjonalnie

    Chrome 111 lub nowszy

    Obiekt do filtrowania listy pobranych reguł.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (rules: Rule[]) => void

Zwroty

  • Obietnica<Reguła[]>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getEnabledRulesets()

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

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

Parametry

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (rulesetIds: string[]) => void

    • rulesetIds

      string[]

Zwroty

  • Promise<string[]>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getMatchedRules()

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

Zwraca wszystkie reguły dopasowane do rozszerzenia. Rozmówcy mogą opcjonalnie filtrować listę dopasowanych reguł, podają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 niezwiązane z aktywnym dokumentem, które zostały dopasowane ponad 5 minut temu, nie zostaną zwrócone.

Parametry

Zwroty

  • Chrome 91 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

getSessionRules()

Obietnice Chrome 90+ 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

Zwraca bieżący zestaw reguł ograniczonych do sesji dla rozszerzenia. Użytkownicy mogą opcjonalnie filtrować listę pobrany reguł, podając filter.

Parametry

  • filtr

    GetRulesFilter opcjonalnie

    Chrome 111 lub nowszy

    Obiekt do filtrowania listy pobranych reguł.

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    (rules: Rule[]) => void

Zwroty

  • Obietnica<Reguła[]>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

isRegexSupported()

Obietnice Chrome 87 i nowsze wersje 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

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

Parametry

Zwroty

  • Chrome 91 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

setExtensionActionOptions()

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

Określa, czy liczba działań dla kart powinna być wyświetlana jako tekst plakietki działania rozszerzenia, oraz umożliwia zwiększanie tej liczby.

Parametry

  • wywołanie zwrotne

    function opcjonalny

    Chrome 89 lub nowszy

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

testMatchOutcome()

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

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

Parametry

Zwroty

  • Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

updateDynamicRules()

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

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

  • Ta aktualizacja jest wykonywana jako pojedyncza operacja atomowa: albo dodawane i usuwane są wszystkie określone reguły, albo zwracany jest błąd.
  • Te reguły są zachowywane w przypadku kolejnych sesji przeglądarki i aktualizacji rozszerzeń.
  • Za pomocą tej funkcji nie można usunąć reguł statycznych określonych w ramach pakietu 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

  • Chrome 87 lub nowszy
  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

updateEnabledRulesets()

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

Aktualizuje zestaw włączonych statycznych zestawów reguł dla rozszerzenia. Najpierw usuwane są reguły z identyfikatorami podanymi w sekcji options.disableRulesetIds, a potem dodawane są reguły z sekcji options.enableRulesetIds. Pamiętaj, że zestaw włączonych statycznych zestawów reguł jest utrwalany w całych sesjach, ale nie w przypadku aktualizacji rozszerzeń. Oznacza to, że klucz manifestu rule_resources określa zestaw włączonych statycznych zestawów reguł w każdej aktualizacji rozszerzenia.

Parametry

  • Chrome 87 lub nowszy
  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

updateSessionRules()

Obietnice Chrome 90+ 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
)

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

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

Parametry

  • wywołanie zwrotne

    function opcjonalny

    Parametr callback ma postać:

    () => void

Zwroty

  • Obietnica<void>

    Chrome 91 lub nowszy

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

updateStaticRules()

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

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

Parametry

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w pliku manifestu w wersji 3 i późniejszych, ale wywołania zwrotne są dostępne ze względu na zgodność wsteczną. Nie możesz używać obu w tym samym wywołaniu funkcji. Obiet na obietnice zwracany jest z tym samym typem, który jest przekazywany do funkcji zwracającej wywołanie zwrotne.

Wydarzenia

onRuleMatchedDebug

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

Uruchamiane, gdy reguła zostanie dopasowana do żądania. Dostępne tylko w rozpakowanych rozszerzeniach z uprawnieniem "declarativeNetRequestFeedback", ponieważ jest ono przeznaczone tylko do debugowania.

Parametry