chrome.declarativeWebRequest

Opis

Uwaga: ten interfejs API został wycofany. Zamiast tego zapoznaj się z interfejsem API declarativeNetRequest. Przechwytywać, blokować i modyfikować przesyłane żądania za pomocą interfejsu API chrome.declarativeWebRequest. Jest to znacznie szybsze niż chrome.webRequest API, ponieważ możesz rejestrować reguły, które są oceniane w przeglądarce, a nie mechanizm JavaScriptu, co skraca czas oczekiwania w obie strony i zwiększa wydajność.

Uprawnienia

declarativeWebRequest

Musisz zadeklarować parametr „declarativeWebRequest” uprawnienia w pliku manifestu rozszerzenia na korzystanie z tego API oraz uprawnienia hosta.

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

Dostępność

Wersja beta ≤ MV2

Plik manifestu

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

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

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

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

Jeśli na przykład "https://*.google.com/*" jest jedynym uprawnieniem hosta, które ma rozszerzenie, to takie uprawnienie rozszerzenie może skonfigurować regułę, aby:

  • Anuluj prośbę o połączenie z kontem https://www.google.com lub https://anything.else.com.
  • Wyślij wiadomość, gdy dotrzesz do: https://www.google.com, ale nie pod numer https://something.else.com.

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

Reguły

Interfejs deklaratywny interfejs API żądania internetowego jest zgodny z założeniami interfejsu deklaratywnego interfejsu API. Możesz zarejestrować się do obiektu zdarzenia chrome.declarativeWebRequest.onRequest.

Interfejs deklaratywny interfejs API żądania internetowego obsługuje jeden typ kryteriów dopasowania: RequestMatcher. Funkcja RequestMatcher pasuje do żądań sieciowych tylko wtedy, gdy są spełnione wszystkie wymienione kryteria. Poniżej Parametr RequestMatcher będzie pasować do żądania sieciowego, gdy użytkownik wpisze https://www.example.com w polu ominibox:

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

Ze względu na ten schemat żądania wysyłane do https://www.example.com będą odrzucane przez platformę RequestMatcher. Poza tym wszystkie żądania umieszczonego elementu iframe byłyby odrzucane z powodu błędu resourceType.

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

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

Aby anulować wszystkie prośby wysyłane do usług example.com i foobar.com, możesz dodać drugi warunek: , ponieważ każdy warunek jest wystarczający do wywołania wszystkich określonych działań:

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 deklaratywny interfejs API żądania internetowego jest zgodny z modelem cyklu życia żądań sieciowych utworzonym w następujący sposób: Request API. Oznacza to, że warunki można testować tylko na określonych etapach żądania internetowego Podobnie działania można wykonywać tylko na określonych etapach. W tabelach poniżej znajdziesz listę etapów żądania zgodnych z warunkami i działaniami.

Etapy żądania, na których mogą być przetwarzane atrybuty warunku.
Atrybut warunku onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
url ✓ ✓ ✓ ✓
resourceType ✓ ✓ ✓ ✓
contentType ✓
excludeContentType ✓
responseHeaders ✓
excludeResponseHeaders ✓
requestHeaders ✓
excludeRequestHeaders ✓
thirdPartyForCookies ✓ ✓ ✓ ✓
Etapy żądania, na 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żywaj priorytetów do zastępowania reguł

Reguły można powiązać z priorytetami w sposób opisany w interfejsie Events API. Mechanizmem tego może być używane do określania wyjątków. Ten przykład blokuje wszystkie żądania wysyłane do obrazów o nazwie evil.jpg z wyjątkiem serwera „mojserwer.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 w żądaniach etapów. Na każdym etapie żądania internetowego oceniane są wszystkie warunki wszystkich reguł. Jeśli Wykonano działanie IgnoreRules. Dotyczy ono tylko innych działań wykonywanych w przypadku tego samego żądania witryny na tym samym etapie.

Typy

AddRequestCookie

Dodaje do żądania plik cookie lub zastępuje plik cookie, jeśli istnieje już inny plik o tej samej nazwie. Warto pamiętać, że preferowane jest korzystanie z interfejsu Cookies API, ponieważ jest to mniej kosztowny pod względem obliczeń.

Właściwości

AddResponseCookie

