chrome.webRequest

Opis

Użyj interfejsu chrome.webRequest API, aby obserwować i analizować ruch oraz przechwytywać, blokować lub modyfikować żądania w trakcie przesyłania.

Uprawnienia

webRequest

Aby używać interfejsu Web Request API, musisz zadeklarować uprawnienie "webRequest" w manifeście rozszerzenia wraz z niezbędnymi uprawnieniami dotyczącymi hosta. Aby przechwycić żądanie zasobu podrzędnego, rozszerzenie musi mieć dostęp zarówno do żądanego adresu URL, jak i do jego inicjatora. Na przykład:

{
  "name": "My extension",
  ...
  "permissions": [
    "webRequest"
  ],
  "host_permissions": [
    "*://*.google.com/*"
  ],
  ...
}

webRequestBlocking

Wymagane do rejestrowania modułów obsługi zdarzeń blokujących. Od wersji Manifest V3 jest to dostępne tylko w przypadku rozszerzeń zainstalowanych na podstawie zasad.

webRequestAuthProvider

Wymagane do użycia metody onAuthRequired. Zobacz Obsługa uwierzytelniania.

Pojęcia i zastosowanie

Cykl życia żądań

Interfejs API żądania internetowego definiuje zestaw zdarzeń, które następują po sobie w cyklu życia żądania internetowego. Możesz używać tych zdarzeń do obserwowania i analizowania ruchu. Niektóre zdarzenia synchroniczne umożliwiają przechwytywanie, blokowanie lub modyfikowanie żądania.

Cykl życia zdarzenia w przypadku udanych żądań jest przedstawiony poniżej, a następnie podano definicje zdarzeń:

Cykl życia żądania internetowego z perspektywy interfejsu webrequest API

onBeforeRequest (opcjonalnie synchroniczne)
Uruchamiane, gdy ma nastąpić żądanie. To zdarzenie jest wysyłane przed nawiązaniem połączenia TCP i może służyć do anulowania lub przekierowywania żądań.
onBeforeSendHeaders (opcjonalnie synchroniczne)
Uruchamia się, gdy ma nastąpić wysłanie żądania i przygotowane zostały nagłówki początkowe. To zdarzenie umożliwia rozszerzeniom dodawanie, modyfikowanie i usuwanie nagłówków żądań (*). Zdarzenie onBeforeSendHeaders jest przekazywane do wszystkich subskrybentów, więc różni subskrybenci mogą próbować modyfikować żądanie. Sposób obsługi tego procesu znajdziesz w sekcji Szczegóły implementacji. To zdarzenie może służyć do anulowania prośby.
onSendHeaders
Wywoływane po tym, jak wszystkie rozszerzenia zmodyfikują nagłówki żądania, i przedstawia ostateczną wersję(*). Zdarzenie jest wywoływane przed wysłaniem nagłówków do sieci. To zdarzenie ma charakter informacyjny i jest obsługiwane asynchronicznie. Nie można jej modyfikować ani anulować.
onHeadersReceived (opcjonalnie synchroniczne)
Wywoływany za każdym razem, gdy otrzymywany jest nagłówek odpowiedzi HTTP(S). Ze względu na przekierowania i żądania uwierzytelniania może się to zdarzyć wielokrotnie w przypadku jednego żądania. To zdarzenie umożliwia rozszerzeniom dodawanie, modyfikowanie i usuwanie nagłówków odpowiedzi, takich jak przychodzące nagłówki Content-Type. Dyrektywy buforowania są przetwarzane przed wywołaniem tego zdarzenia, więc modyfikowanie nagłówków takich jak Cache-Control nie ma wpływu na pamięć podręczną przeglądarki. Umożliwia też anulowanie lub przekierowanie żądania.
onAuthRequired (opcjonalnie synchroniczne)
Występuje, gdy żądanie wymaga uwierzytelnienia użytkownika. To zdarzenie może być obsługiwane synchronicznie, aby dostarczać dane uwierzytelniające. Pamiętaj, że rozszerzenia mogą podawać nieprawidłowe dane logowania. Uważaj, aby nie wpaść w nieskończoną pętlę, wielokrotnie podając nieprawidłowe dane logowania. Możesz też użyć tej metody, aby anulować prośbę.
onBeforeRedirect
Wywoływane, gdy ma nastąpić przekierowanie. Przekierowanie może być wywołane przez kod odpowiedzi HTTP lub przez rozszerzenie. To zdarzenie ma charakter informacyjny i jest obsługiwane asynchronicznie. Nie możesz modyfikować ani anulować prośby.
onResponseStarted
Wywoływane, gdy zostanie odebrany pierwszy bajt treści odpowiedzi. W przypadku żądań HTTP oznacza to, że dostępne są wiersz stanu i nagłówki odpowiedzi. To zdarzenie ma charakter informacyjny i jest obsługiwane asynchronicznie. Nie można jej zmienić ani anulować.
onCompleted
Wywoływane, gdy żądanie zostało przetworzone.
onErrorOccurred
Wywoływane, gdy nie udało się przetworzyć żądania.

Interfejs Web Request API gwarantuje, że w przypadku każdego żądania jako zdarzenie końcowe zostanie wywołane zdarzenie onCompleted lub onErrorOccurred, z jednym wyjątkiem: jeśli żądanie zostanie przekierowane na adres URL data://, ostatnim zgłoszonym zdarzeniem będzie onBeforeRedirect.

* Pamiętaj, że interfejs API żądań internetowych udostępnia rozszerzeniu abstrakcję stosu sieciowego. Wewnętrznie jedno żądanie adresu URL może zostać podzielone na kilka żądań HTTP (np. w celu pobrania poszczególnych zakresów bajtów z dużego pliku) lub może być obsługiwane przez stos sieciowy bez komunikacji z siecią. Z tego powodu interfejs API nie udostępnia końcowych nagłówków HTTP, które są wysyłane do sieci. Na przykład wszystkie nagłówki związane z pamięcią podręczną są niewidoczne dla rozszerzenia.

Te nagłówki nie są obecnie przekazywane do zdarzenia onBeforeSendHeaders. Nie gwarantujemy, że ta lista jest kompletna lub stabilna.

  • Autoryzacja
  • Cache-Control
  • Połączenie
  • Content-Length
  • Host
  • If-Modified-Since
  • If-None-Match
  • If-Range
  • Partial-Data
  • Pragma
  • Proxy-Authorization
  • Proxy-Connection
  • Transfer-Encoding

