chrome.declarativeWebRequest

refresh date: 2026-09-25 robots: noindex

Opis

Uwaga: ten interfejs API został wycofany. Zamiast tego użyj interfejsu declarativeNetRequest API. Użyj interfejsu chrome.declarativeWebRequest API, aby przechwytywać, blokować lub modyfikować żądania w trakcie ich przesyłania. Jest on znacznie szybszy niż interfejs API chrome.webRequest, ponieważ możesz rejestrować reguły, które są oceniane w przeglądarce, a nie w mechanizmie JavaScript. Zmniejsza to opóźnienia związane z ruchem w obie strony i zwiększa wydajność.

Uprawnienia

declarativeWebRequest

Aby korzystać z tego interfejsu API, musisz zadeklarować uprawnienie „declarativeWebRequest” w pliku manifestu rozszerzenia, a także uprawnienia dotyczące hosta.

{
  "name": "My extension",
  ...
  "permissions": [
    "declarativeWebRequest",
    "*://*/*"
  ],
  ...
}

Dostępność

Wersja beta ≤ MV2

Plik manifestu

Pamiętaj, że niektóre rodzaje działań nie wymagają uprawnień hosta:

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

Działanie SendMessageToExtension() wymaga uprawnień hosta w przypadku wszystkich hostów, w których przypadku chcesz wywołać wiadomość.

Wszystkie inne działania wymagają uprawnień hosta do wszystkich adresów URL.

Jeśli na przykład "https://*.google.com/*" jest jedynym uprawnieniem hosta, jakie ma rozszerzenie, może ono skonfigurować regułę, która:

  • Anuluj prośbę o dostęp do rozszerzenia https://www.google.com lub https://anything.else.com.
  • Wysyłanie wiadomości podczas nawigowania do https://www.google.com, ale nie do https://something.else.com.

Rozszerzenie nie może skonfigurować reguły przekierowania z https://www.google.com na https://mail.google.com.

Reguły

Interfejs Declarative Web Request API jest zgodny z koncepcjami interfejsu Declarative API. Możesz zarejestrować reguły w obiekcie zdarzenia chrome.declarativeWebRequest.onRequest.

Interfejs Declarative Web Request API obsługuje jeden typ kryteriów dopasowania, czyli RequestMatcher. Warunek RequestMatcher pasuje do żądań sieciowych tylko wtedy, gdy spełnione są wszystkie wymienione kryteria. Poniższy RequestMatcher będzie pasować do żądania sieci, gdy użytkownik wpisze https://www.example.com w omniboksie:

var matcher = new chrome.declarativeWebRequest.RequestMatcher({
  url: { hostSuffix: 'example.com', schemes: ['http'] },
  resourceType: ['main_frame']
});

Żądania wysyłane do https://www.example.com będą odrzucane przez RequestMatcher ze względu na ten schemat. Wszystkie żądania dotyczące osadzonego elementu iframe również zostaną odrzucone z powodu resourceType.

Aby anulować wszystkie żądania wysyłane do domeny „example.com”, możesz zdefiniować regułę w ten sposób:

var rule = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

Aby anulować wszystkie żądania wysyłane do example.com i foobar.com, możesz dodać drugi warunek, ponieważ każdy warunek wystarczy, aby wywołać wszystkie określone działania:

var rule2 = {
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'example.com' } }),
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: 'foobar.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};

Zarejestruj reguły w ten sposób:

chrome.declarativeWebRequest.onRequest.addRules([rule2]);

Ocena warunków i działań

Interfejs Declarative Web Request API jest zgodny z modelem cyklu życia żądań internetowych interfejsu Web Request API. Oznacza to, że warunki można testować tylko na określonych etapach żądania sieciowego, a działania można wykonywać tylko na określonych etapach. W tabelach poniżej znajdziesz etapy żądania, które są zgodne z warunkami i działaniami.

