browser.declarativeNetRequest

Opis

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

Uprawnienia

declarativeNetRequest
declarativeNetRequestWithHostAccess

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

"declarativeNetRequest"

Wywołuje ostrzeżenie o uprawnieniach podczas instalacji, ale zapewnia domyślny dostęp do reguł allow, allowAllRequests i block. Używaj tej opcji, gdy jest to możliwe, aby uniknąć konieczności proszenia o pełny dostęp do hostów.

"declarativeNetRequestFeedback"

Włącza funkcje debugowania w przypadku rozpakowanych rozszerzeń, a konkretnie getMatchedRules() i onRuleMatchedDebug.

"declarativeNetRequestWithHostAccess"

Ostrzeżenie o uprawnieniach nie jest wyświetlane podczas instalacji, ale musisz poprosić o uprawnienia hosta, zanim będzie można wykonać jakiekolwiek działanie na hoście. Jest to przydatne, gdy chcesz używać reguł declarativeNetRequest w rozszerzeniu, które ma już uprawnienia hosta, bez generowania dodatkowych ostrzeżeń.

Dostępność

Chrome 84 lub nowsza wersja browser.* od Chrome 148

Plik manifestu

Oprócz uprawnień opisanych wcześniej niektóre typy zestawów reguł, zwłaszcza statyczne zestawy reguł, wymagają zadeklarowania klucza manifestu "declarative_net_request", który powinien być słownikiem z jednym kluczem o nazwie "rule_resources". Ten klucz jest tablicą zawierającą słowniki typu Ruleset, jak pokazano poniżej. (Pamiętaj, że nazwa „Ruleset” nie pojawia się w pliku JSON manifestu, ponieważ jest to tylko tablica). Zestawy reguł statycznych 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 zbiory reguł

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

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

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

Dynamiczne

Są zachowywane między sesjami przeglądarki i uaktualnieniami rozszerzeń oraz zarządzane za pomocą JavaScriptu, gdy rozszerzenie jest używane.

Sesja

Dane są usuwane po zamknięciu przeglądarki i zainstalowaniu nowej wersji rozszerzenia. Regułami sesji zarządza się za pomocą JavaScriptu, gdy rozszerzenie jest używane.

Statyczny

Są pakowane, instalowane i aktualizowane podczas instalowania lub uaktualniania rozszerzenia. Reguły statyczne są przechowywane w plikach reguł w formacie JSON i wymienione w pliku manifestu.

Zestawy reguł dynamicznych i ograniczonych do sesji

Dynamicznymi zestawami reguł i zestawami reguł sesji zarządza się za pomocą JavaScriptu, gdy rozszerzenie jest używane.

• Reguły dynamiczne są zachowywane między sesjami przeglądarki i uaktualnieniami rozszerzeń.
• Reguły sesji są czyszczone po zamknięciu przeglądarki i zainstalowaniu nowej wersji rozszerzenia.

Istnieje tylko po jednym zbiorze reguł każdego z tych typów. Rozszerzenie może dynamicznie dodawać lub usuwać reguły, wywołując funkcje updateDynamicRules() i updateSessionRules(), o ile nie zostaną przekroczone limity reguł. Informacje o limitach reguł znajdziesz w artykule Limity reguł. Przykład znajdziesz w sekcji Przykłady kodu.

Statyczne zestawy reguł

W przeciwieństwie do reguł dynamicznych i reguł sesji reguły statyczne są pakowane, instalowane i aktualizowane podczas instalowania lub uaktualniania rozszerzenia. Są one przechowywane w plikach reguł w formacie JSON, które są wskazywane rozszerzeniu za pomocą kluczy "declarative_net_request" i "rule_resources" w sposób opisany powyżej, a także co najmniej 1 słownika Ruleset. Słownik Ruleset zawiera ścieżkę do pliku reguł, identyfikator zestawu reguł zawartego w pliku oraz informację o tym, czy zestaw reguł jest włączony czy wyłączony. Dwa ostatnie są ważne, gdy włączasz lub wyłączasz zestaw reguł automatycznie.

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

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

Przyspieszona weryfikacja

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

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

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

Zestaw włączonych reguł statycznych i zbiorów reguł jest zachowywany między sesjami przeglądarki. Żadne z nich nie są zachowywane po aktualizacji rozszerzenia, co oznacza, że po aktualizacji dostępne są tylko reguły, które zdecydujesz się pozostawić w plikach reguł.

Ze względu na wydajność obowiązują też ograniczenia dotyczące liczby reguł i zestawów reguł, które mogą być włączone jednocześnie. Zadzwoń pod numer getAvailableStaticRuleCount(), aby sprawdzić liczbę dodatkowych reguł, które mogą być włączone. 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 są definiowane za pomocą klucza "id" słownika Ruleset. Maksymalny limit wyłączonych reguł statycznych wynosi 5000.

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

Reguły kompilacji

Niezależnie od typu reguła zaczyna się od 4 pól, jak pokazano poniżej. Klucze "id" i "priority" przyjmują liczbę, natomiast klucze "action" i "condition" mogą zawierać kilka warunków blokowania i przekierowywania. Ta reguła blokuje wszystkie żądania skryptów pochodzące z "foo.com" do dowolnego adresu URL z "abc" jako podłańcuchem.

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

