chrome.declarativeNetRequest

Opis

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

Uprawnienia

declarativeNetRequest
declarativeNetRequestWithHostAccess

„declarativeNetRequest” i „declarativeNetRequestWithHostAccess” uprawnienia dają te same możliwości. Różnica między nimi polega na tym, że uprawnienia którą poproszono lub przyznano.

"declarativeNetRequest"
Wyświetla ostrzeżenie o uprawnieniach podczas instalacji, ale daje niejawny dostęp do: Reguły allow, allowAllRequests i block. Używaj go, gdy to możliwe, aby uniknąć które wymagają pełnego dostępu do hostów.
"declarativeNetRequestFeedback"
Udostępnia funkcje debugowania dotyczące rozpakowanych rozszerzeń, w szczególności getMatchedRules() i onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
Ostrzeżenie o uprawnieniach nie jest wyświetlane podczas instalacji, ale musisz poprosić o dostęp do hosta , zanim będzie można wykonać jakiekolwiek czynności na hoście. Ten jest odpowiednie, gdy chcesz użyć deklaratywnych reguł żądań netto w rozszerzenie, które ma już uprawnienia hosta bez generowania dodatkowych ostrzeżeniami.

Dostępność

Chrome 84 i nowsze .

Plik manifestu

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

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

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

Reguły i zestawy reguł

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

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

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

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

Zestawy reguł dynamicznych i ograniczonych do sesji

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

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

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

Statyczne zestawy reguł

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

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

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

Przyspieszona weryfikacja

Zmiany w statycznych zestawach reguł mogą kwalifikować się do przyspieszonego sprawdzenia. Zobacz przyspieszone sprawdzanie kwalifikujących się zmian.

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

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

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

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

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

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

Utwórz reguły

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

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

Dopasowywanie adresów URL

Deklaratywne żądanie netto umożliwia dopasowywanie adresów URL do wzorca pasujących do siebie składni lub wyrażeń regularnych.

Składnia filtra adresów URL

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

urlFilter Odpowiada Nie pasuje
"abc" https://abcd.com
https://example.com/abcd		 https://ab.com
"abc*d" https://abcd.com
https://example.com/abcxyzd		 https://abc.com
"||a.example.com" https://a.example.com/
https://b.a.example.com/xyz
https://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ż używać wyrażeń regularnych. Zobacz "regexFilter". Aby dowiedzieć się więcej na temat: mające zastosowanie do tych warunków, zobacz reguły używające wyrażeń regularnych.

Określanie dobrych warunków adresu URL

Zachowaj ostrożność, tworząc reguły, które zawsze pasują do całej domeny. W przeciwnym razie może pasować w nieoczekiwanych sytuacjach. Na przykład podczas korzystania z funkcji składnia dopasowania do wzorca:

  • google.com nie pasuje do wyrażenia https://example.com/?param=google.com
  • ||google.com nie pasuje do wyrażenia https://google.company
  • https://www.google.com nie pasuje do wyrażenia https://example.com/?param=https://www.google.com

Co warto wykorzystać:

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

W podobny sposób możesz zakotwiczyć wyrażenie regularne za pomocą znaków ^ i /. Dla: przykładu, ^https:\/\/www\.google\.com\/ pasuje do dowolnej ścieżki w https://www.google.com.

Ocena reguł

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

Przed wysłaniem prośby

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

Dla każdego rozszerzenia przeglądarka określa listę reguł dopasowania. Reguły z działaniem modifyHeaders nie są tu uwzględnione, ponieważ będą obsługiwane później. Poza tym reguły z warunkem responseHeaders będą rozpatrywane później (gdy będą dostępne nagłówki odpowiedzi) i nie zostaną uwzględnione.

Następnie dla każdego rozszerzenia Chrome wybiera maksymalnie jednego 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 to reguła allow lub allowAllRequests albo ramka, której dotyczy żądanie, pasuje wcześniej do reguły allowAllRequests o wyższym lub takim samym priorytecie z tego rozszerzenia, żądanie jest „dozwolone” i nie będzie miało żadnego wpływu na prośbę.

Jeśli więcej niż jedno rozszerzenie chce zablokować lub przekierować tę prośbę, 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 tę, która pochodzi 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 pasujących reguł modifyHeaders.

W ramach pojedynczego rozszerzenia Chrome tworzy listę modyfikacji, które należy wprowadzić, znajdując wszystkie pasujące reguły modifyHeaders. Podobnie jak wcześniej uwzględniane są tylko te reguły, które mają wyższy priorytet niż pasujące reguły allow lub allowAllRequests.