Etapy żądania, podczas których można przetwarzać atrybuty warunku.
Atrybut stanu onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
url ✓ ✓ ✓ ✓
resourceType ✓ ✓ ✓ ✓
contentType ✓
excludeContentType ✓
responseHeaders ✓
excludeResponseHeaders ✓
requestHeaders ✓
excludeRequestHeaders ✓
thirdPartyForCookies ✓ ✓ ✓ ✓
Etapy żądania, podczas których można wykonywać działania.
Zdarzenie onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
AddRequestCookie ✓
AddResponseCookie ✓
AddResponseHeader ✓
CancelRequest ✓ ✓ ✓ ✓
EditRequestCookie ✓
EditResponseCookie ✓
IgnoreRules ✓ ✓ ✓ ✓
RedirectByRegEx ✓ ✓
RedirectRequest ✓ ✓
RedirectToEmptyDocument ✓ ✓
RedirectToTransparentImage ✓ ✓
RemoveRequestCookie ✓
RemoveRequestHeader ✓
RemoveResponseCookie ✓
RemoveResponseHeader ✓
SendMessageToExtension ✓ ✓ ✓ ✓
SetRequestHeader ✓

Używanie priorytetów do zastępowania reguł

Reguły można powiązać z priorytetami w sposób opisany w interfejsie Events API. Ten mechanizm może służyć do wyrażania wyjątków. Poniższy przykład blokuje wszystkie żądania obrazów o nazwie evil.jpgz wyjątkiem serwera „myserver.com”.

var rule1 = {
  priority: 100,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
        url: { pathEquals: 'evil.jpg' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.CancelRequest()
  ]
};
var rule2 = {
  priority: 1000,
  conditions: [
    new chrome.declarativeWebRequest.RequestMatcher({
      url: { hostSuffix: '.myserver.com' } })
  ],
  actions: [
    new chrome.declarativeWebRequest.IgnoreRules({
      lowerPriorityThan: 1000 })
  ]
};
chrome.declarativeWebRequest.onRequest.addRules([rule1, rule2]);

Pamiętaj, że działanie IgnoreRules nie jest zachowywane na etapach żądania. Na każdym etapie żądania internetowego są sprawdzane wszystkie warunki wszystkich reguł. Jeśli zostanie wykonane działanie IgnoreRules, będzie ono miało zastosowanie tylko do innych działań, które są wykonywane w ramach tego samego żądania internetowego na tym samym etapie.

Typy

AddRequestCookie

Dodaje plik cookie do żądania lub zastępuje go, jeśli istnieje już inny plik cookie o tej samej nazwie. Zalecamy używanie interfejsu Cookies API, ponieważ jest on mniej kosztowny pod względem obliczeniowym.

Właściwości

AddResponseCookie

Dodaje plik cookie do odpowiedzi lub zastępuje plik cookie, jeśli istnieje już inny plik cookie o tej samej nazwie. Zalecamy używanie interfejsu Cookies API, ponieważ jest on mniej kosztowny pod względem obliczeniowym.

Właściwości

AddResponseHeader

Dodaje nagłówek odpowiedzi do odpowiedzi na to żądanie internetowe. Wiele nagłówków odpowiedzi może mieć tę samą nazwę, więc aby zastąpić nagłówek, musisz najpierw go usunąć, a potem dodać nowy.

Właściwości

CancelRequest

Deklaratywne działanie związane z wydarzeniem, które anuluje żądanie sieciowe.

Właściwości

EditRequestCookie

Edytuje co najmniej 1 plik cookie żądania. Zalecamy używanie interfejsu Cookies API, ponieważ jest on mniej kosztowny pod względem obliczeniowym.

Właściwości

  • konstruktor,

    pusty

    Funkcja constructor wygląda tak:

    (arg: EditRequestCookie) => {...}

  • Filtruj pliki cookie, które zostaną zmodyfikowane. Wszystkie puste wpisy są ignorowane.

  • modyfikacja,

    RequestCookie

    Atrybuty, które mają zostać zastąpione w plikach cookie pasujących do filtra. Atrybuty ustawione na pusty ciąg znaków są usuwane.

EditResponseCookie

Edytuje co najmniej 1 plik cookie odpowiedzi. Zalecamy używanie interfejsu Cookies API, ponieważ jest on mniej kosztowny pod względem obliczeniowym.

Właściwości

FilterResponseCookie

Filtr pliku cookie w odpowiedziach HTTP.