Dopasowanie adresu URL

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

Składnia filtra adresów URL

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

urlFilter	Dopasowania	Nie pasuje
"abc"	https://abcd.com https://example.com/abcd	https://ab.com
"abc*d"	https://abcd.com https://example.com/abcxyzd	https://abc.com
"||a.example.com"	https://a.example.com/ https://b.a.example.com/xyz https://a.example.company	https://example.com/
"|https*"	https://example.com	http://example.com/ http://https.com
"example*^123|"	https://example.com/123 http://abc.com/example?123	https://example.com/1234 https://abc.com/example0123

Wyrażenia regularne

W warunkach można też używać wyrażeń regularnych. Zobacz klucz "regexFilter". Informacje o limitach dotyczących tych warunków znajdziesz w artykule Reguły korzystające z wyrażeń regularnych.

Tworzenie dobrych warunków dotyczących adresów URL

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

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

Co warto wykorzystać:

• ||google.com/, co odpowiada wszystkim ścieżkom i subdomenom.
• |https://www.google.com/, co pasuje do wszystkich ścieżek i żadnych subdomen.

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

Ocena reguły

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

Przed wysłaniem prośby

Zanim żądanie zostanie wysłane, rozszerzenie może je zablokować lub przekierować (w tym zmienić schemat z HTTP na HTTPS) za pomocą pasującej reguły.

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

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

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

Jeśli więcej niż jedno rozszerzenie chce zablokować lub przekierować to żądanie, wybierane jest jedno działanie. Chrome robi to, sortując 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.

Uwaga: dostawcy przeglądarek uzgodnili, że nie będą standaryzować kolejności, w jakiej są uruchamiane reguły o tym samym działaniu i priorytecie. Może się to zmieniać między uruchomieniami lub wersjami przeglądarki, nawet jeśli jest rozłożone na kilka typów zestawów reguł (np. regułę statyczną i regułę sesji). Jeśli kolejność jest ważna, zawsze należy wyraźnie określić priorytet.

Przed wysłaniem nagłówków żądania

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

W ramach jednego rozszerzenia Chrome tworzy listę modyfikacji do wykonania, 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ż pasujące reguły allow lub allowAllRequests.

Te reguły są stosowane przez Chrome w takiej kolejności, że reguły z ostatnio zainstalowanego rozszerzenia są zawsze oceniane przed regułami ze 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 informacje, również dotyczące rozszerzeń:

• Jeśli reguła dodaje wartość do nagłówka, reguły o niższym priorytecie mogą tylko dodawać wartość do tego nagłówka. Operacje ustawiania i usuwania są niedozwolone.
• Jeśli reguła ustawia nagłówek, tylko reguły o niższym priorytecie z tego samego rozszerzenia mogą do niego dołączać. Żadne 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 warunkiem responseHeaders.