Chrome stosuje te reguły w takiej kolejności, że reguły z nowo zainstalowanego rozszerzenia są zawsze sprawdzane przed regułami ze starszego rozszerzenia. Poza tym reguły o wyższym priorytecie z jednego rozszerzenia są zawsze stosowane przed regułami o niższym priorytecie z tego samego rozszerzenia. W szczególności – nawet w przypadku różnych rozszerzeń:

  • Jeśli reguła jest dołączana do nagłówka, to reguły o niższym priorytecie mogą dołączać tylko do tego nagłówka. Operacje ustawiania i usuwania nie są dozwolone.
  • Jeśli reguła ustawia nagłówek, do tego nagłówka mogą być dołączane tylko reguły o niższym priorytecie z tego samego rozszerzenia. Inne modyfikacje nie są dozwolone.
  • 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 warunkem responseHeaders.

Po posortowaniu tych reguł według reguł action i priority oraz wykluczeniu wszystkich reguł, które stały się zbędne przez pasującą regułę allow lub allowAllRequests (dzieje się tak samo jak w przypadku kroków opisanych w sekcji „Przed żądaniem”), Chrome może zablokować lub przekierować żądanie w imieniu rozszerzenia.

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 jest to obsługiwane przez stronę, która wysłała żądanie, a Chrome przedwcześnie je zakończyła. W przypadku reguły przekierowania Chrome wysyła nowe żądanie na adres URL przekierowania. Zastanów się, czy te działania spełniają oczekiwania dotyczące ochrony prywatności w przypadku Twojego rozszerzenia.

Jeśli żądanie nie zostanie zablokowane ani przekierowane, Chrome zastosuje wszystkie reguły modifyHeaders. Stosowanie modyfikacji nagłówków odpowiedzi działa w sposób opisany w sekcji „Przed wysłaniem nagłówków żądań”. Zmodyfikowanie nagłówków żądań nic nie da, bo żądanie zostało już wysłane.

Bezpieczne reguły

Bezpieczne reguły to reguły o działaniu block, allow, allowAllRequests lub upgradeScheme. Reguły te podlegają limit reguł dynamicznych.

Ograniczenia reguł

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

Reguły statyczne

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

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

Reguły sesji

Rozszerzenie może mieć maksymalnie 5000 reguł sesji. Jest ona narażona na MAX_NUMBER_OF_SESSION_RULES

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

Reguły dynamiczne

Rozszerzenie może mieć co najmniej 5000 reguł dynamicznych. Jest ona narażona na MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Od wersji Chrome 121 obowiązuje większy limit 30 tys. reguł dla bezpiecznych reguł dynamicznych, są widoczne jako MAX_NUMBER_OF_DYNAMIC_RULES. Dowolne niebezpieczne reguły dodane do limitu do 5000 również będą wliczane do tego limitu.

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

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

Wyrażenia regularne mogą być używane w przypadku wszystkich typów reguł. jednak łączna liczba reguł wyrażeń regularnych każdego typu nie może przekroczyć 1000. Jest to tzw. MAX_NUMBER_OF_REGEX_RULES.

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

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

Interakcje z mechanizmami Service Worker

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

Zasoby dostępne przez internet

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

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

Zaktualizuj reguły dynamiczne

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

// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

Zaktualizuj statyczne zestawy reguł

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

async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
  // Create the options structure for the call to updateEnabledRulesets()
  let options = { enableRulesetIds: enableRulesetIds }
  // Get the number of enabled static rules
  const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();
  // Compare rule counts to determine if anything needs to be disabled so that
  // new rules can be enabled
  const proposedCount = enableRulesetIds.length;
  if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}

Przykłady reguł

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

„Priorytet”, klawisz

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

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

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

Przekierowania

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

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

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

Poniższy kod służy do przekierowania do subdomeny example.com za pomocą klucza "transform". Wykorzystuje kotwicę nazwy domeny („||”) do przechwytywania żądań z dowolnym schematem z example.com. Klucz "scheme" w zasadzie "transform" określa, że przekierowania do subdomeny zawsze używają przedrostka „https”.

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

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

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

Nagłówki

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

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

Typy

DomainType

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

Typ wyliczeniowy

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

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

ExtensionActionOptions

Chrome 88 i nowsze .

Właściwości

  • displayActionCountAsBadgeText

    Wartość logiczna opcjonalna

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

  • tabUpdate

    Opcjonalne TabActionCountUpdate

    Chrome w wersji 89 lub nowszej .

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