Właściwości

  • ageLowerBound

    number opcjonalny

    Włącznie z dolną granicą czasu życia pliku cookie (w sekundach od bieżącego czasu). To kryterium spełniają tylko pliki cookie, których data ważności jest ustawiona na „teraz + ageLowerBound” lub późniejszą. Pliki cookie sesji nie spełniają kryteriów tego filtra. Okres ważności pliku cookie jest obliczany na podstawie atrybutów pliku cookie „max-age” lub „expires”. Jeśli podane są oba parametry, do obliczenia czasu życia pliku cookie używany jest parametr „max-age”.

  • ageUpperBound

    number opcjonalny

    Górna granica czasu życia pliku cookie (określona w sekundach od bieżącego czasu). To kryterium spełniają tylko pliki cookie, których data i godzina ważności mieszczą się w przedziale [teraz, teraz + ageUpperBound]. Pliki cookie sesji i pliki cookie, których data i godzina wygaśnięcia są w przeszłości, nie spełniają kryteriów tego filtra. Okres ważności pliku cookie jest obliczany na podstawie atrybutów pliku cookie „max-age” lub „expires”. Jeśli podane są oba parametry, do obliczenia czasu życia pliku cookie używany jest parametr „max-age”.

  • domena

    ciąg znaków opcjonalny

    Wartość atrybutu Domain pliku cookie.

  • traci ważność

    ciąg znaków opcjonalny

    Wartość atrybutu Expires pliku cookie.

  • httpOnly

    ciąg znaków opcjonalny

    Istnienie atrybutu pliku cookie HttpOnly.

  • maxAge

    number opcjonalny

    Wartość atrybutu Max-Age pliku cookie

  • nazwa

    ciąg znaków opcjonalny

    Nazwa pliku cookie.

  • ścieżka

    ciąg znaków opcjonalny

    Wartość atrybutu Path pliku cookie.

  • Bezpieczny

    ciąg znaków opcjonalny

    Istnienie atrybutu Secure cookie.

  • sessionCookie

    wartość logiczna opcjonalna

    Filtruje pliki cookie sesji. Pliki cookie sesji nie mają określonego czasu trwania w żadnym z atrybutów „max-age” ani „expires”.

  • wartość

    ciąg znaków opcjonalny

    Wartość pliku cookie, może być umieszczona w cudzysłowie prostym.

HeaderFilter

Filtruje nagłówki żądań według różnych kryteriów. Wiele kryteriów jest ocenianych jako koniunkcja.

Właściwości

  • nameContains

    string | string[] opcjonalnie

    Warunek jest spełniony, jeśli nazwa nagłówka zawiera wszystkie określone ciągi tekstowe.

  • nameEquals

    ciąg znaków opcjonalny

    Pasuje, jeśli nazwa nagłówka jest równa podanemu ciągowi tekstowemu.

  • namePrefix

    ciąg znaków opcjonalny

    Warunek jest spełniony, jeśli nazwa nagłówka zaczyna się od określonego ciągu znaków.

  • nameSuffix

    ciąg znaków opcjonalny

    Warunek jest spełniony, jeśli nazwa nagłówka kończy się określonym ciągiem znaków.

  • valueContains

    string | string[] opcjonalnie

    Dopasowuje, jeśli wartość nagłówka zawiera wszystkie określone ciągi znaków.

  • valueEquals

    ciąg znaków opcjonalny

    Pasuje, jeśli wartość nagłówka jest równa określonemu ciągowi znaków.

  • valuePrefix

    ciąg znaków opcjonalny

    Warunek jest spełniony, jeśli wartość nagłówka zaczyna się od określonego ciągu znaków.

  • valueSuffix

    ciąg znaków opcjonalny

    Pasuje, jeśli wartość nagłówka kończy się określonym ciągiem.

IgnoreRules

Maskuje wszystkie reguły, które spełniają określone kryteria.

Właściwości

  • konstruktor,

    pusty

    Funkcja constructor wygląda tak:

    (arg: IgnoreRules) => {...}

  • hasTag

    ciąg znaków opcjonalny

    Jeśli to ustawienie jest włączone, reguły z określonym tagiem są ignorowane. Ignorowanie nie jest trwałe i dotyczy tylko reguł i ich działań na tym samym etapie żądania sieciowego. Pamiętaj, że reguły są wykonywane w kolejności malejącej według priorytetu. To działanie ma wpływ na reguły o niższym priorytecie niż bieżąca reguła. Reguły o tym samym priorytecie mogą być ignorowane lub nie.

  • lowerPriorityThan

    number opcjonalny

    Jeśli ta opcja jest ustawiona, reguły o priorytecie niższym niż określona wartość są ignorowane. Ta granica nie jest trwała i wpływa tylko na reguły i ich działania na tym samym etapie żądania sieciowego.

RedirectByRegEx

Przekierowuje żądanie, stosując wyrażenie regularne do adresu URL. Wyrażenia regularne korzystają ze składni RE2.