Dodaje do odpowiedzi plik cookie lub zastępuje plik cookie, jeśli istnieje już inny plik o tej samej nazwie. Warto pamiętać, że preferowane jest korzystanie z interfejsu Cookies API, ponieważ jest to mniej kosztowny pod względem obliczeń.

Właściwości

AddResponseHeader

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

Właściwości

  • konstruktor

    nieważne

    Funkcja constructor wygląda tak: 

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

  • nazwa

    ciąg znaków

    Nazwa nagłówka odpowiedzi HTTP.

  • wartość

    ciąg znaków

    Wartość nagłówka odpowiedzi HTTP.

CancelRequest

Działanie deklaratywne, które anuluje żądanie sieciowe.

Właściwości

EditRequestCookie

Umożliwia edycję co najmniej jednego pliku cookie żądania. Warto pamiętać, że preferowane jest korzystanie z interfejsu Cookies API, ponieważ jest to mniej kosztowny pod względem obliczeń.

Właściwości

  • konstruktor

    nieważne

    Funkcja constructor wygląda tak: 

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

  • Filtr plików cookie, które zostaną zmodyfikowane. Wszystkie puste wpisy są ignorowane.

  • modyfikacja

    RequestCookie

    Atrybuty, które powinny zostać zastąpione w plikach cookie zawierających filtr. Atrybuty ustawione jako pusty ciąg znaków są usuwane.

EditResponseCookie

Edytuje co najmniej jeden plik cookie odpowiedzi. Warto pamiętać, że preferowane jest korzystanie z interfejsu Cookies API, ponieważ jest to mniej kosztowny pod względem obliczeń.

Właściwości

FilterResponseCookie

Filtr pliku cookie w odpowiedziach HTTP.

Właściwości

  • ageLowerBound

    liczba opcjonalnie

    Dolna granica uwzględniająca czas trwania pliku cookie (określana w sekundach po aktualnej godzinie). Tylko pliki cookie, których data i godzina wygaśnięcia jest ustawione na „teraz + ageLowerBound” spełnić to kryterium. Pliki cookie sesji nie spełniają kryterium tego filtra. Czas trwania pliku cookie jest obliczany na podstawie wartości „max-age” lub „wygasa” plików cookie. Jeśli określono obie wartości, „max-age” służy do obliczania czasu przechowywania pliku cookie.

  • ageUpperBound

    liczba opcjonalnie

    Górna granica uwzględniająca czas trwania pliku cookie (określana w sekundach po aktualnej godzinie). Tylko pliki cookie, których data i godzina wygaśnięcia mieszczą się w przedziale [teraz, now + ageUpperBound], spełniają to kryterium. Pliki cookie sesji oraz pliki cookie, których data ważności i godzina przypada w przeszłości, nie spełniają kryterium tego filtra. Czas trwania pliku cookie jest obliczany na podstawie wartości „max-age” lub „wygasa” plików cookie. Jeśli określono obie wartości, „max-age” służy do obliczania czasu przechowywania pliku cookie.

  • domena

    ciąg znaków opcjonalny

    Wartość atrybutu pliku cookie domeny.

  • traci ważność

    ciąg znaków opcjonalny

    Wartość atrybutu Wygasający plik cookie.

  • httpOnly

    ciąg znaków opcjonalny

    Występowanie atrybutu HttpOnly cookie.

  • maxAge

    liczba opcjonalnie

    Wartość atrybutu pliku cookie Max-Age

  • nazwa

    ciąg znaków opcjonalny

    Nazwa pliku cookie.

  • ścieżka

    ciąg znaków opcjonalny

    Wartość atrybutu pliku cookie ścieżki.

  • Bezpieczny

    ciąg znaków opcjonalny

    Obecność atrybutu Bezpieczny plik cookie.

  • sessionCookie

    Wartość logiczna opcjonalna

    Filtruje pliki cookie sesji. Pliki cookie sesji nie mają czasu trwania w żadnej wartości z wartości „max-age” lub „wygasa” .

  • wartość

    ciąg znaków opcjonalny

    Wartość w pliku cookie można doprecyzować w podwójnym cudzysłowie.

HeaderFilter

Filtruje nagłówki żądań pod kątem różnych kryteriów. Kilka kryteriów jest sprawdzanych jako spójnik.