Od Chrome 79 modyfikacje nagłówka żądania wpływają na sprawdzanie współdzielenia zasobów między serwerami z różnych domen (CORS). Jeśli zmodyfikowane nagłówki żądań dotyczących zasobów z innej domeny nie spełniają kryteriów, spowoduje to wysłanie procesu wstępnego CORS, aby zapytać serwer, czy takie nagłówki mogą zostać zaakceptowane. Jeśli naprawdę musisz zmodyfikować nagłówki w sposób naruszający protokół CORS, musisz określić 'extraHeaders' w opt_extraInfoSpec. Z drugiej strony modyfikacje nagłówków odpowiedzi nie działają w celu oszukania sprawdzania CORS. Jeśli chcesz oszukać protokół CORS, musisz też określić 'extraHeaders' w przypadku modyfikacji odpowiedzi.

Od Chrome w wersji 79 interfejs API webRequest domyślnie nie przechwytuje żądań wstępnych CORS ani odpowiedzi na nie. Proces wstępny CORS dla adresu URL żądania jest widoczny dla rozszerzenia, jeśli w przypadku tego adresu URL w opt_extraInfoSpec jest określony odbiornik z 'extraHeaders'. onBeforeRequest może też pobierać 'extraHeaders' z Chrome 79.

Od Chrome 79 ten nagłówek żądania nie jest podawany i nie można go modyfikować ani usuwać bez określenia 'extraHeaders' w opt_extraInfoSpec:

  • Punkt początkowy

Od Chrome 72, jeśli chcesz modyfikować odpowiedzi, zanim Cross Origin Read Blocking (CORB) zablokuje odpowiedź, musisz określić 'extraHeaders' w opt_extraInfoSpec.

Od Chrome 72 te nagłówki żądań nie są udostępniane i nie można ich modyfikować ani usuwać bez określenia 'extraHeaders' w opt_extraInfoSpec:

  • Accept-Language
  • Accept-Encoding
  • Referer
  • Plik cookie

Od Chrome 72 nagłówek odpowiedzi Set-Cookie nie jest podawany i nie można go modyfikować ani usuwać bez określenia 'extraHeaders' w opt_extraInfoSpec.

Od Chrome 89 nie można skutecznie modyfikować ani usuwać nagłówka odpowiedzi X-Frame-Options bez określania 'extraHeaders' w opt_extraInfoSpec.

Interfejs webRequest API udostępnia tylko żądania, które rozszerzenie ma uprawnienia do wyświetlania na podstawie uprawnień hosta. Dostępne są tylko te schematy: http://, https://, ftp://, file://, ws:// (od Chrome 58), wss:// (od Chrome 58), urn: (od Chrome 91) lub chrome-extension://. Ponadto ukrywane są nawet niektóre żądania z adresami URL korzystającymi z jednego z powyższych schematów. Obejmują one chrome-extension://other_extension_id, gdzie other_extension_id nie jest identyfikatorem rozszerzenia, które ma obsłużyć żądanie, https://www.google.com/chrome i inne wrażliwe żądania związane z podstawowymi funkcjami przeglądarki. Synchroniczne żądania XMLHttpRequests z rozszerzenia są też ukrywane przed blokującymi modułami obsługi zdarzeń, aby zapobiec zakleszczeniom. Pamiętaj, że w przypadku niektórych obsługiwanych schematów zestaw dostępnych zdarzeń może być ograniczony ze względu na charakter odpowiedniego protokołu. Na przykład w przypadku pliku scheme można wysyłać tylko onBeforeRequest, onResponseStarted, onCompleted i onErrorOccurred.

Od Chrome 58 interfejs webRequest API obsługuje przechwytywanie żądania uzgodnienia połączenia WebSocket. Uzgadnianie połączenia odbywa się za pomocą żądania uaktualnienia HTTP, więc jego przepływ pasuje do modelu webRequest zorientowanego na HTTP. Pamiętaj, że interfejs API nie przechwytuje:

  • Poszczególne wiadomości wysyłane przez nawiązane połączenie WebSocket.
  • WebSocket zamyka połączenie.

Przekierowania nie są obsługiwane w przypadku żądań WebSocket.

Od Chrome 72 rozszerzenie może przechwycić żądanie tylko wtedy, gdy ma uprawnienia hosta zarówno do żądanego adresu URL, jak i do inicjatora żądania.

Od Chrome w wersji 96 interfejs WebRequest API obsługuje przechwytywanie żądania uzgadniania WebTransport przez HTTP/3. Ponieważ uzgadnianie jest przeprowadzane za pomocą żądania HTTP CONNECT, jego przepływ pasuje do modelu webRequest zorientowanego na HTTP. Uwaga:

  • Po nawiązaniu sesji rozszerzenia nie mogą obserwować sesji ani w nią ingerować za pomocą interfejsu WebRequest API.
  • Modyfikowanie nagłówków żądań HTTP w onBeforeSendHeaders jest ignorowane.
  • Przekierowania i uwierzytelnianie nie są obsługiwane w WebTransport przez HTTP/3.

Identyfikatory żądań

Każde żądanie jest identyfikowane za pomocą identyfikatora żądania. Ten identyfikator jest unikalny w ramach sesji przeglądarki i kontekstu rozszerzenia. Pozostaje on stały przez cały cykl życia żądania i może służyć do dopasowywania zdarzeń do tego samego żądania. Pamiętaj, że w przypadku przekierowania HTTP lub uwierzytelniania HTTP kilka żądań HTTP jest mapowanych na 1 żądanie internetowe.

Rejestrowanie detektorów zdarzeń

Aby zarejestrować odbiornik zdarzeń dla żądania internetowego, użyj odmiany zwykłej addListener() funkcji. Oprócz określenia funkcji wywołania zwrotnego musisz podać argument filtra, a opcjonalnie możesz też podać argument dodatkowych informacji.

3 argumenty interfejsu API żądania internetowego addListener() mają te definicje:

var callback = function(details) {...};
var filter = {...};
var opt_extraInfoSpec = [...];

Oto przykład nasłuchiwania zdarzenia onBeforeRequest:

chrome.webRequest.onBeforeRequest.addListener(
    callback, filter, opt_extraInfoSpec);

Każde wywołanie addListener() przyjmuje jako pierwszy parametr obowiązkową funkcję wywołania zwrotnego. Ta funkcja wywołania zwrotnego otrzymuje słownik zawierający informacje o bieżącym żądaniu adresu URL. Informacje w tym słowniku zależą od konkretnego typu zdarzenia oraz zawartości opt_extraInfoSpec.