Po posortowaniu tych reguł według action i priority oraz wykluczeniu reguł, które stały się zbędne z powodu pasującej reguły allow lub allowAllRequests (odbywa się to tak samo jak w przypadku kroków opisanych 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 do serwera, a serwer otrzymał dane, takie jak treść żądania. Reguła blokowania lub przekierowania z warunkiem nagłówków odpowiedzi będzie nadal 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, otrzymując odpowiedź o zablokowaniu, a Chrome przedwcześnie kończy żądanie. W przypadku reguły przekierowania Chrome wysyła nowe żądanie do przekierowanego adresu URL. Zastanów się, czy te zachowania spełniają oczekiwania dotyczące prywatności w przypadku Twojego rozszerzenia.

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

Reguły bezpieczeństwa

Bezpieczne reguły to reguły, które mają działanie block, allow, allowAllRequests lub upgradeScheme. Te reguły podlegają zwiększonemu limitowi reguł dynamicznych.

Ograniczenia reguł

Wczytywanie i ocenianie reguł w przeglądarce wiąże się z obciążeniem, dlatego podczas korzystania z interfejsu API obowiązują pewne ograniczenia. Limity zależą od typu używanej reguły.

Reguły statyczne

Reguły statyczne to reguły określone w plikach reguł zadeklarowanych w pliku manifestu. Rozszerzenie może określać maksymalnie 100 statycznych zestawów reguł w ramach klucza manifestu "rule_resources", ale jednocześnie może być włączonych tylko 50 z nich. Ten drugi to MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Łącznie te zestawy reguł gwarantują co najmniej 30 000 reguł. Jest to GUARANTEED_MINIMUM_STATIC_RULES.

Uwaga: przed wersją Chrome 120 rozszerzenia były ograniczone do łącznie 50 statycznych zestawów reguł, z których tylko 10 mogło być włączonych jednocześnie. Użyj pola manifestu minimum_chrome_version, aby ograniczyć wersje Chrome, w których można zainstalować rozszerzenie.

Liczba reguł dostępnych po tym czasie zależy od tego, ile reguł jest włączonych przez wszystkie rozszerzenia zainstalowane w przeglądarce użytkownika. Możesz znaleźć ten numer w czasie działania, wywołując getAvailableStaticRuleCount(). Przykład znajdziesz w sekcji Przykłady kodu.

Uwaga: od wersji Chrome 128, jeśli użytkownik wyłączy rozszerzenie na stronie chrome://extensions, reguły statyczne rozszerzenia nie będą już wliczane do globalnego limitu reguł statycznych. Może to zwolnić limit reguł statycznych dla innych rozszerzeń, ale oznacza też, że po ponownym włączeniu rozszerzenia może ono mieć dostęp do mniejszej liczby reguł statycznych niż wcześniej.

Reguły sesji

Rozszerzenie może mieć maksymalnie 5000 reguł sesji. Jest to widoczne 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 to widoczne jako MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

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

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

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

Wyrażeń regularnych można używać we wszystkich typach reguł, ale łączna liczba reguł z wyrażeniami regularnymi każdego typu nie może przekraczać 1000. Jest to limit MAX_NUMBER_OF_REGEX_RULES.

Dodatkowo każda reguła po skompilowaniu musi mieć mniej niż 2 KB. Jest to w przybliżeniu skorelowane 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 pracownikami obsługi

Interfejs declarativeNetRequest dotyczy tylko żądań, które docierają do stosu sieciowego. Obejmuje to odpowiedzi z pamięci podręcznej HTTP, ale może nie obejmować odpowiedzi, które przechodzą przez moduł obsługi onfetch skryptu service worker. declarativeNetRequest nie będzie mieć wpływu na odpowiedzi generowane przez skrypt service worker ani pobierane z CacheStorage, ale będzie mieć wpływ na wywołania fetch() wykonywane w skrypcie service worker.

Zasoby dostępne w internecie

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

Modyfikacja nagłówka

Operacja dołączania jest obsługiwana tylko w przypadku tych nagłówków żądania: 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. W przypadku tej listy dozwolonych wielkość liter ma znaczenie (błąd 449152902).

Podczas dołączania do nagłówka żądania lub nagłówka odpowiedzi przeglądarka użyje odpowiedniego separatora, jeśli będzie to możliwe.

Przykłady

Przykłady kodu

Aktualizowanie reguł dynamicznych

Poniższy przykład pokazuje, jak wywołać updateDynamicRules(). Procedura dla updateSessionRules() jest taka sama.

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

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

Aktualizowanie statycznych zestawów reguł

Poniższy 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ł. Możesz to zrobić, gdy liczba potrzebnych reguł statycznych przekracza dozwoloną liczbę. Aby to działało, niektóre zestawy reguł powinny być zainstalowane z wyłączonymi niektórymi zestawami reguł (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 browser.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 > browser.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await browser.declarativeNetRequest.updateEnabledRulesets(options);
}

Przykłady reguł

Przykłady poniżej pokazują, jak Chrome ustala priorytety reguł w rozszerzeniu. Podczas sprawdzania reguł możesz otworzyć reguły ustalania priorytetów w osobnym oknie.

Klucz „priority”

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

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

Nawigacja do https://google.com

Ten adres URL jest objęty 2 regułami: o identyfikatorach 1 i 4. Zastosowana zostanie reguła o identyfikatorze 1, ponieważ działania "block" mają wyższy priorytet niż działania "redirect". Pozostałe reguły nie mają zastosowania, ponieważ dotyczą dłuższych adresów URL.

Przejście na stronę https://google.com/1234

Ze względu na dłuższy adres URL reguła o identyfikatorze 2 jest teraz dopasowywana oprócz reguł o identyfikatorach 1 i 4. Zastosowana zostanie reguła o identyfikatorze 2, 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. Zastosowana zostanie reguła o identyfikatorze 3, ponieważ ma najwyższy priorytet w grupie zdefiniowany przez dewelopera.

[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {"urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "allow" },
    "condition": { "urlFilter": "||google.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 3,
    "priority": 2,
    "action": { "type": "block" },
    "condition": { "urlFilter": "||google.com/12345", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 4,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
    "condition": { "urlFilter": "||google.com/", "resourceTypes": ["main_frame"] }
  },
]

Przekierowania

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

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

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

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

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

W przykładzie poniżej użyto wyrażeń regularnych do przekierowania z https://www.abc.xyz.com/path na https://abc.xyz.com/path. W kluczu "regexFilter" zwróć uwagę na to, jak kropki są poprzedzone znakiem zmiany znaczenia i że grupa przechwytywania wybiera „abc” lub „def”. Klucz "regexSubstitution" określa pierwsze zwrócone dopasowanie wyrażenia regularnego za pomocą „\1”. W tym przypadku „abc” jest pobierane z przekierowanego adresu URL i umieszczane w podstawieniu.

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

Nagłówki

W przykładzie poniżej usuwane są wszystkie pliki cookie zarówno z ramki głównej, jak i z ramek podrzędnych.

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

Typy

DomainType

Określa, czy żądanie jest własne czy zewnętrzne w stosunku do ramki, w której zostało wygenerowane. Żądanie jest uznawane za żądanie własne, jeśli ma tę samą domenę (eTLD+1) co ramka, w której zostało wygenerowane.

Typ wyliczeniowy

"firstParty"
Żądanie sieciowe jest własne w ramce, w której zostało wygenerowane.

"thirdParty"
Żądanie sieciowe pochodzi z ramki innej firmy.

ExtensionActionOptions

Chrome 88 lub nowsza browser.* od Chrome 148

Właściwości

• displayActionCountAsBadgeText

  boolean opcjonalne

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

• tabUpdate

  TabActionCountUpdate opcjonalny

  Chrome 89 lub nowsza browser.* od Chrome 148

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

GetDisabledRuleIdsOptions

Chrome 111 lub nowsza wersja browser.* od Chrome 148

Właściwości

• rulesetId

  tekst

  Identyfikator odpowiadający statycznemu elementowi Ruleset.

GetRulesFilter

Chrome 111 lub nowsza wersja browser.* od Chrome 148

Właściwości

• ruleIds

  number[] opcjonalny

  Jeśli podasz tę wartość, uwzględniane będą tylko reguły o zgodnych identyfikatorach.

HeaderInfo

Chrome 128 lub nowsza browser.* od Chrome 148

Właściwości

• excludedValues

  string[] opcjonalne

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

• nagłówek

  tekst

  Nazwa nagłówka. Ten warunek dopasowuje nazwę tylko wtedy, gdy nie określono ani values, ani excludedValues.

• wartości

  string[] opcjonalne

  Jeśli ten warunek jest określony, jest spełniony, gdy wartość nagłówka pasuje do co najmniej jednego wzorca na tej liście. Obsługuje dopasowywanie wartości nagłówka, w którym wielkość liter nie jest rozróżniana, oraz te konstrukcje:

  '*' : odpowiada dowolnej liczbie znaków.

  '?' : odpowiada 0 lub 1 znakowi.

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

HeaderOperation

Chrome 86 lub nowsza browser.* od Chrome 148

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

Typ wyliczeniowy

"append"
Dodaje nowy wpis dla określonego nagłówka. Podczas modyfikowania nagłówków żądania ta operacja jest obsługiwana tylko w przypadku określonych nagłówków.

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

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

IsRegexSupportedResult

Chrome 87 lub nowsza browser.* od Chrome 148

Właściwości

• isSupported

  wartość logiczna

• reason

  UnsupportedRegexReason opcjonalny

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

MatchedRule

Właściwości

• ruleId

  liczba

  Identyfikator reguły dopasowania.

• rulesetId

  tekst

  Identyfikator Ruleset, do którego należy ta reguła. W przypadku reguły pochodzącej z zestawu reguł dynamicznych będzie to DYNAMIC_RULESET_ID.

MatchedRuleInfo

Właściwości

• reguła

  MatchedRule

• tabId

  liczba

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

• timeStamp

  liczba

  Czas dopasowania reguły. Sygnatury czasowe będą zgodne z konwencją JavaScriptu dotyczącą czasu, czyli będą liczbą milisekund od początku epoki.

MatchedRuleInfoDebug

Właściwości

• żądanie

  RequestDetails

  Szczegółowe informacje o żądaniu, do którego dopasowano regułę.

• reguła

  MatchedRule

MatchedRulesFilter

Właściwości

• minTimeStamp

  number optional

  Jeśli została określona, dopasowuje tylko reguły po podanej sygnaturze czasowej.

• tabId

  number optional

  Jeśli jest określona, dopasowuje tylko reguły dla danej karty. Jeśli ustawiono wartość -1, dopasowuje reguły, które nie są powiązane z żadną aktywną kartą.

ModifyHeaderInfo

Chrome 86 lub nowsza browser.* od Chrome 148

Właściwości

• nagłówek

  tekst

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

• operacja

  HeaderOperation

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

• wartość

  ciąg znaków opcjonalny

  Nowa wartość nagłówka. Musisz go określić w przypadku operacji append i set.

QueryKeyValue

Właściwości

• klucz

  tekst

• replaceOnly

  boolean opcjonalne

  Chrome 94 lub nowsza wersja browser.* od Chrome 148

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

• wartość

  tekst

QueryTransform

Właściwości

• addOrReplaceParams

  QueryKeyValue[] opcjonalny

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

• removeParams

  string[] opcjonalne

  Lista kluczy zapytań do usunięcia.

Redirect

Właściwości

• extensionPath

  ciąg znaków opcjonalny

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

• regexSubstitution

  ciąg znaków opcjonalny

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

• przekształcenie

  URLTransform opcjonalny

  Przekształcenia adresów URL do wykonania.

• URL

  ciąg znaków opcjonalny

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

RegexOptions

Chrome 87 lub nowsza browser.* od Chrome 148

Właściwości

• isCaseSensitive

  boolean opcjonalne

  Określa, czy w przypadku podanej wartości regex ma być uwzględniana wielkość liter. Wartość domyślna to true.

• wyrażenie regularne

  tekst

  Wyrażenie regularne do sprawdzenia.

• requireCapturing

  boolean opcjonalne

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

RequestDetails

Właściwości

• documentId

  ciąg znaków opcjonalny

  Chrome 106 lub nowsza browser.* od Chrome 148

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

• documentLifecycle

  DocumentLifecycle opcjonalny

  Chrome 106 lub nowsza browser.* od Chrome 148

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

• frameId

  liczba

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

• frameType

  FrameType opcjonalny

  Chrome 106 lub nowsza browser.* od Chrome 148

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

• inicjator

  ciąg znaków opcjonalny

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

• method

  tekst

  Standardowa metoda HTTP.

• parentDocumentId

  ciąg znaków opcjonalny

  Chrome 106 lub nowsza browser.* od Chrome 148

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

• parentFrameId

  liczba

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

• requestId

  tekst

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

• tabId

  liczba

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

• typ

  ResourceType

  Typ zasobu żądania.

• URL

  tekst

  Adres URL żądania.

RequestMethod

Chrome 91 lub nowsza browser.* od Chrome 148

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

Typ wyliczeniowy

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

Opisuje typ zasobu żądania sieciowego.

Typ wyliczeniowy

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

Właściwości

• działanie

  RuleAction

  Działanie, które należy podjąć, jeśli ta reguła zostanie dopasowana.

• warunek

  RuleCondition

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

• id

  liczba

  Identyfikator, który jednoznacznie identyfikuje regułę. Obowiązkowa i powinna być większa lub równa 1.

• kampanii

  number optional

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

RuleAction

Właściwości

• Przekieruj

  Redirect opcjonalny

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

• requestHeaders

  ModifyHeaderInfo[] opcjonalny

  Chrome 86 lub nowsza browser.* od Chrome 148

  Nagłówki żądania, które mają zostać zmodyfikowane. Ma zastosowanie tylko wtedy, gdy RuleActionType to „modifyHeaders”.

• responseHeaders

  ModifyHeaderInfo[] opcjonalny

  Chrome 86 lub nowsza browser.* od Chrome 148

  Nagłówki odpowiedzi do zmodyfikowania w żądaniu. Ma zastosowanie tylko wtedy, gdy RuleActionType to „modifyHeaders”.

• typ

  RuleActionType

  Typ działania, które ma zostać wykonane.

RuleActionType

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

Typ wyliczeniowy

"block"
Blokuje żądanie sieciowe.

"redirect"
Przekieruj żądanie sieciowe.

"allow"
Zezwalaj na żądanie sieciowe. Żądanie nie zostanie przechwycone, jeśli istnieje pasująca do niego reguła zezwalania.

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

"modifyHeaders"
Modyfikowanie nagłówków żądania/odpowiedzi z żądania sieciowego.

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

RuleCondition

Właściwości

• domainType

  DomainType opcjonalny

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

• domeny

  string[] opcjonalne

  Wycofane od wersji Chrome 101

  Użyj w zamian initiatorDomains

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

• excludedDomains

  string[] opcjonalne

  Wycofane od wersji Chrome 101

  Użyj w zamian excludedInitiatorDomains

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

• excludedInitiatorDomains

  string[] opcjonalne

  Chrome 101 lub nowsza browser.* od Chrome 148

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

  Uwagi:

  • Dozwolone są też subdomeny, np. „a.example.com”.
  • Wpisy mogą zawierać tylko znaki ASCII.
  • W przypadku domen międzynarodowych używaj kodowania punycode.
  • Dopasowanie dotyczy inicjatora żądania, a nie adresu URL żądania.
  • Subdomeny wymienionych domen również są wykluczone.
• excludedRequestDomains

  string[] opcjonalne

  Chrome 101 lub nowsza browser.* od Chrome 148

  Reguła nie będzie dopasowywać żądań sieciowych, gdy domeny będą zgodne z domenami z listy excludedRequestDomains. Jeśli lista jest pusta lub pominięta, żadne domeny nie są wykluczone. Ta zasada ma pierwszeństwo przed zasadą requestDomains.

  Uwagi:

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

  RequestMethod[] opcjonalny

  Chrome 91 lub nowsza browser.* od Chrome 148

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

• excludedResourceTypes

  ResourceType[] opcjonalny

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

• excludedResponseHeaders

  HeaderInfo[] opcjonalny

  Chrome 128 lub nowsza browser.* od Chrome 148

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

• excludedTabIds

  number[] opcjonalny

  Chrome 92 lub nowsza wersja browser.* od Chrome 148

  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.

• excludedTopDomains

  string[] opcjonalne

  Chrome 145 lub nowsza browser.* od Chrome 148

  Reguła nie będzie dopasowywać żądań sieciowych, gdy domena powiązanej ramki najwyższego poziomu będzie zgodna z domeną z listy excludedTopDomains. Jeśli lista jest pusta lub pominięta, żadne domeny nie są wykluczone. Ta zasada ma pierwszeństwo przed zasadą topDomains.

  Uwagi:

  • Dozwolone są też subdomeny, np. „a.example.com”.
  • Wpisy mogą zawierać tylko znaki ASCII.
  • W przypadku domen międzynarodowych używaj kodowania punycode.
  • Subdomeny wymienionych domen również są wykluczone.
  • W przypadku żądań bez powiązanej ramki najwyższego poziomu (np. żądań inicjowanych przez ServiceWorker) brana jest pod uwagę domena inicjatora żądania.
• initiatorDomains

  string[] opcjonalne

  Chrome 101 lub nowsza browser.* od Chrome 148

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

  Uwagi:

  • Dozwolone są też subdomeny, np. „a.example.com”.
  • Wpisy mogą zawierać tylko znaki ASCII.
  • W przypadku domen międzynarodowych używaj kodowania punycode.
  • Dopasowanie dotyczy inicjatora żądania, a nie adresu URL żądania.
  • Subdomeny wymienionych domen również są dopasowywane.
• isUrlFilterCaseSensitive

  boolean opcjonalne

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

• regexFilter

  ciąg znaków opcjonalny

  Wyrażenie regularne, które ma być dopasowane do adresu URL żądania sieciowego. Używana jest składnia RE2.

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

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

• requestDomains

  string[] opcjonalne

  Chrome 101 lub nowsza browser.* od Chrome 148

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

  Uwagi:

  • Dozwolone są też subdomeny, np. „a.example.com”.
  • Wpisy mogą zawierać tylko znaki ASCII.
  • W przypadku domen międzynarodowych używaj kodowania punycode.
  • Subdomeny wymienionych domen również są dopasowywane.
• requestMethods

  RequestMethod[] opcjonalny

  Chrome 91 lub nowsza browser.* od Chrome 148

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

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

• resourceTypes

  ResourceType[] opcjonalny

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

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

• responseHeaders

  HeaderInfo[] opcjonalny

  Chrome 128 lub nowsza browser.* od Chrome 148

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

• tabIds

  number[] opcjonalny

  Chrome 92 lub nowsza wersja browser.* od Chrome 148

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

• topDomains

  string[] opcjonalne

  Chrome 145 lub nowsza browser.* od Chrome 148

  Reguła będzie dopasowywać tylko żądania sieciowe, gdy domena powiązanej ramki najwyższego poziomu będzie zgodna z domeną z listy topDomains. Jeśli lista zostanie pominięta, reguła będzie stosowana do żądań powiązanych ze wszystkimi domenami ramek najwyższego poziomu. Pusta lista jest niedozwolona.

  Uwagi:

  • Dozwolone są też subdomeny, np. „a.example.com”.
  • Wpisy mogą zawierać tylko znaki ASCII.
  • W przypadku domen międzynarodowych używaj kodowania punycode.
  • Subdomeny wymienionych domen również są dopasowywane.
  • W przypadku żądań bez powiązanej ramki najwyższego poziomu (np. żądań inicjowanych przez ServiceWorker) brana jest pod uwagę domena inicjatora żądania.
• urlFilter

  ciąg znaków opcjonalny

  Wzorzec, który jest dopasowywany do adresu URL żądania sieciowego. Obsługiwane konstrukcje:

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

  '|': kotwica po lewej/prawej stronie – jeśli jest używana na końcu wzorca, określa odpowiednio początek lub koniec adresu URL.

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

  '^' : separator: pasuje do wszystkiego oprócz liter, cyfr i tych znaków: _, -, ., %. Dopasowuje też koniec adresu URL.

  Dlatego urlFilter składa się z tych części: (opcjonalna kotwica po lewej stronie / kotwica nazwy domeny) + wzorzec + (opcjonalna kotwica po prawej stronie).

  Jeśli pominiesz tę wartość, dopasowywane będą wszystkie adresy URL. Pusty ciąg znaków jest niedozwolony.

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

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

  Uwaga: urlFilter musi składać się wyłącznie ze znaków ASCII. Jest on dopasowywany do adresu URL, w którym host jest zakodowany w formacie punycode (w przypadku domen międzynarodowych), a wszystkie inne znaki spoza zestawu ASCII są zakodowane w formacie UTF-8. Jeśli na przykład adres URL żądania to http://abc.рф?q=ф, urlFilter zostanie dopasowany do adresu URL http://abc.xn--p1ai/?q=%D1%84.

RuleConditionKeys

Chrome 145 lub nowsza browser.* od Chrome 148

Typ wyliczeniowy

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

Właściwości

• aktywne

  wartość logiczna

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

• id

  tekst

  Niepusty ciąg znaków, który jednoznacznie identyfikuje zestaw reguł. Identyfikatory zaczynające się od „_” są zarezerwowane do użytku wewnętrznego.

• ścieżka

  tekst

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

RulesMatchedDetails

Właściwości

• rulesMatchedInfo

  MatchedRuleInfo[]

  Reguły pasujące do danego filtra.

TabActionCountUpdate

Chrome 89 lub nowsza browser.* od Chrome 148

Właściwości

• Zwiększ

  liczba

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

• tabId

  liczba

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

TestMatchOutcomeResult

Chrome 103 lub nowsza wersja browser.* od Chrome 148

Właściwości

• matchedRules

  MatchedRule[]

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

TestMatchRequestDetails

Chrome 103 lub nowsza wersja browser.* od Chrome 148

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. W przypadku żądań HTTP domyślnie jest to „get”, a w przypadku żądań innych niż HTTP jest ignorowane.

• responseHeaders

  object opcjonalny

  Chrome 129 lub nowsza browser.* od Chrome 148

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

• tabId

  number optional

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

• topUrl

  ciąg znaków opcjonalny

  Chrome 145 lub nowsza browser.* od Chrome 148

  Powiązany adres URL ramki najwyższego poziomu (jeśli istnieje) dla żądania.

• typ

  ResourceType

  Typ zasobu hipotetycznego żądania.

• URL

  tekst

  Adres URL hipotetycznego żądania.

UnsupportedRegexReason

Chrome 87 lub nowsza browser.* od Chrome 148

Opisuje, dlaczego dane wyrażenie regularne nie jest obsługiwane.

Typ wyliczeniowy

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

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

UpdateRuleOptions

Chrome 87 lub nowsza browser.* od Chrome 148

Właściwości

• addRules

  Rule[] opcjonalne

  Reguły do dodania.

• removeRuleIds

  number[] opcjonalny

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

UpdateRulesetOptions

Chrome 87 lub nowsza browser.* od Chrome 148

Właściwości

• disableRulesetIds

  string[] opcjonalne

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

• enableRulesetIds

  string[] opcjonalne

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

UpdateStaticRulesOptions

Chrome 111 lub nowsza wersja browser.* od Chrome 148

Właściwości

• disableRuleIds

  number[] opcjonalny

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

• enableRuleIds

  number[] opcjonalny

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

• rulesetId

  tekst

  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 zaczynać się od znaku „#”.

• host

  ciąg znaków opcjonalny

  Nowy host żą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 pole jest puste, dotychczasowa ścieżka zostanie wyczyszczona.

• port

  ciąg znaków opcjonalny

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

• zapytanie

  ciąg znaków opcjonalny

  Nowe zapytanie dla żądania. Może być puste (w takim przypadku istniejące zapytanie zostanie wyczyszczone) lub zaczynać się od znaku „?”.

• queryTransform

  QueryTransform opcjonalny

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

• schemat

  ciąg znaków opcjonalny

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

• nazwa użytkownika

  ciąg znaków opcjonalny

  Nowa nazwa użytkownika dla żądania.

Właściwości

DYNAMIC_RULESET_ID

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

Wartość

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Przedział czasu, w którym można wykonać MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules połączeń, podany w minutach. Dodatkowe wywołania natychmiast zakończą się niepowodzeniem i ustawią runtime.lastError. Uwaga: wywołania getMatchedRules powiązane z gestem użytkownika nie są objęte limitem.

Wartość

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 lub nowsza browser.* od Chrome 148

Minimalna liczba reguł statycznych gwarantowanych dla rozszerzenia 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.

Wartość

20

MAX_NUMBER_OF_DYNAMIC_RULES

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

Wartość

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 lub nowsza wersja browser.* od Chrome 148

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

Wartość

50

MAX_NUMBER_OF_REGEX_RULES

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

Wartość

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 lub nowsza browser.* od Chrome 148

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

Wartość

5000

MAX_NUMBER_OF_STATIC_RULESETS

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

Wartość

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 lub nowsza browser.* od Chrome 148

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

Wartość

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 lub nowsza browser.* od Chrome 148

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

Wartość

5000

SESSION_RULESET_ID

Chrome 90 lub nowsza browser.* od Chrome 148

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

Wartość

"_session"

Metody

getAvailableStaticRuleCount()

Chrome 89 lub nowsza browser.* od Chrome 148

browser.declarativeNetRequest.getAvailableStaticRuleCount(): Promise<number>

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

Zwroty

• Promise<number>

  Chrome 91 lub nowsza browser.* od Chrome 148

getDisabledRuleIds()

Chrome 111 lub nowsza wersja browser.* od Chrome 148

browser.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
): Promise<number[]>

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

Parametry

• Opcje

  GetDisabledRuleIdsOptions

  Określa zestaw reguł, do którego ma zostać wysłane zapytanie.

Zwroty

• thought Promise<number[]>

  Obiekt Promise, który zwraca listę identyfikatorów odpowiadających wyłączonym regułom w tym zbiorze reguł.

getDynamicRules()

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

Zwraca bieżący zestaw reguł dynamicznych rozszerzenia. Osoby dzwoniące mogą opcjonalnie filtrować listę pobranych reguł, podając filter.

Parametry

• filtr

  GetRulesFilter opcjonalny

  Chrome 111 lub nowsza wersja browser.* od Chrome 148

  Obiekt do filtrowania listy pobranych reguł.

Zwroty

• Promise<Rule[]>

  Chrome 91 lub nowsza browser.* od Chrome 148

  Obiekt Promise, który rozwiązuje się za pomocą zbioru reguł dynamicznych. Obiekt Promise może zostać odrzucony w przypadku tymczasowych błędów wewnętrznych.

getEnabledRulesets()

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

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

Zwroty

• Promise<string[]>

  Chrome 91 lub nowsza browser.* od Chrome 148

  Obiekt Promise, który zwraca listę identyfikatorów, gdzie każdy identyfikator odpowiada włączonemu statycznemu obiektowi Ruleset.

getMatchedRules()

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

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

Parametry

• filtr

  MatchedRulesFilter opcjonalny

  Obiekt do filtrowania listy pasujących reguł.

Zwroty

• Promise<RulesMatchedDetails>

  Chrome 91 lub nowsza browser.* od Chrome 148

  Obiekt Promise, który jest rozwiązywany po pobraniu listy dopasowanych reguł. W przypadku błędu obiekt Promise zostanie odrzucony. Może się tak zdarzyć z różnych powodów, takich jak niewystarczające uprawnienia lub przekroczenie limitu.

getSessionRules()

Chrome 90 lub nowsza browser.* od Chrome 148

browser.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

Zwraca bieżący zestaw reguł rozszerzenia w ramach sesji. Osoby dzwoniące mogą opcjonalnie filtrować listę pobranych reguł, podając filter.

Parametry

• filtr

  GetRulesFilter opcjonalny

  Chrome 111 lub nowsza wersja browser.* od Chrome 148

  Obiekt do filtrowania listy pobranych reguł.

Zwroty

• Promise<Rule[]>

  Chrome 91 lub nowsza browser.* od Chrome 148

  Obiekt Promise, który jest rozwiązywany za pomocą zestawu reguł o zakresie sesji.

isRegexSupported()

Chrome 87 lub nowsza browser.* od Chrome 148

browser.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
): Promise<IsRegexSupportedResult>

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

Parametry

• regexOptions

  RegexOptions

  Wyrażenie regularne do sprawdzenia.

Zwroty

• Promise<IsRegexSupportedResult>

  Chrome 91 lub nowsza browser.* od Chrome 148

  Obiekt Promise, który zwraca szczegóły dotyczące tego, czy wyrażenie regularne jest obsługiwane, a jeśli nie, to dlaczego.

setExtensionActionOptions()

Chrome 88 lub nowsza browser.* od Chrome 148

browser.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise<void>

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

Parametry

• Opcje

  ExtensionActionOptions

Zwroty

• thought Promise<void>

  Chrome 91 lub nowsza browser.* od Chrome 148

testMatchOutcome()

Chrome 103 lub nowsza wersja browser.* od Chrome 148

browser.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
): Promise<TestMatchOutcomeResult>

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