Właściwości

  • konstruktor,

    pusty

    Funkcja constructor wygląda tak:

    (arg: RedirectByRegEx) => {...}

  • od

    tekst

    Wzorzec dopasowania, który może zawierać grupy przechwytywania. Grupy przechwytywania są przywoływane w składni Perla ($1, $2, …), a nie w składni RE2 (\1, \2, …), aby były bardziej podobne do wyrażeń regularnych JavaScriptu.

  • do

    tekst

    Wzorzec docelowy.

RedirectRequest

Deklaratywne działanie zdarzenia, które przekierowuje żądanie sieciowe.

Właściwości

RedirectToEmptyDocument

Deklaratywne działanie zdarzenia, które przekierowuje żądanie sieciowe do pustego dokumentu.

Właściwości

RedirectToTransparentImage

Deklaratywne działanie związane ze zdarzeniem, które przekierowuje żądanie sieciowe do przezroczystego obrazu.

Właściwości

RemoveRequestCookie

Usuwa co najmniej 1 plik cookie żądania. Zalecamy używanie interfejsu Cookies API, ponieważ jest on mniej kosztowny pod względem obliczeniowym.

Właściwości

RemoveRequestHeader

Usuwa nagłówek żądania o określonej nazwie. Nie używaj funkcji SetRequestHeader i RemoveRequestHeader z tą samą nazwą nagłówka w tym samym żądaniu. Każda nazwa nagłówka żądania występuje w każdym żądaniu tylko raz.

Właściwości

RemoveResponseCookie

Usuwa co najmniej 1 plik cookie z odpowiedzi. Zalecamy używanie interfejsu Cookies API, ponieważ jest on mniej kosztowny pod względem obliczeniowym.

Właściwości

RemoveResponseHeader

Usuwa wszystkie nagłówki odpowiedzi o określonych nazwach i wartościach.

Właściwości

  • konstruktor,

    pusty

    Funkcja constructor wygląda tak:

    (arg: RemoveResponseHeader) => {...}

  • nazwa

    tekst

    Nazwa nagłówka żądania HTTP (bez uwzględniania wielkości liter).

  • wartość

    ciąg znaków opcjonalny

    Wartość nagłówka żądania HTTP (wielkość liter nie jest rozróżniana).

RequestCookie

Filtr lub specyfikacja pliku cookie w żądaniach HTTP.

Właściwości

  • nazwa

    ciąg znaków opcjonalny

    Nazwa pliku cookie.

  • wartość

    ciąg znaków opcjonalny

    Wartość pliku cookie, może być umieszczona w cudzysłowie prostym.

RequestMatcher

Dopasowuje zdarzenia sieciowe według różnych kryteriów.

Właściwości

  • konstruktor,

    pusty

    Funkcja constructor wygląda tak:

    (arg: RequestMatcher) => {...}

  • contentType

    string[] opcjonalnie

    Warunek jest spełniony, jeśli typ MIME odpowiedzi (z nagłówka HTTP Content-Type) znajduje się na liście.

  • excludeContentType

    string[] opcjonalnie

    Warunek jest spełniony, jeśli typ MIME odpowiedzi (z nagłówka Content-Type HTTP) nie znajduje się na liście.

  • excludeRequestHeaders

    HeaderFilter[] optional

    Dopasowuje, jeśli żaden z nagłówków żądania nie pasuje do żadnego z filtrów nagłówków.

  • excludeResponseHeaders

    HeaderFilter[] optional

    Dopasowanie następuje, jeśli żaden z nagłówków odpowiedzi nie pasuje do żadnego z filtrów nagłówków.

  • firstPartyForCookiesUrl

    UrlFilter opcjonalny

    Wycofano

    Ignorowana od wersji 82.

    Dopasowuje, jeśli warunki UrlFilter są spełnione w przypadku adresu URL „źródła własnego” żądania. Adres URL „własnej domeny” w żądaniu, jeśli jest obecny, może się różnić od docelowego adresu URL żądania i określa, co jest uważane za „własną domenę” na potrzeby sprawdzania plików cookie przez inne firmy.

  • requestHeaders

    HeaderFilter[] optional

    Dopasowuje, jeśli niektóre nagłówki żądania pasują do jednego z filtrów nagłówków.

  • resourceType

    ResourceType[] opcjonalny

    Pasuje, jeśli typ żądania znajduje się na liście. Żądania, które nie pasują do żadnego z tych typów, zostaną odfiltrowane.

  • responseHeaders

    HeaderFilter[] optional

    Dopasowuje, jeśli niektóre nagłówki odpowiedzi są dopasowane przez jeden z filtrów nagłówków.

  • etapy

    Stage[] opcjonalny

    Zawiera listę ciągów znaków opisujących etapy. Dozwolone wartości to „onBeforeRequest”, „onBeforeSendHeaders”, „onHeadersReceived”, „onAuthRequired”. Jeśli ten atrybut jest obecny, ogranicza on odpowiednie etapy do tych, które są wymienione. Pamiętaj, że cały warunek ma zastosowanie tylko na etapach zgodnych ze wszystkimi atrybutami.

  • thirdPartyForCookies

    wartość logiczna opcjonalna

    Wycofano

    Ignorowana od wersji 87.

    Jeśli ma wartość „true”, pasuje do żądań podlegających zasadom dotyczącym plików cookie innych firm. Jeśli ma wartość „false”, pasuje do wszystkich innych żądań.

  • URL

    UrlFilter opcjonalny

    Dopasowuje, jeśli warunki UrlFilter są spełnione w przypadku adresu URL żądania.