GetDisabledRuleIdsOptions

Chrome w wersji 111 lub nowszej .

Właściwości

  • rulesetId

    ciąg znaków

    Identyfikator odpowiadający statycznemu elementowi Ruleset.

GetRulesFilter

Chrome w wersji 111 lub nowszej .

Właściwości

  • ruleIds

    liczba[] opcjonalnie

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

HeaderInfo

Chrome 128 i nowsze wersje .

Właściwości

  • excludedValues

    string[] opcjonalnie

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

  • nagłówek

    ciąg znaków

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

  • wartości

    string[] opcjonalnie

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

    '*' : odpowiada dowolnej liczbie znaków.

    '?' : dopasowuje zero lub jeden znak.

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

HeaderOperation

Chrome 86 i nowsze .

Opisuje możliwe operacje polecenia „modifyHeaders” .

Typ wyliczeniowy

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

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

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

IsRegexSupportedResult

Chrome 87 i nowsze .

Właściwości

  • isSupported

    wartość logiczna

  • powód

    UnsupportedRegexReason opcjonalny

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

MatchedRule

Właściwości

  • ruleId

    liczba

    Identyfikator pasującej reguły.

  • rulesetId

    ciąg znaków

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

MatchedRuleInfo

Właściwości

  • reguła

    MatchedRule

  • tabId

    liczba

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

  • timeStamp

    liczba

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

MatchedRuleInfoDebug

Właściwości

  • żądanie

    RequestDetails

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

  • reguła

    MatchedRule

MatchedRulesFilter

Właściwości

  • minTimeStamp

    liczba opcjonalnie

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

  • tabId

    liczba opcjonalnie

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

ModifyHeaderInfo

Chrome 86 i nowsze .

Właściwości

  • nagłówek

    ciąg znaków

    Nazwa nagłówka do zmodyfikowania.

  • operacja

    HeaderOperation

    Operacja do wykonania na nagłówku.

  • wartość

    ciąg znaków opcjonalny

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

QueryKeyValue

Właściwości

  • klucz

    ciąg znaków

  • replaceOnly

    Wartość logiczna opcjonalna

    Chrome w wersji 94 lub nowszej .

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

  • wartość

    ciąg znaków

QueryTransform

Właściwości

  • addOrReplaceParams

    QueryKeyValue[] opcjonalny

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

  • removeParams

    string[] opcjonalnie

    Lista kluczy zapytania do usunięcia.

Redirect

Właściwości

  • extensionPath

    ciąg znaków opcjonalny

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

  • regexSubstitution

    ciąg znaków opcjonalny

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

  • przekształcenie

    Opcjonalny URLTransform

    Przekształcenia adresów URL do wykonania.

  • URL

    ciąg znaków opcjonalny

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

RegexOptions

Chrome 87 i nowsze .

Właściwości

  • isCaseSensitive

    Wartość logiczna opcjonalna

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

  • wyrażenie regularne

    ciąg znaków

    Wyrażenie regularne do sprawdzenia.

  • requireCapturing

    Wartość logiczna opcjonalna

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

RequestDetails

Właściwości

  • documentId

    ciąg znaków opcjonalny

    Chrome 106 lub nowszy .

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

  • documentLifecycle

    Opcjonalny DocumentLifecycle

    Chrome 106 lub nowszy .

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

  • frameId

    liczba

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

  • frameType

    Opcjonalny FrameType

    Chrome 106 lub nowszy .

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

  • inicjator

    ciąg znaków opcjonalny

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

  • method

    ciąg znaków

    Standardowa metoda HTTP.

  • parentDocumentId

    ciąg znaków opcjonalny

    Chrome 106 lub nowszy .

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

  • parentFrameId

    liczba

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

  • requestId

    ciąg znaków

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

  • tabId

    liczba

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

  • Typ zasobu żądania.

  • URL

    ciąg znaków

    Adres URL żądania.

RequestMethod

Chrome w wersji 91 lub nowszej .

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

Typ wyliczeniowy

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"inna"

ResourceType

Opisuje typ zasobu żądania sieciowego.

Typ wyliczeniowy

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"inna"

Rule

Właściwości

  • działanie

    RuleAction

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

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

  • id

    liczba

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

  • kampanii

    liczba opcjonalnie

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

RuleAction