Parametry

• żądanie

  TestMatchRequestDetails

Zwroty

• Promise<TestMatchOutcomeResult>

  Obiekt Promise, który zwraca szczegóły pasujących reguł.

updateDynamicRules()

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

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

• Ta aktualizacja jest wykonywana jako pojedyncza operacja niepodzielna: dodawane i usuwane są wszystkie określone reguły albo zwracany jest błąd.
• Te reguły są zachowywane między sesjami przeglądarki i aktualizacjami 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

• Opcje

  UpdateRuleOptions

  Chrome 87 lub nowsza browser.* od Chrome 148

Zwroty

• thought Promise<void>

  Chrome 91 lub nowsza browser.* od Chrome 148

  Obietnica, która zostanie spełniona po zakończeniu aktualizacji. W przypadku błędu obietnica zostanie odrzucona i nie zostaną wprowadzone żadne zmiany w zestawie reguł. Może się tak zdarzyć z różnych powodów, takich jak nieprawidłowy format reguły, zduplikowany identyfikator reguły, przekroczenie limitu liczby reguł, błędy wewnętrzne i inne.

updateEnabledRulesets()

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

Aktualizuje zestaw włączonych statycznych zbiorów reguł rozszerzenia. Najpierw usuwane są zestawy reguł o identyfikatorach wymienionych w options.disableRulesetIds, a następnie dodawane są zestawy reguł wymienione w options.enableRulesetIds. Pamiętaj, że zestaw włączonych statycznych zbiorów reguł jest zachowywany między sesjami, ale nie między aktualizacjami rozszerzeń, tzn. klucz manifestu rule_resources określa zestaw włączonych statycznych zbiorów reguł przy każdej aktualizacji rozszerzenia.