ResponseCookie

Specyfikacja pliku cookie w odpowiedziach HTTP.

Właściwości

  • domena

    ciąg znaków opcjonalny

    Wartość atrybutu Domain pliku cookie.

  • traci ważność

    ciąg znaków opcjonalny

    Wartość atrybutu Expires pliku cookie.

  • httpOnly

    ciąg znaków opcjonalny

    Istnienie atrybutu pliku cookie HttpOnly.

  • maxAge

    number opcjonalny

    Wartość atrybutu Max-Age pliku cookie

  • nazwa

    ciąg znaków opcjonalny

    Nazwa pliku cookie.

  • ścieżka

    ciąg znaków opcjonalny

    Wartość atrybutu Path pliku cookie.

  • Bezpieczny

    ciąg znaków opcjonalny

    Istnienie atrybutu Secure cookie.

  • wartość

    ciąg znaków opcjonalny

    Wartość pliku cookie, może być umieszczona w cudzysłowie prostym.

SendMessageToExtension

Wywołuje zdarzenie declarativeWebRequest.onMessage.

Właściwości

SetRequestHeader

Ustawia nagłówek żądania o określonej nazwie na określoną wartość. Jeśli nagłówek o podanej nazwie nie istniał wcześniej, zostanie utworzony nowy. Porównanie nazw nagłówków zawsze uwzględnia wielkość liter. Każda nazwa nagłówka żądania występuje w każdym żądaniu tylko raz.

Właściwości

Stage

Typ wyliczeniowy

"onBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

"onAuthRequired"

Wydarzenia

onMessage

chrome.declarativeWebRequest.onMessage.addListener(
  callback: function,
)

Wyzwalane, gdy wiadomość jest wysyłana za pomocą declarativeWebRequest.SendMessageToExtension z działania interfejsu API deklaratywnych żądań sieciowych.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => void

    • szczegóły

      obiekt

      • documentId

        ciąg znaków opcjonalny

        Identyfikator UUID dokumentu, który wysłał żądanie.

      • Etap cyklu życia dokumentu.

      • frameId

        liczba

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

      • Typ ramki, w której nastąpiła nawigacja.

      • wiadomość

        tekst

        Wiadomość wysłana przez skrypt wywołujący.

      • method

        tekst

        Standardowa metoda HTTP.

      • parentDocumentId

        ciąg znaków opcjonalny

        UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma usługi nadrzędnej, wartość nie jest ustawiona.

      • 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. Dzięki temu można je wykorzystać do powiązania różnych zdarzeń w ramach tego samego żądania.

      • etapie

        Etap

        Etap żądania sieciowego, podczas którego zostało wywołane zdarzenie.

      • tabId

        liczba

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

      • timeStamp

        liczba

        Czas wywołania tego sygnału w milisekundach od początku epoki.

      • Jak będzie wykorzystywany żądany zasób.

      • URL

        tekst

onRequest

Udostępnia deklaratywny interfejs Event API, który składa się z funkcji addRules, removeRules i getRules.

Warunki

RequestMatcher

Działania

AddRequestCookie

AddResponseCookie

AddResponseHeader

CancelRequest

EditRequestCookie

EditResponseCookie

RedirectRequest

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

RemoveResponseCookie

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

SendMessageToExtension

IgnoreRules