Właściwości

  • nameContains

    string | string[] opcjonalnie

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

  • nameEquals

    ciąg znaków opcjonalny

    Dopasowuje, jeśli nazwa nagłówka jest równa określonemu ciągowi znaków.

  • namePrefix

    ciąg znaków opcjonalny

    Pasuje, jeśli nazwa nagłówka zaczyna się od określonego ciągu.

  • nameSuffix

    ciąg znaków opcjonalny

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

  • valueContains

    string | string[] opcjonalnie

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

  • valueEquals

    ciąg znaków opcjonalny

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

  • valuePrefix

    ciąg znaków opcjonalny

    Dopasowuje, jeśli wartość nagłówka zaczyna się określonym ciągiem znaków.

  • valueSuffix

    ciąg znaków opcjonalny

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

IgnoreRules

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

Właściwości

  • konstruktor

    nieważne

    Funkcja constructor wygląda tak: 

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

  • hasTag

    ciąg znaków opcjonalny

    Jeśli zasada jest skonfigurowana, reguły z określonym tagiem są ignorowane. To ignorowanie nie jest trwałe. Ma wpływ tylko na reguły i ich działania na tym samym etapie żądania sieciowego. Pamiętaj, że reguły są wykonywane w kolejności malejącej według priorytetów. To działanie 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

    liczba opcjonalnie

    Jeśli zasada jest skonfigurowana, reguły o niższym priorytecie niż określona wartość są ignorowane. Ta granica nie jest zachowywana. Ma wpływ tylko na reguły i ich działania na tym samym etapie żądania sieciowego.

RedirectByRegEx

Przekierowuje żądanie przez zastosowanie w adresie URL wyrażenia regularnego. Wyrażenia regularne używają składni RE2.

Właściwości

  • konstruktor

    nieważne

    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 Perl ($1, $2, ...), a nie w składni RE2 (\1, \2, ...), co jest bliższe wyrażeniam regularnym JavaScript.

  •  

    ciąg znaków

    Wzorzec miejsca docelowego.

RedirectRequest

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

Właściwości

  • konstruktor

    nieważne

    Funkcja constructor wygląda tak: 

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

  • redirectUrl

    ciąg znaków

    Miejsce docelowe, do którego następuje przekierowanie żądania.

RedirectToEmptyDocument

Akcja zdarzenia deklaratywnego, która przekierowuje żądanie sieciowe do pustego dokumentu.

Właściwości

RedirectToTransparentImage

Działanie deklaratywne, które przekierowuje żądanie sieciowe do przezroczystego obrazu.

Właściwości

RemoveRequestCookie

Usuwa co najmniej 1 plik cookie żądania. Warto pamiętać, że preferowane jest korzystanie z interfejsu Cookies API, ponieważ jest to mniej kosztowny pod względem obliczeń.

Właściwości

RemoveRequestHeader

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

Właściwości

RemoveResponseCookie

Usuwa co najmniej 1 plik cookie odpowiedzi. Warto pamiętać, że preferowane jest korzystanie z interfejsu Cookies API, ponieważ jest to mniej kosztowny pod względem obliczeń.

Właściwości

RemoveResponseHeader

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

Właściwości

  • konstruktor

    nieważne

    Funkcja constructor wygląda tak: 

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

  • nazwa

    ciąg znaków

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

  • 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ść w pliku cookie można doprecyzować w podwójnym cudzysłowie.

RequestMatcher

Dopasowuje zdarzenia sieciowe na podstawie różnych kryteriów.