Parametry

• Opcje

  UpdateRulesetOptions

  Chrome 87 lub nowsza browser.* od Chrome 148

Zwroty

• thought Promise<void>

  Chrome 91 lub nowsza browser.* od Chrome 148

  Obietnica, która zostanie spełniona po zakończeniu aktualizacji. W przypadku błędu obietnica zostanie odrzucona i nie zostaną wprowadzone żadne zmiany w zestawie włączonych zestawów reguł. Może się to zdarzyć z różnych powodów, takich jak nieprawidłowe identyfikatory zestawów reguł, przekroczenie limitu liczby reguł lub błędy wewnętrzne.

updateSessionRules()

Chrome 90 lub nowsza browser.* od Chrome 148

browser.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
): Promise<void>

Modyfikuje bieżący zestaw reguł rozszerzenia na poziomie sesji. Najpierw usuwane są reguły o identyfikatorach wymienionych w options.removeRuleIds, a potem dodawane są reguły podane w options.addRules. Uwagi:

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

Parametry

• Opcje

  UpdateRuleOptions

Zwroty

• thought Promise<void>

  Chrome 91 lub nowsza browser.* od Chrome 148

  Obietnica, która zostanie spełniona po zakończeniu aktualizacji. W przypadku błędu obietnica zostanie odrzucona i nie zostaną wprowadzone żadne zmiany w zestawie reguł. Może się tak zdarzyć z różnych powodów, takich jak nieprawidłowy format reguły, zduplikowany identyfikator reguły, przekroczenie limitu liczby reguł i inne.

updateStaticRules()

Chrome 111 lub nowsza wersja browser.* od Chrome 148

browser.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise<void>

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

Parametry

• Opcje

  UpdateStaticRulesOptions

Zwroty

• thought Promise<void>

  Obietnica, która zostanie spełniona po zakończeniu aktualizacji. W przypadku błędu obietnica zostanie odrzucona i nie zostaną wprowadzone żadne zmiany we włączonych regułach statycznych.

Wydarzenia

onRuleMatchedDebug

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

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

Parametry

• callback

  funkcja

  Parametr callback wygląda tak:

  (info: MatchedRuleInfoDebug) => void

  • informacje

    MatchedRuleInfoDebug