Jeśli opcjonalna tablica opt_extraInfoSpec zawiera ciąg znaków 'blocking' (dozwolony tylko w przypadku określonych wydarzeń), funkcja wywołania zwrotnego jest obsługiwana synchronicznie. Oznacza to, że żądanie jest blokowane do momentu, gdy funkcja wywołania zwrotnego zwróci wartość. W takim przypadku funkcja zwrotna może zwrócić wartość webRequest.BlockingResponse, która określa dalszy cykl życia żądania. W zależności od kontekstu ta odpowiedź umożliwia anulowanie lub przekierowanie żądania (onBeforeRequest), anulowanie żądania lub zmodyfikowanie nagłówków (onBeforeSendHeaders, onHeadersReceived) oraz anulowanie żądania lub podanie danych uwierzytelniających (onAuthRequired).

Jeśli opcjonalna tablica opt_extraInfoSpec zawiera ciąg 'asyncBlocking' (dozwolony tylko w przypadku onAuthRequired), rozszerzenie może wygenerować webRequest.BlockingResponse asynchronicznie.

webRequest.RequestFilter filter umożliwia ograniczenie żądań, w przypadku których zdarzenia są wywoływane w różnych wymiarach:

Adresy URL
Wzorce adresów URL, np. *://www.google.com/foo*bar.
Typy
Typy żądań, takie jak main_frame (dokument wczytywany w ramce najwyższego poziomu), sub_frame (dokument wczytywany w ramce wbudowanej) i image (obraz w witrynie). Zobacz webRequest.RequestFilter.
Identyfikator karty
Identyfikator jednej karty.
Identyfikator okna
Identyfikator okna.

W zależności od typu zdarzenia możesz określić ciągi znaków w opt_extraInfoSpec, aby poprosić o dodatkowe informacje o żądaniu. Służy do podawania szczegółowych informacji o danych żądania tylko wtedy, gdy jest to wyraźnie wymagane.

Obsługa uwierzytelniania

Aby obsługiwać żądania uwierzytelniania HTTP, dodaj do pliku manifestu uprawnienie "webRequestAuthProvider":

{
  "permissions": [
    "webRequest",
    "webRequestAuthProvider"
  ]
}

Pamiętaj, że to uprawnienie nie jest wymagane w przypadku rozszerzenia zainstalowanego zgodnie z zasadami, które ma uprawnienie "webRequestBlocking".

Aby podać dane logowania synchronicznie:

chrome.webRequest.onAuthRequired.addListener((details) => {
    return {
      authCredentials: {
        username: 'guest',
        password: 'guest'
      }
    };
  },
  { urls: ['https://httpbin.org/basic-auth/guest/guest'] },
  ['blocking']
);

Aby podać dane logowania asynchronicznie:

chrome.webRequest.onAuthRequired.addListener((details, callback) => {
    callback({
      authCredentials: {
        username: 'guest',
        password: 'guest'
      }
    });
  },
  { urls: ['https://httpbin.org/basic-auth/guest/guest'] },
  ['asyncBlocking']
);

Szczegóły implementacji

Podczas tworzenia rozszerzenia korzystającego z interfejsu API żądań internetowych warto poznać kilka ważnych szczegółów implementacji:

web_accessible_resources

Gdy rozszerzenie używa interfejsów API webRequest do przekierowania żądania zasobu publicznego do zasobu, który nie jest dostępny w internecie, jest blokowane i powoduje błąd. Powyższe zasady obowiązują nawet wtedy, gdy zasób, który nie jest dostępny w internecie, należy do rozszerzenia przekierowującego. Aby zadeklarować zasoby do użycia z interfejsami declarativeWebRequest API, w pliku manifestu należy zadeklarować i wypełnić tablicę "web_accessible_resources" zgodnie z dokumentacją dostępną tutaj.

Rozwiązywanie konfliktów

W obecnej implementacji interfejsu Web Request API żądanie jest uznawane za anulowane, jeśli co najmniej jedno rozszerzenie wyda polecenie anulowania żądania. Jeśli rozszerzenie anuluje żądanie, wszystkie rozszerzenia otrzymają powiadomienie w postaci zdarzenia onErrorOccurred. Tylko jedno rozszerzenie może przekierować żądanie lub zmodyfikować nagłówek w danym momencie. Jeśli więcej niż jedno rozszerzenie próbuje zmodyfikować żądanie, wygrywa rozszerzenie zainstalowane jako ostatnie, a wszystkie pozostałe są ignorowane. Rozszerzenie nie otrzymuje powiadomienia, jeśli jego instrukcja modyfikacji lub przekierowania została zignorowana.

Buforowanie

Chrome korzysta z 2 rodzajów pamięci podręcznej: na dysku i bardzo szybkiej w pamięci. Czas życia pamięci podręcznej w pamięci jest powiązany z czasem życia procesu renderowania, który w przybliżeniu odpowiada karcie. Żądania, na które odpowiada pamięć podręczna, są niewidoczne dla interfejsu Web Request API. Jeśli moduł obsługi żądań zmieni swoje działanie (np. sposób blokowania żądań), proste odświeżenie strony może nie uwzględnić tej zmiany. Aby mieć pewność, że zmiana zachowania zostanie wprowadzona, wywołaj funkcję handlerBehaviorChanged(), aby wyczyścić pamięć podręczną. Nie rób tego jednak zbyt często, ponieważ czyszczenie pamięci podręcznej jest bardzo kosztowną operacją. Po zarejestrowaniu lub wyrejestrowaniu detektora zdarzeń nie musisz wywoływać funkcji handlerBehaviorChanged().

Sygnatury czasowe

Właściwość timestamp zdarzeń żądań internetowych jest gwarantowana tylko w zakresie wewnętrznej spójności. Porównanie jednego zdarzenia z innym da prawidłowe przesunięcie między nimi, ale porównanie ich z bieżącym czasem w rozszerzeniu (np. za pomocą (new Date()).getTime()) może dać nieoczekiwane wyniki.

Obsługa błędów

Jeśli spróbujesz zarejestrować zdarzenie z nieprawidłowymi argumentami, zostanie zgłoszony błąd JavaScriptu, a procedura obsługi zdarzeń nie zostanie zarejestrowana. Jeśli podczas obsługi zdarzenia wystąpi błąd lub jeśli moduł obsługi zdarzeń zwróci nieprawidłową odpowiedź blokującą, w konsoli rozszerzenia zostanie zarejestrowany komunikat o błędzie, a moduł obsługi zostanie zignorowany w przypadku tego żądania.