Właściwości

  • Przekieruj

    Przekierowanie opcjonalne

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

  • requestHeaders

    ModifyHeaderInfo[] opcjonalny

    Chrome 86 i nowsze .

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

  • responseHeaders

    ModifyHeaderInfo[] opcjonalny

    Chrome 86 i nowsze .

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

  • Typ działania do wykonania.

RuleActionType

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

Typ wyliczeniowy

"block"
Zablokuj żądanie sieciowe.

"redirect"
Przekieruj żądanie sieciowe.

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

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

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

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

RuleCondition

Właściwości

  • domainType

    Opcjonalny DomainType

    Określa, czy żądanie sieciowe jest w domenie, z której pochodzi, jest żądaniem należącym do użytkownika czy od firmy zewnętrznej. Jeśli go pominiesz, wszystkie żądania zostaną zaakceptowane.

  • domeny

    string[] opcjonalnie

    Wycofane od Chrome 101

    Zamiast tego użyj initiatorDomains

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

  • excludedDomains

    string[] opcjonalnie

    Wycofane od Chrome 101

    Zamiast tego użyj excludedInitiatorDomains

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

  • excludedInitiatorDomains

    string[] opcjonalnie

    Chrome 101 i nowsze wersje .

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

    Uwagi:

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

    string[] opcjonalnie

    Chrome 101 i nowsze wersje .

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

    Uwagi:

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

    RequestMethod[] opcjonalny

    Chrome w wersji 91 lub nowszej .

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

  • excludedResourceTypes

    ResourceType[] opcjonalny

    Lista typów zasobów, które nie pasują do reguły. Należy określić tylko jedną z tych właściwości: resourceTypes lub excludedResourceTypes. Jeśli nie określono żadnego z nich, wszystkie typy zasobów oprócz „main_frame” są zablokowane.

  • excludedResponseHeaders

    HeaderInfo[] opcjonalny

    Chrome 128 i nowsze wersje .

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

  • excludedTabIds

    liczba[] opcjonalnie

    Chrome w wersji 92 lub nowszej .

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

  • initiatorDomains

    string[] opcjonalnie

    Chrome 101 i nowsze wersje .

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

    Uwagi:

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

    Wartość logiczna opcjonalna

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

  • regexFilter

    ciąg znaków opcjonalny

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

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

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

  • requestDomains

    string[] opcjonalnie

    Chrome 101 i nowsze wersje .

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

    Uwagi:

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

    RequestMethod[] opcjonalny

    Chrome w wersji 91 lub nowszej .

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

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

  • resourceTypes

    ResourceType[] opcjonalny

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

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

  • responseHeaders

    HeaderInfo[] opcjonalny

    Chrome 128 i nowsze wersje .

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

  • tabIds

    liczba[] opcjonalnie

    Chrome w wersji 92 lub nowszej .

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

  • urlFilter

    ciąg znaków opcjonalny

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

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

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

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

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

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

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

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

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

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

Ruleset

Właściwości

  • włączone

    wartość logiczna

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

  • id

    ciąg znaków

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

  • ścieżka

    ciąg znaków

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

RulesMatchedDetails

Właściwości

TabActionCountUpdate

Chrome w wersji 89 lub nowszej .

Właściwości

  • Zwiększ

    liczba

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

  • tabId

    liczba

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

TestMatchOutcomeResult

Chrome 103 i nowsze wersje .

Właściwości

  • matchedRules

    MatchedRule[]

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

TestMatchRequestDetails

Chrome 103 i nowsze wersje .

Właściwości

  • inicjator

    ciąg znaków opcjonalny

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

  • method

    Opcjonalny RequestMethod

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

  • responseHeaders

    obiekt opcjonalny

    Oczekujący

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

  • tabId

    liczba opcjonalnie

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

  • Typ zasobu hipotetycznego żądania.

  • URL

    ciąg znaków

    Adres URL hipotetycznego żądania.

UnsupportedRegexReason

Chrome 87 i nowsze .

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

Typ wyliczeniowy

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

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

UpdateRuleOptions

Chrome 87 i nowsze .

Właściwości

  • addRules

    Reguła[] opcjonalna

    Reguły do dodania.

  • removeRuleIds

    liczba[] opcjonalnie

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

UpdateRulesetOptions

Chrome 87 i nowsze .

Właściwości

  • disableRulesetIds

    string[] opcjonalnie

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

  • enableRulesetIds

    string[] opcjonalnie

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

UpdateStaticRulesOptions

Chrome w wersji 111 lub nowszej .