Właściwości

  • konstruktor

    nieważne

    Funkcja constructor wygląda tak: 

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

  • contentType

    string[] opcjonalnie

    Dopasowuje, jeśli na liście znajduje się typ multimediów MIME odpowiedzi (z nagłówka HTTP Content-Type).

  • excludeContentType

    string[] opcjonalnie

    Dopasowuje, jeśli typ multimediów MIME odpowiedzi (z nagłówka HTTP Content-Type) nie jest uwzględniony na liście.

  • excludeRequestHeaders

    HeaderFilter[] opcjonalny

    Dopasowuje się, jeśli żaden z nagłówków żądania nie jest zgodny przez żaden z filtrów nagłówków.

  • excludeResponseHeaders

    HeaderFilter[] opcjonalny

    Dopasowuje się, jeśli żaden z nagłówków odpowiedzi nie jest zgodny przez żaden z filtrów nagłówków.

  • firstPartyForCookiesUrl

    UrlFilter opcjonalny

    Wycofano

    Ignorowana od wersji 82.

    Pasuje, jeśli dla parametru „własna” zostaną spełnione warunki filtra UrlFilter Adres URL żądania. „Własne segmenty odbiorców” Adres URL żądania (jeśli istnieje) może się różnić od docelowego adresu URL żądania i określa, co jest uważane za „własne” zamiast sprawdzania plików cookie przez inne firmy.

  • requestHeaders

    HeaderFilter[] opcjonalny

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

  • resourceType

    ResourceType[] opcjonalny

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

  • responseHeaders

    HeaderFilter[] opcjonalny

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

  • etapy

    Etap[] opcjonalny

    Zawiera listę ciągów tekstowych opisujących etapy. Dozwolone wartości to „onBeforeRequest”, „onBeforeSendHeaders”, „onHeadersReceived”, „onAuthRequired”. Jeśli ten atrybut występuje, ogranicza odpowiednie etapy do tych wymienionych. Pamiętaj, że cały warunek ma zastosowanie tylko do etapów zgodnych ze wszystkimi atrybutami.

  • thirdPartyForCookies

    Wartość logiczna opcjonalna

    Wycofano

    Ignorowana od wersji 87.

    Jeśli ma wartość Prawda, dopasowuje żądania, które podlegają zasadom dotyczącym plików cookie innych firm. Jeśli ma wartość Fałsz, dopasowuje wszystkie inne żądania.

  • URL

    UrlFilter opcjonalny

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

ResponseCookie

Specyfikacja pliku cookie w odpowiedziach HTTP.

Właściwości

  • domena

    ciąg znaków opcjonalny

    Wartość atrybutu pliku cookie domeny.

  • traci ważność

    ciąg znaków opcjonalny

    Wartość atrybutu Wygasający plik cookie.

  • httpOnly

    ciąg znaków opcjonalny

    Występowanie atrybutu HttpOnly cookie.

  • maxAge

    liczba opcjonalnie

    Wartość atrybutu pliku cookie Max-Age

  • nazwa

    ciąg znaków opcjonalny

    Nazwa pliku cookie.

  • ścieżka

    ciąg znaków opcjonalny

    Wartość atrybutu pliku cookie ścieżki.

  • Bezpieczny

    ciąg znaków opcjonalny

    Obecność atrybutu Bezpieczny plik cookie.

  • wartość

    ciąg znaków opcjonalny

    Wartość pliku cookie można doprecyzować w podwójnym cudzysłowie.

SendMessageToExtension

Wyzwala zdarzenie declarativeWebRequest.onMessage.

Właściwości

SetRequestHeader

Ustawia określoną wartość w nagłówku żądania o określonej nazwie. Jeśli nagłówek o takiej nazwie nie istniał wcześniej, tworzony jest nowy. W porównaniu nazwy nagłówka wielkość liter zawsze nie jest rozróżniana. Każda nazwa nagłówka żądania występuje tylko raz w każdym żądaniu.

Właściwości

  • konstruktor

    nieważne

    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,
)

Uruchamiane, gdy wiadomość jest wysyłana przez declarativeWebRequest.SendMessageToExtension w wyniku działania interfejsu API deklaratywnego żądania internetowego.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (details: object) => void

    • szczegóły

      Obiekt

      • documentId

        ciąg znaków opcjonalny

        Identyfikator UUID dokumentu, z którego wysłano żądanie.

      • Cykl życia dokumentu.

      • frameId

        liczba

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

      • Typ ramki, w której wystą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

        Identyfikator UUID dokumentu nadrzędnego, w którym znajduje się ta ramka. Ta wartość nie jest ustawiona, jeśli nie ma elementu nadrzędnego.

      • parentFrameId

        liczba

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

      • requestId

        ciąg znaków

        Identyfikator żądania. Identyfikatory żądań są unikalne w obrębie sesji przeglądarki. Dzięki temu można je wykorzystać do powiązania różnych zdarzeń w tym samym żądaniu.

      • etapie

        Etap

        Etap żądania sieciowego, na którym zostało wywołane zdarzenie.

      • tabId

        liczba

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

      • 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 interfejs Deklaratywny interfejs API zdarzeń, który składa się z zasad 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