Przykłady

Ten przykład pokazuje, jak zablokować wszystkie żądania wysyłane do www.evil.com:

chrome.webRequest.onBeforeRequest.addListener(
  function(details) {
    return {cancel: details.url.indexOf("://www.evil.com/") != -1};
  },
  {urls: ["<all_urls>"]},
  ["blocking"]
);

Ta funkcja korzysta z blokującego modułu obsługi zdarzeń, dlatego w pliku manifestu wymaga uprawnień "webRequest" i "webRequestBlocking".

Poniższy przykład pozwala osiągnąć ten sam cel w bardziej efektywny sposób, ponieważ żądania, które nie są kierowane na www.evil.com, nie muszą być przekazywane do rozszerzenia:

chrome.webRequest.onBeforeRequest.addListener(
  function(details) { return {cancel: true}; },
  {urls: ["*://www.evil.com/*"]},
  ["blocking"]
);

Ten przykład pokazuje, jak usunąć nagłówek klienta użytkownika ze wszystkich żądań:

chrome.webRequest.onBeforeSendHeaders.addListener(
  function(details) {
    for (var i = 0; i < details.requestHeaders.length; ++i) {
      if (details.requestHeaders[i].name === 'User-Agent') {
        details.requestHeaders.splice(i, 1);
        break;
      }
    }
    return {requestHeaders: details.requestHeaders};
  },
  {urls: ["<all_urls>"]},
  ["blocking", "requestHeaders"]
);

Aby wypróbować interfejs chrome.webRequest API, zainstaluj przykładowy kod webRequest z repozytorium chrome-extension-samples.

Typy

BlockingResponse

Zwraca wartość dla funkcji obsługi zdarzeń, do których zastosowano parametr extraInfoSpec „blocking”. Umożliwia modułowi obsługi zdarzeń modyfikowanie żądań sieciowych.

Właściwości

  • authCredentials

    obiekt opcjonalny

    Używana tylko jako odpowiedź na zdarzenie onAuthRequired. Jeśli to pole jest ustawione, żądanie jest wysyłane przy użyciu podanych danych logowania.

    • hasło

      ciąg znaków

    • nazwa użytkownika

      ciąg znaków

  • anuluj

    wartość logiczna opcjonalna

    Jeśli wartość jest prawdziwa, żądanie zostanie anulowane. Zapobiega to wysłaniu prośby. Może być używana jako odpowiedź na zdarzenia onBeforeRequest, onBeforeSendHeaders, onHeadersReceived i onAuthRequired.

  • redirectUrl

    ciąg znaków opcjonalny

    Używana tylko jako odpowiedź na zdarzenia onBeforeRequest i onHeadersReceived. Jeśli ta opcja jest ustawiona, pierwotne żądanie nie zostanie wysłane ani zrealizowane, tylko przekierowane na podany adres URL. Przekierowania do schematów innych niż HTTP, np. data:, są dozwolone. Przekierowania zainicjowane przez działanie przekierowania używają oryginalnej metody żądania do przekierowania, z jednym wyjątkiem: jeśli przekierowanie zostanie zainicjowane na etapie onHeadersReceived, zostanie ono wydane przy użyciu metody GET. Przekierowania z adresów URL ze schematami ws:// i wss:// są ignorowane.

  • requestHeaders

    HttpHeaders opcjonalny

    Używane tylko w odpowiedzi na zdarzenie onBeforeSendHeaders. Jeśli to pole jest ustawione, żądanie jest wysyłane z tymi nagłówkami.

  • responseHeaders

    HttpHeaders opcjonalny

    Używane tylko jako odpowiedź na zdarzenie onHeadersReceived. Jeśli jest ustawiony, zakłada się, że serwer odpowiedział za pomocą tych nagłówków odpowiedzi. Zwracaj tylko responseHeaders, jeśli naprawdę chcesz zmodyfikować nagłówki, aby ograniczyć liczbę konfliktów (tylko jedno rozszerzenie może modyfikować responseHeaders w przypadku każdego żądania).

FormDataItem

Chrome 66 lub nowsza

Zawiera dane przekazywane w danych formularza. W przypadku formularza zakodowanego w formacie URL dane są przechowywane jako ciąg znaków, jeśli są ciągiem znaków UTF-8, a w innych przypadkach jako ArrayBuffer. W przypadku danych formularza jest to ArrayBuffer. Jeśli dane formularza reprezentują przesyłanie pliku, jest to ciąg znaków z nazwą pliku, jeśli nazwa pliku jest podana.

Typ wyliczeniowy

ArrayBuffer

ciąg znaków

HttpHeaders

Tablica nagłówków HTTP. Każdy nagłówek jest reprezentowany jako słownik zawierający klucze name oraz value lub binaryValue.

Typ

object[]

Właściwości

  • binaryValue

    number[] opcjonalny

    Wartość nagłówka HTTP, jeśli nie można jej przedstawić w formacie UTF-8. Jest przechowywana jako poszczególne wartości bajtów (0–255).

  • nazwa

    ciąg znaków

    Nazwa nagłówka HTTP.

  • wartość

    ciąg znaków opcjonalny

    Wartość nagłówka HTTP, jeśli można ją przedstawić w formacie UTF-8.

IgnoredActionType

Chrome w wersji 70 lub nowszej

Typ wyliczeniowy

„redirect”

„request_headers”

„response_headers”

"auth_credentials"

OnAuthRequiredOptions

Chrome 44 lub nowsza

Typ wyliczeniowy

„responseHeaders”
Określa, że nagłówki odpowiedzi mają być uwzględnione w wydarzeniu.

„blocking”
Określa, że żądanie jest blokowane do momentu, gdy funkcja wywołania zwrotnego zwróci wartość.

"asyncBlocking"
Określa, że funkcja wywołania zwrotnego jest obsługiwana asynchronicznie.

„extraHeaders”
Określa, że nagłówki mogą naruszać współdzielenie zasobów między serwerami z różnych domen (CORS).

OnBeforeRedirectOptions

Chrome 44 lub nowsza

Typ wyliczeniowy

„responseHeaders”
Określa, że nagłówki odpowiedzi mają być uwzględnione w wydarzeniu.

„extraHeaders”
Określa, że nagłówki mogą naruszać współdzielenie zasobów między serwerami z różnych domen (CORS).

OnBeforeRequestOptions

Chrome 44 lub nowsza

Typ wyliczeniowy