Właściwości

  • disableRuleIds

    liczba[] opcjonalnie

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

  • enableRuleIds

    liczba[] opcjonalnie

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

  • rulesetId

    ciąg znaków

    Identyfikator odpowiadający statycznemu elementowi Ruleset.

URLTransform

Właściwości

  • fragment

    ciąg znaków opcjonalny

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

  • host

    ciąg znaków opcjonalny

    Nowy host dla żądania.

  • hasło

    ciąg znaków opcjonalny

    Nowe hasło dla żądania.

  • ścieżka

    ciąg znaków opcjonalny

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

  • port

    ciąg znaków opcjonalny

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

  • zapytanie

    ciąg znaków opcjonalny

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

  • queryTransform

    Opcjonalny QueryTransform

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

  • schemat

    ciąg znaków opcjonalny

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

  • nazwa użytkownika

    ciąg znaków opcjonalny

    Nowa nazwa użytkownika dla prośby.

Właściwości

DYNAMIC_RULESET_ID

Identyfikator zestawu reguł dynamicznych dodanych przez rozszerzenie.

Wartość

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

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

Wartość

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome w wersji 89 lub nowszej .

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

Wartość

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Liczba wywołań funkcji getMatchedRules w okresie GETMATCHEDRULES_QUOTA_INTERVAL wynosi

Wartość

20

MAX_NUMBER_OF_DYNAMIC_RULES

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

Wartość

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome w wersji 94 lub nowszej .

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

Wartość

50

MAX_NUMBER_OF_REGEX_RULES

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

Wartość

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome w wersji 120 lub nowszej .

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

Wartość

5000

MAX_NUMBER_OF_STATIC_RULESETS

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

Wartość

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome w wersji 120 lub nowszej .

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

Wartość

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome w wersji 120 lub nowszej .

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

Wartość

5000

SESSION_RULESET_ID

Chrome w wersji 90 lub nowszej .

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

Wartość

"_session"

Metody

getAvailableStaticRuleCount()

Obietnica Chrome w wersji 89 lub nowszej 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

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

Parametry

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (count: number) => void

    • liczba

      liczba

Zwroty

  • Promise<number>

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getDisabledRuleIds()

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

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

Parametry

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

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      liczba[]

Zwroty

  • Obietnica<number[]>

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getDynamicRules()

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

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

Parametry

  • filtr

    Opcjonalne GetRulesFilter

    Chrome w wersji 111 lub nowszej .

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

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (rules: Rule[]) => void

Zwroty

  • Obietnica<Reguła[]>

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getEnabledRulesets()

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

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

Parametry

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (rulesetIds: string[]) => void

    • rulesetIds

      ciąg znaków[]

Zwroty

  • Promise&lt;string[]&gt;

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getMatchedRules()

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

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

Parametry

Zwroty

  • Promise&lt;RulesMatchedDetails&gt;

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

getSessionRules()

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

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

Parametry

  • filtr

    Opcjonalne GetRulesFilter

    Chrome w wersji 111 lub nowszej .

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

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    (rules: Rule[]) => void

Zwroty

  • Obietnica<Reguła[]>

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

isRegexSupported()

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

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

Parametry

Zwroty

  • Promise&lt;IsRegexSupportedResult&gt;

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

setExtensionActionOptions()

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

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

Parametry

  • wywołanie zwrotne

    funkcja optional

    Chrome w wersji 89 lub nowszej .

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

testMatchOutcome()

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

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

Parametry

Zwroty

  • Promise&lt;TestMatchOutcomeResult&gt;

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

updateDynamicRules()

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

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

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

Parametry

  • Chrome 87 i nowsze .
  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

updateEnabledRulesets()

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

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

Parametry

  • Chrome 87 i nowsze .
  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

updateSessionRules()

Obietnica Chrome w wersji 90 lub nowszej 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
)

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

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

Parametry

  • wywołanie zwrotne

    funkcja optional

    Parametr callback wygląda tak: 

    () => void

Zwroty

  • Obietnica<void>

    Chrome w wersji 91 lub nowszej .

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

updateStaticRules()

Obietnica Chrome w wersji 111 i nowszych 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

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

Parametry

Zwroty

  • Obietnica<void>

    Obietnice są obsługiwane w Manifest V3 i nowszych, ale wywołania zwrotne są podane w przypadku zgodność wsteczną. Nie można użyć obu w tym samym wywołaniu funkcji. Polecenie promowana jest realizowane z tym samym typem, który jest przekazywany do wywołania zwrotnego.

Wydarzenia

onRuleMatchedDebug

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

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

Parametry