chrome.declarativeWebRequest

Opis

Uwaga: ten interfejs API został wycofany. Zamiast tego skorzystaj z interfejsu API declarativeNetRequest. Użyj interfejsu chrome.declarativeWebRequest API, aby przechwytywać, blokować lub modyfikować żądania w trakcie ich przesyłania. Jest on znacznie szybszy niż chrome.webRequest API, ponieważ możesz rejestrować reguły, które są oceniane w przeglądarce, a nie w silniku JavaScript, co zmniejsza 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 wraz z uprawnieniami dotyczącymi hosta.

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

Dostępność

Wersja beta ≤ MV2

Plik manifestu

Pamiętaj, że niektóre typy działań niewrażliwych 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ć komunikat w odpowiedzi na żądania sieciowe.

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 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: RequestMatcher. Symbol RequestMatcher pasuje do żądań sieciowych tylko wtedy, gdy spełnione są wszystkie wymienione kryteria. Poniższy ciąg znaków RequestMatcher będzie pasować do żądania sieci, gdy użytkownik wpisze https://www.example.com w pasku adresu:

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 schemat. Wszystkie żądania dotyczące osadzonego elementu iframe będą odrzucane z powodu resourceType.

Aby anulować wszystkie żądania do „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 z nich 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 internetowego, 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 sekcji Interfejs Events API. Ten mechanizm może służyć do wyrażania wyjątków. Poniższy przykład blokuje wszystkie żądania dotyczące obrazów o nazwie evil.jpg, z 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 sprawdzane są 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. Pamiętaj, że zalecamy korzystanie z 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. Pamiętaj, że zalecamy korzystanie z 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. Ponieważ wiele nagłówków odpowiedzi może mieć tę samą nazwę, aby zastąpić jeden z nich, musisz najpierw go usunąć, a potem dodać nowy nagłówek odpowiedzi.

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 w żądaniu. Pamiętaj, że zalecamy korzystanie z 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. Pamiętaj, że zalecamy korzystanie z 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

    Dolna granica czasu życia pliku cookie (określona 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ą. Ciasteczka 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 atrybuty, do obliczenia czasu życia pliku cookie używany jest atrybut „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 wygaśnięcia 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 atrybuty, do obliczenia czasu życia pliku cookie używany jest atrybut „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 życia 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[] opcjonalny

    Zwraca dopasowanie, jeśli nazwa nagłówka zawiera wszystkie określone ciągi.

  • 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

    Pasuje, 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[] opcjonalny

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

  • valueEquals

    ciąg znaków opcjonalny

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

  • valuePrefix

    ciąg znaków opcjonalny

    Dopasowuje, jeśli wartość nagłówka zaczyna się od określonego ciągu.

  • valueSuffix

    ciąg znaków opcjonalny

    Dopasowuje, 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. 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. Ta czynność wpływa 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 skonfigurowana, reguły o niższym priorytecie 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

    ciąg znaków

    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 JavaScript.

  • do

    ciąg znaków

    Wzorzec miejsca docelowego.

RedirectRequest

Deklaratywne działanie związane ze zdarzeniem, 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 z wydarzeniem, które przekierowuje żądanie sieciowe do przezroczystego obrazu.

Właściwości

RemoveRequestCookie

Usuwa co najmniej 1 plik cookie żądania. Pamiętaj, że zalecamy korzystanie z 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. Pamiętaj, że zalecamy korzystanie z 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

    ciąg znaków

    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[] opcjonalny

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

  • excludeContentType

    string[] opcjonalny

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

  • excludeRequestHeaders

    HeaderFilter[] opcjonalnie

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

  • excludeResponseHeaders

    HeaderFilter[] opcjonalnie

    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

    Ignorowane od wersji 82.

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

  • requestHeaders

    HeaderFilter[] opcjonalnie

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

  • resourceType

    ResourceType[] opcjonalny

    Dopasowuje, jeśli typ żądania jest zawarty na liście. Żądania, które nie pasują do żadnego z tych typów, zostaną odfiltrowane.

  • responseHeaders

    HeaderFilter[] opcjonalnie

    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”, dopasowuje żądania, które podlegają 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

  • konstruktor

    pusty

    Funkcja constructor wygląda tak:

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

  • nazwa

    ciąg znaków

    Nazwa nagłówka żądania HTTP.

  • wartość

    ciąg znaków

    Wartość nagłówka żądania HTTP.

Stage

Typ wyliczeniowy

"onBeforeRequest"

"onBeforeSendHeaders"

„onHeadersReceived”

„onAuthRequired”

Wydarzenia

onMessage

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

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

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => void

    • szczegóły

      obiekt

      • documentId

        ciąg znaków opcjonalny

        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 oznacza identyfikator ramki podrzędnej, w której jest wysyłane żądanie. Jeśli dokument ramki (lub podramki) 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 obrębie karty.

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

      • wiadomość

        ciąg znaków

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

      • method

        ciąg znaków

        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, ten parametr nie jest ustawiony.

      • parentFrameId

        liczba

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

      • requestId

        ciąg znaków

        Identyfikator żądania. Identyfikatory żądań są unikalne w ramach sesji przeglądarki. 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.

      • Sposób wykorzystania żądanego zasobu.

      • URL

        ciąg znaków

onRequest

Udostępnia deklaratywny interfejs API zdarzeń, 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