„blocking”
Określa, że żądanie jest blokowane do momentu, gdy funkcja wywołania zwrotnego zwróci wartość.

„requestBody”
Określa, że treść żądania powinna być uwzględniona w zdarzeniu.

„extraHeaders”
Określa, że nagłówki mogą naruszać współdzielenie zasobów między serwerami z różnych domen (CORS).

OnBeforeSendHeadersOptions

Chrome 44 lub nowsza

Typ wyliczeniowy

„requestHeaders”
Określa, że nagłówek żądania powinien być uwzględniony w zdarzeniu.

„blocking”
Określa, że żądanie jest blokowane do momentu, gdy funkcja wywołania zwrotnego zwróci wartość.

„extraHeaders”
Określa, że nagłówki mogą naruszać współdzielenie zasobów między serwerami z różnych domen (CORS).

OnCompletedOptions

Chrome 44 lub nowsza

Typ wyliczeniowy

„responseHeaders”
Określa, że nagłówki odpowiedzi mają być uwzględnione w wydarzeniu.

„extraHeaders”
Określa, że nagłówki mogą naruszać współdzielenie zasobów między serwerami z różnych domen (CORS).

OnErrorOccurredOptions

Chrome 79 lub nowsza

Wartość

„extraHeaders”

OnHeadersReceivedOptions

Chrome 44 lub nowsza

Typ wyliczeniowy

„blocking”
Określa, że żądanie jest blokowane do momentu, gdy funkcja wywołania zwrotnego zwróci wartość.

„responseHeaders”
Określa, że nagłówki odpowiedzi mają być uwzględnione w wydarzeniu.

„extraHeaders”
Określa, że nagłówki mogą naruszać współdzielenie zasobów między serwerami z różnych domen (CORS).

„securityInfo”
Określa, że w zdarzeniu mają być uwzględnione informacje o bezpieczeństwie.

„securityInfoRawDer”
Określa, że w zdarzeniu mają być uwzględnione informacje o zabezpieczeniach z surowymi bajtami certyfikatów.

OnResponseStartedOptions

Chrome 44 lub nowsza

Typ wyliczeniowy

„responseHeaders”
Określa, że nagłówki odpowiedzi mają być uwzględnione w wydarzeniu.

„extraHeaders”
Określa, że nagłówki mogą naruszać współdzielenie zasobów między serwerami z różnych domen (CORS).

OnSendHeadersOptions

Chrome 44 lub nowsza

Typ wyliczeniowy

„requestHeaders”
Określa, że nagłówek żądania powinien być uwzględniony w zdarzeniu.

„extraHeaders”
Określa, że nagłówki mogą naruszać współdzielenie zasobów między serwerami z różnych domen (CORS).

RequestFilter

Obiekt opisujący filtry, które mają być stosowane do zdarzeń webRequest.

Właściwości

  • tabId

    number opcjonalny

  • typy

    ResourceType[] opcjonalny

    Lista typów żądań. Żądania, które nie pasują do żadnego z tych typów, zostaną odfiltrowane.

  • adresy

    string[]

    Lista adresów URL lub wzorców adresów URL. Żądania, które nie pasują do żadnego z adresów URL, zostaną odfiltrowane.

  • windowId

    number opcjonalny

ResourceType

Chrome 44 lub nowsza

Typ wyliczeniowy

„main_frame”
Określa zasób jako główną ramkę.

„sub_frame”
Określa zasób jako ramkę podrzędną.

„stylesheet”
Określa zasób jako arkusz stylów.

„script”
Określa zasób jako skrypt.

„image”
Określa zasób jako obraz.

„font”
Określa zasób jako czcionkę.

„object”
Określa zasób jako obiekt.

„xmlhttprequest”
Określa zasób jako XMLHttpRequest.

„ping”
Określa zasób jako ping.

„csp_report”
Określa zasób jako raport Content Security Policy (CSP).

„media”
Określa zasób jako obiekt multimedialny.

„websocket”
Określa zasób jako WebSocket.

„webbundle”
Określa zasób jako pakiet internetowy.

„other”
Określa zasób jako typ nieujęty na liście.

SecurityInfo

Oczekuje

Właściwości

  • certyfikaty

    object[]

    Lista certyfikatów

    • odcisk palca

      obiekt

      Odciski cyfrowe certyfikatu.

      • sha256

        ciąg znaków

        odcisk cyfrowy certyfikatu SHA256.

    • rawDER

      ArrayBuffer opcjonalny

      Surowe bajty certyfikatu serwera z kodowaniem DER

  • stan

    ciąg znaków

    Stan połączenia. Jedna z wartości: secure, insecure, broken.

UploadData

Zawiera dane przesłane w żądaniu adresu URL.

Właściwości

  • B

    dowolny opcjonalny

    Obiekt ArrayBuffer z kopią danych.

  • plik

    ciąg znaków opcjonalny

    Ciąg znaków ze ścieżką i nazwą pliku.

Właściwości

MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES

Maksymalna liczba wywołań funkcji handlerBehaviorChanged w ciągu 10-minutowego przedziału czasu. handlerBehaviorChanged to kosztowne wywołanie funkcji, którego nie należy często używać.

Wartość

20

Metody

handlerBehaviorChanged()

chrome.webRequest.handlerBehaviorChanged(): Promise<void>

Należy wywołać, gdy zmieni się zachowanie modułów obsługi webRequest, aby zapobiec nieprawidłowemu przetwarzaniu z powodu buforowania. Wywołanie tej funkcji jest kosztowne. Nie dzwoń zbyt często.

Zwroty

  • Promise<void>

    Chrome 116 lub nowsza

Wydarzenia

onActionIgnored

Chrome w wersji 70 lub nowszej 
chrome.webRequest.onActionIgnored.addListener(
  callback: function,
)

Wywoływane, gdy proponowana przez rozszerzenie modyfikacja żądania sieciowego jest ignorowana. Dzieje się tak w przypadku konfliktów z innymi rozszerzeniami.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => void

    • szczegóły

      obiekt

      • działanie

        IgnoredActionType

        Proponowane działanie, które zostało zignorowane.

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

onAuthRequired

chrome.webRequest.onAuthRequired.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnAuthRequiredOptions[],
)

Wywoływane, gdy wystąpi błąd uwierzytelniania. Odbiorca ma 3 opcje: może podać dane logowania, anulować żądanie i wyświetlić stronę błędu lub nie podejmować żadnych działań w odpowiedzi na wyzwanie. Jeśli podano nieprawidłowe dane logowania użytkownika, funkcja może być wywoływana wielokrotnie w przypadku tego samego żądania. Pamiętaj, że w parametrze extraInfoSpec należy określić tylko jeden z trybów: 'blocking' lub 'asyncBlocking'.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object, asyncCallback?: function) => BlockingResponse | undefined

    • szczegóły

      obiekt

      • pretendent

        obiekt

        Serwer, który prosi o uwierzytelnienie.

        • host

          ciąg znaków

        • port

          liczba

      • documentId

        ciąg znaków

        Chrome 106 lub nowsza

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

      • Chrome 106 lub nowsza

        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 ramki zewnętrznej. Identyfikatory ramek są unikalne w obrębie karty.

      • Chrome 106 lub nowsza

        Typ ramki, w której wystąpiło żądanie.

      • inicjator,

        ciąg znaków opcjonalny

        Chrome 63 lub nowsza

        Pochodzenie, z którego zostało zainicjowane żądanie. Nie zmienia się ona w przypadku przekierowań. Jeśli jest to nieprzezroczyste źródło, użyty zostanie ciąg znaków „null”.

      • isProxy

        Wartość logiczna

        Wartość „true” w przypadku nagłówka Proxy-Authenticate, „false” w przypadku nagłówka WWW-Authenticate.

      • method

        ciąg znaków

        Standardowa metoda HTTP.

      • parentDocumentId

        ciąg znaków opcjonalny

        Chrome 106 lub nowsza

        Identyfikator UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma elementu nadrzędnego, ta 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.

      • obszar

        ciąg znaków opcjonalny

        Obszar uwierzytelniania udostępniony przez serwer (jeśli taki istnieje).

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

      • responseHeaders

        HttpHeaders opcjonalny

        Nagłówki odpowiedzi HTTP, które zostały otrzymane wraz z tą odpowiedzią.

      • schemat

        ciąg znaków

        Schemat uwierzytelniania, np. Basic lub Digest.

      • statusCode

        liczba

        Chrome 43 lub nowszy

        Standardowy kod stanu HTTP zwrócony przez serwer.

      • statusLine

        ciąg znaków

        Wiersz stanu HTTP odpowiedzi lub ciąg „HTTP/0.9 200 OK” w przypadku odpowiedzi HTTP/0.9 (czyli odpowiedzi bez wiersza stanu) albo pusty ciąg, jeśli nie ma nagłówków.

      • 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

    • asyncCallback

      funkcja opcjonalna

      Chrome 58 lub nowsza

      Parametr asyncCallback wygląda tak:

      (response: BlockingResponse) => void

    • returns

      BlockingResponse | undefined

      Jeśli w parametrze „extraInfoSpec” określono wartość „blocking”, detektor zdarzeń powinien zwrócić obiekt tego typu.

  • extraInfoSpec

    OnAuthRequiredOptions[] opcjonalnie

onBeforeRedirect

chrome.webRequest.onBeforeRedirect.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeRedirectOptions[],
)

Uruchamiane, gdy ma nastąpić przekierowanie zainicjowane przez serwer.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => void

    • szczegóły

      obiekt

      • documentId

        ciąg znaków

        Chrome 106 lub nowsza

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

      • Chrome 106 lub nowsza

        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 ramki zewnętrznej. Identyfikatory ramek są unikalne w obrębie karty.

      • Chrome 106 lub nowsza

        Typ ramki, w której wystąpiło żądanie.

      • fromCache

        Wartość logiczna

        Wskazuje, czy ta odpowiedź została pobrana z pamięci podręcznej na dysku.

      • inicjator,

        ciąg znaków opcjonalny

        Chrome 63 lub nowsza

        Pochodzenie, z którego zostało zainicjowane żądanie. Nie zmienia się ona w przypadku przekierowań. Jeśli jest to nieprzezroczyste źródło, użyty zostanie ciąg znaków „null”.

      • ip

        ciąg znaków opcjonalny

        Adres IP serwera, do którego zostało wysłane żądanie. Pamiętaj, że może to być dosłowny adres IPv6.

      • method

        ciąg znaków

        Standardowa metoda HTTP.

      • parentDocumentId

        ciąg znaków opcjonalny

        Chrome 106 lub nowsza

        Identyfikator UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma elementu nadrzędnego, ta 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.

      • redirectUrl

        ciąg znaków

        Nowy URL.

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

      • responseHeaders

        HttpHeaders opcjonalny

        Nagłówki odpowiedzi HTTP, które zostały odebrane wraz z tym przekierowaniem.

      • statusCode

        liczba

        Standardowy kod stanu HTTP zwrócony przez serwer.

      • statusLine

        ciąg znaków

        Wiersz stanu HTTP odpowiedzi lub ciąg „HTTP/0.9 200 OK” w przypadku odpowiedzi HTTP/0.9 (czyli odpowiedzi bez wiersza stanu) albo pusty ciąg, jeśli nie ma nagłówków.

      • 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

  • extraInfoSpec

    OnBeforeRedirectOptions[] opcjonalnie

onBeforeRequest

chrome.webRequest.onBeforeRequest.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeRequestOptions[],
)

Uruchamiane, gdy ma nastąpić wysłanie żądania.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => BlockingResponse | undefined

    • szczegóły

      obiekt

      • documentId

        ciąg znaków opcjonalny

        Chrome 106 lub nowsza

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

      • documentLifecycle

        extensionTypes.DocumentLifecycle opcjonalnie

        Chrome 106 lub nowsza

        Cykl ż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 ramki zewnętrznej. Identyfikatory ramek są unikalne w obrębie karty.

      • frameType

        extensionTypes.FrameType opcjonalny

        Chrome 106 lub nowsza

        Typ ramki, w której wystąpiło żądanie.

      • inicjator,

        ciąg znaków opcjonalny

        Chrome 63 lub nowsza

        Pochodzenie, z którego zostało zainicjowane żądanie. Nie zmienia się ona w przypadku przekierowań. Jeśli jest to nieprzezroczyste źródło, użyty zostanie ciąg znaków „null”.

      • method

        ciąg znaków

        Standardowa metoda HTTP.

      • parentDocumentId

        ciąg znaków opcjonalny

        Chrome 106 lub nowsza

        Identyfikator UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma elementu nadrzędnego, ta 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.

      • requestBody

        obiekt opcjonalny

        Zawiera dane treści żądania HTTP. Podawane tylko wtedy, gdy extraInfoSpec zawiera „requestBody”.

        • błąd

          ciąg znaków opcjonalny

          Błędy podczas uzyskiwania danych treści żądania.

        • formData

          obiekt opcjonalny

          Jeśli metoda żądania to POST, a treść jest ciągiem par klucz-wartość zakodowanych w UTF8 jako multipart/form-data lub application/x-www-form-urlencoded, ten słownik jest obecny i dla każdego klucza zawiera listę wszystkich wartości tego klucza. Jeśli dane są innego typu lub są nieprawidłowo sformatowane, słownik nie jest dostępny. Przykładowa wartość tego słownika to {'key': ['value1', 'value2']}.

        • nieprzetworzony

          UploadData[] opcjonalny

          Jeśli metoda żądania to PUT lub POST, a treść nie została jeszcze przeanalizowana w formData, ta tablica zawiera nieprzeanalizowane elementy treści żądania.

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

      • 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

    • returns

      BlockingResponse | undefined

      Jeśli w parametrze „extraInfoSpec” określono wartość „blocking”, detektor zdarzeń powinien zwrócić obiekt tego typu.

  • extraInfoSpec

    OnBeforeRequestOptions[] opcjonalnie

onBeforeSendHeaders

chrome.webRequest.onBeforeSendHeaders.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnBeforeSendHeadersOptions[],
)

Wydarzenie wywoływane przed wysłaniem żądania HTTP, gdy dostępne są nagłówki żądania. Może to nastąpić po nawiązaniu połączenia TCP z serwerem, ale przed wysłaniem jakichkolwiek danych HTTP.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => BlockingResponse | undefined

    • szczegóły

      obiekt

      • documentId

        ciąg znaków

        Chrome 106 lub nowsza

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

      • Chrome 106 lub nowsza

        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 ramki zewnętrznej. Identyfikatory ramek są unikalne w obrębie karty.

      • Chrome 106 lub nowsza

        Typ ramki, w której wystąpiło żądanie.

      • inicjator,

        ciąg znaków opcjonalny

        Chrome 63 lub nowsza

        Pochodzenie, z którego zostało zainicjowane żądanie. Nie zmienia się ona w przypadku przekierowań. Jeśli jest to nieprzezroczyste źródło, użyty zostanie ciąg znaków „null”.

      • method

        ciąg znaków

        Standardowa metoda HTTP.

      • parentDocumentId

        ciąg znaków opcjonalny

        Chrome 106 lub nowsza

        Identyfikator UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma elementu nadrzędnego, ta 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.

      • requestHeaders

        HttpHeaders opcjonalny

        Nagłówki żądania HTTP, które zostaną wysłane wraz z tym żądaniem.

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

      • 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

    • returns

      BlockingResponse | undefined

      Jeśli w parametrze „extraInfoSpec” określono wartość „blocking”, detektor zdarzeń powinien zwrócić obiekt tego typu.

  • extraInfoSpec

    OnBeforeSendHeadersOptions[] opcjonalny

onCompleted

chrome.webRequest.onCompleted.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnCompletedOptions[],
)

Uruchamiane po zakończeniu żądania.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => void

    • szczegóły

      obiekt

      • documentId

        ciąg znaków

        Chrome 106 lub nowsza

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

      • Chrome 106 lub nowsza

        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 ramki zewnętrznej. Identyfikatory ramek są unikalne w obrębie karty.

      • Chrome 106 lub nowsza

        Typ ramki, w której wystąpiło żądanie.

      • fromCache

        Wartość logiczna

        Wskazuje, czy ta odpowiedź została pobrana z pamięci podręcznej na dysku.

      • inicjator,

        ciąg znaków opcjonalny

        Chrome 63 lub nowsza

        Pochodzenie, z którego zostało zainicjowane żądanie. Nie zmienia się ona w przypadku przekierowań. Jeśli jest to nieprzezroczyste źródło, użyty zostanie ciąg znaków „null”.

      • ip

        ciąg znaków opcjonalny

        Adres IP serwera, do którego zostało wysłane żądanie. Pamiętaj, że może to być dosłowny adres IPv6.

      • method

        ciąg znaków

        Standardowa metoda HTTP.

      • parentDocumentId

        ciąg znaków opcjonalny

        Chrome 106 lub nowsza

        Identyfikator UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma elementu nadrzędnego, ta 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

        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.

      • responseHeaders

        HttpHeaders opcjonalny

        Nagłówki odpowiedzi HTTP, które zostały otrzymane wraz z tą odpowiedzią.

      • statusCode

        liczba

        Standardowy kod stanu HTTP zwrócony przez serwer.

      • statusLine

        ciąg znaków

        Wiersz stanu HTTP odpowiedzi lub ciąg „HTTP/0.9 200 OK” w przypadku odpowiedzi HTTP/0.9 (czyli odpowiedzi bez wiersza stanu) albo pusty ciąg, jeśli nie ma nagłówków.

      • 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

  • extraInfoSpec

    OnCompletedOptions[] opcjonalnie

onErrorOccurred

chrome.webRequest.onErrorOccurred.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnErrorOccurredOptions[],
)

Uruchamiane, gdy wystąpi błąd.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => void

    • szczegóły

      obiekt

      • documentId

        ciąg znaków

        Chrome 106 lub nowsza

        Identyfikator UUID dokumentu, który wysyła żądanie. Ta wartość nie występuje, jeśli żądanie dotyczy nawigacji w ramce.

      • Chrome 106 lub nowsza

        Etap cyklu życia dokumentu.

      • błąd

        ciąg znaków

        Opis błędu. Nie ma gwarancji, że ten ciąg znaków będzie zgodny wstecznie w kolejnych wersjach. Nie wolno analizować jego treści ani podejmować na ich podstawie działań.

      • 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 ramki zewnętrznej. Identyfikatory ramek są unikalne w obrębie karty.

      • Chrome 106 lub nowsza

        Typ ramki, w której wystąpiło żądanie.

      • fromCache

        Wartość logiczna

        Wskazuje, czy ta odpowiedź została pobrana z pamięci podręcznej na dysku.

      • inicjator,

        ciąg znaków opcjonalny

        Chrome 63 lub nowsza

        Pochodzenie, z którego zostało zainicjowane żądanie. Nie zmienia się ona w przypadku przekierowań. Jeśli jest to nieprzezroczyste źródło, użyty zostanie ciąg znaków „null”.

      • ip

        ciąg znaków opcjonalny

        Adres IP serwera, do którego zostało wysłane żądanie. Pamiętaj, że może to być dosłowny adres IPv6.

      • method

        ciąg znaków

        Standardowa metoda HTTP.

      • parentDocumentId

        ciąg znaków opcjonalny

        Chrome 106 lub nowsza

        Identyfikator UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma elementu nadrzędnego, ta 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

        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.

      • 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

  • extraInfoSpec

    OnErrorOccurredOptions[] opcjonalnie

onHeadersReceived

chrome.webRequest.onHeadersReceived.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnHeadersReceivedOptions[],
)

Wywoływane po otrzymaniu nagłówków odpowiedzi HTTP żądania.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => BlockingResponse | undefined

    • szczegóły

      obiekt

      • documentId

        ciąg znaków

        Chrome 106 lub nowsza

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

      • Chrome 106 lub nowsza

        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 ramki zewnętrznej. Identyfikatory ramek są unikalne w obrębie karty.

      • Chrome 106 lub nowsza

        Typ ramki, w której wystąpiło żądanie.

      • inicjator,

        ciąg znaków opcjonalny

        Chrome 63 lub nowsza

        Pochodzenie, z którego zostało zainicjowane żądanie. Nie zmienia się ona w przypadku przekierowań. Jeśli jest to nieprzezroczyste źródło, użyty zostanie ciąg znaków „null”.

      • method

        ciąg znaków

        Standardowa metoda HTTP.

      • parentDocumentId

        ciąg znaków opcjonalny

        Chrome 106 lub nowsza

        Identyfikator UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma elementu nadrzędnego, ta 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

        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.

      • responseHeaders

        HttpHeaders opcjonalny

        Nagłówki odpowiedzi HTTP, które zostały otrzymane wraz z tą odpowiedzią.

      • securityInfo

        SecurityInfo opcjonalnie

        Oczekuje

        Informacje o połączeniu TLS/QUIC używanym w przypadku połączenia bazowego. Podawany tylko wtedy, gdy w parametrze extraInfoSpec określono wartość securityInfo.

      • statusCode

        liczba

        Chrome 43 lub nowszy

        Standardowy kod stanu HTTP zwrócony przez serwer.

      • statusLine

        ciąg znaków

        Wiersz stanu HTTP odpowiedzi lub ciąg znaków „HTTP/0.9 200 OK” w przypadku odpowiedzi HTTP/0.9 (czyli odpowiedzi, które nie mają wiersza stanu).

      • 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

    • returns

      BlockingResponse | undefined

      Jeśli w parametrze „extraInfoSpec” określono wartość „blocking”, detektor zdarzeń powinien zwrócić obiekt tego typu.

  • extraInfoSpec

    OnHeadersReceivedOptions[] opcjonalnie

onResponseStarted

chrome.webRequest.onResponseStarted.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnResponseStartedOptions[],
)

Wywoływane po otrzymaniu pierwszego bajtu treści odpowiedzi. W przypadku żądań HTTP oznacza to, że dostępne są wiersz stanu i nagłówki odpowiedzi.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => void

    • szczegóły

      obiekt

      • documentId

        ciąg znaków

        Chrome 106 lub nowsza

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

      • Chrome 106 lub nowsza

        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 ramki zewnętrznej. Identyfikatory ramek są unikalne w obrębie karty.

      • Chrome 106 lub nowsza

        Typ ramki, w której wystąpiło żądanie.

      • fromCache

        Wartość logiczna

        Wskazuje, czy ta odpowiedź została pobrana z pamięci podręcznej na dysku.

      • inicjator,

        ciąg znaków opcjonalny

        Chrome 63 lub nowsza

        Pochodzenie, z którego zostało zainicjowane żądanie. Nie zmienia się ona w przypadku przekierowań. Jeśli jest to nieprzezroczyste źródło, użyty zostanie ciąg znaków „null”.

      • ip

        ciąg znaków opcjonalny

        Adres IP serwera, do którego zostało wysłane żądanie. Pamiętaj, że może to być dosłowny adres IPv6.

      • method

        ciąg znaków

        Standardowa metoda HTTP.

      • parentDocumentId

        ciąg znaków opcjonalny

        Chrome 106 lub nowsza

        Identyfikator UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma elementu nadrzędnego, ta 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

        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.

      • responseHeaders

        HttpHeaders opcjonalny

        Nagłówki odpowiedzi HTTP, które zostały otrzymane wraz z tą odpowiedzią.

      • statusCode

        liczba

        Standardowy kod stanu HTTP zwrócony przez serwer.

      • statusLine

        ciąg znaków

        Wiersz stanu HTTP odpowiedzi lub ciąg „HTTP/0.9 200 OK” w przypadku odpowiedzi HTTP/0.9 (czyli odpowiedzi bez wiersza stanu) albo pusty ciąg, jeśli nie ma nagłówków.

      • 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

  • extraInfoSpec

    OnResponseStartedOptions[] opcjonalnie

onSendHeaders

chrome.webRequest.onSendHeaders.addListener(
  callback: function,
  filter: RequestFilter,
  extraInfoSpec?: OnSendHeadersOptions[],
)

Wywoływana tuż przed wysłaniem żądania do serwera (modyfikacje poprzednich wywołań zwrotnych onBeforeSendHeaders są widoczne w momencie wywołania onSendHeaders).

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (details: object) => void

    • szczegóły

      obiekt

      • documentId

        ciąg znaków

        Chrome 106 lub nowsza

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

      • Chrome 106 lub nowsza

        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 ramki zewnętrznej. Identyfikatory ramek są unikalne w obrębie karty.

      • Chrome 106 lub nowsza

        Typ ramki, w której wystąpiło żądanie.

      • inicjator,

        ciąg znaków opcjonalny

        Chrome 63 lub nowsza

        Pochodzenie, z którego zostało zainicjowane żądanie. Nie zmienia się ona w przypadku przekierowań. Jeśli jest to nieprzezroczyste źródło, użyty zostanie ciąg znaków „null”.

      • method

        ciąg znaków

        Standardowa metoda HTTP.

      • parentDocumentId

        ciąg znaków opcjonalny

        Chrome 106 lub nowsza

        Identyfikator UUID dokumentu nadrzędnego, do którego należy ta ramka. Jeśli nie ma elementu nadrzędnego, ta 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.

      • requestHeaders

        HttpHeaders opcjonalny

        Nagłówki żądania HTTP, które zostały wysłane wraz z tym żądaniem.

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

      • 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

  • extraInfoSpec

    OnSendHeadersOptions[] opcjonalnie