chrome.declarativeWebRequest

Descripción

Nota: Esta API está obsoleta. Consulta la API de declarativeNetRequest en su lugar. Usa la API de chrome.declarativeWebRequest para interceptar, bloquear o modificar solicitudes en tránsito. Es mucho más rápida que la API de chrome.webRequest, ya que puedes registrar reglas que se evalúan en el navegador y no en el motor de JavaScript, lo que reduce las latencias de ida y vuelta y permite una mayor eficiencia.

Permisos

declarativeWebRequest

Debes declarar la "declarativeWebRequest" permiso en el manifiesto de extensión para usar esta junto con los permisos de host.

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

Disponibilidad

Canal beta ≤ MV2

Manifiesto

Ten en cuenta que ciertos tipos de acciones no sensibles no requieren permisos de host:

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

La acción SendMessageToExtension() requiere permisos de host para cualquier host cuyas solicitudes de red en la que deseas activar un mensaje.

Todas las demás acciones requieren permisos de host para todas las URLs.

Por ejemplo, si "https://*.google.com/*" es el único permiso de host que tiene una extensión, este La extensión puede configurar una regla para lo siguiente:

  • Cancela una solicitud a https://www.google.com o https://anything.else.com.
  • Se envía un mensaje cuando navegas a https://www.google.com, pero no a https://something.else.com.

La extensión no puede configurar una regla para redireccionar https://www.google.com a https://mail.google.com.

Reglas

La API de Declarative Web Request sigue los conceptos de la API declarativa. Puedes registrarte al objeto de evento chrome.declarativeWebRequest.onRequest.

La API de Declarative Web Request admite un solo tipo de criterio de coincidencia: RequestMatcher. El RequestMatcher coincide con las solicitudes de red solo si se cumplen todos los criterios enumerados. Lo siguiente RequestMatcher coincidiría con una solicitud de red cuando el usuario ingrese https://www.example.com en el Ominibox:

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

RequestMatcher rechazará las solicitudes a https://www.example.com debido al esquema. Además, todas las solicitudes de un iframe incorporado se rechazarán debido al resourceType.

Para cancelar todas las solicitudes a "example.com", puedes definir una regla de la siguiente manera:

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

Para cancelar todas las solicitudes a example.com y foobar.com, puedes agregar una segunda condición. ya que cada condición es suficiente para activar todas las acciones especificadas:

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

Registra las reglas de la siguiente manera:

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

Evaluación de condiciones y acciones

La API de Declarative Web Request sigue el Modelo de ciclo de vida para solicitudes web de la Web Solicitar API. Esto significa que las condiciones solo pueden probarse en etapas específicas de una solicitud web. y, del mismo modo, las acciones solo se pueden ejecutar en etapas específicas. En las siguientes tablas, se enumeran de solicitudes que son compatibles con condiciones y acciones.

Etapas de la solicitud durante las cuales se pueden procesar los atributos de condición.
Atributo de condición onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
url ✓ ✓ ✓ ✓
resourceType ✓ ✓ ✓ ✓
contentType ✓
excludeContentType ✓
responseHeaders ✓
excludeResponseHeaders ✓
requestHeaders ✓
excludeRequestHeaders ✓
thirdPartyForCookies ✓ ✓ ✓ ✓
Etapas de solicitudes durante las cuales se pueden ejecutar acciones.
Evento onBeforeRequest onBeforeSendHeaders onHeadersReceived onAuthRequired
AddRequestCookie ✓
AddResponseCookie ✓
AddResponseHeader ✓
CancelRequest ✓ ✓ ✓ ✓
EditRequestCookie ✓
EditResponseCookie ✓
IgnoreRules ✓ ✓ ✓ ✓
RedirectByRegEx ✓ ✓
RedirectRequest ✓ ✓
RedirectToEmptyDocument ✓ ✓
RedirectToTransparentImage ✓ ✓
RemoveRequestCookie ✓
RemoveRequestHeader ✓
RemoveResponseCookie ✓
RemoveResponseHeader ✓
SendMessageToExtension ✓ ✓ ✓ ✓
SetRequestHeader ✓

Usa prioridades para anular reglas

Las reglas se pueden asociar con prioridades, como se describe en la API de Events. Este mecanismo puede ser que se usan para expresar excepciones. En el siguiente ejemplo, se bloquean todas las solicitudes de imágenes con el nombre evil.jpg. excepto en el servidor “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]);

Es importante reconocer que la acción IgnoreRules no persiste en todas las solicitudes etapas. Todas las condiciones de todas las reglas se evalúan en cada etapa de una solicitud web. Si un IgnoreRules, solo se aplica a las demás acciones que se ejecutan para la misma solicitud web en la misma etapa.

Tipos

AddRequestCookie

Agrega una cookie a la solicitud o anula una, en caso de que ya exista otra cookie con el mismo nombre. Ten en cuenta que es preferible usar la API de cookies, ya que el procesamiento es más económico.

Propiedades

AddResponseCookie

Agrega una cookie a la respuesta o anula una cookie en caso de que ya exista otra con el mismo nombre. Ten en cuenta que es preferible usar la API de cookies, ya que el procesamiento es más económico.

Propiedades

AddResponseHeader

Agrega el encabezado de respuesta a la respuesta de esta solicitud web. Dado que varios encabezados de respuesta pueden tener el mismo nombre, primero debes quitar y, luego, agregar uno nuevo para reemplazar uno.

Propiedades

  • constructor

    void

    La función constructor se ve de la siguiente manera: 

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

  • nombre

    string

    Nombre del encabezado de respuesta HTTP.

  • valor

    string

    Valor de encabezado de respuesta HTTP.

CancelRequest

Acción de evento declarativa que cancela una solicitud de red.

Propiedades

EditRequestCookie

Edita una o más cookies de solicitud. Ten en cuenta que es preferible usar la API de cookies, ya que el procesamiento es más económico.

Propiedades

  • constructor

    void

    La función constructor se ve de la siguiente manera: 

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

  • filter

    RequestCookie

    Filtra las cookies que se modificarán. Se ignoran todas las entradas vacías.

  • modificación

    RequestCookie

    Atributos que se deben anular en las cookies que configuraron el filtro. Se quitan los atributos que se establecen en una string vacía.

EditResponseCookie

Edita una o más cookies de respuesta. Ten en cuenta que es preferible usar la API de cookies, ya que el procesamiento es más económico.

Propiedades

FilterResponseCookie

Es un filtro de una cookie en las respuestas HTTP.

Propiedades

  • ageLowerBound

    número opcional

    Límite inferior inclusivo en la vida útil de la cookie (especificado en segundos después del tiempo actual). Solo cookies cuya fecha y hora de vencimiento estén configuradas como "now + ageLowerBound" o cumplir con este criterio en otro momento. Las cookies de sesión no cumplen con los criterios de este filtro. La vida útil de las cookies se calcula a partir de los valores de "edad máxima" o “vence” atributos de cookies. Si se especifican ambos, 'max-age' se usa para calcular la vida útil de la cookie.

  • ageUpperBound

    número opcional

    Límite superior inclusivo en la vida útil de la cookie (especificado en segundos después del tiempo actual). Solo las cookies cuya fecha y hora de vencimiento están en el intervalo [ahora, ahora + ageUpperBound] cumplen con este criterio. Las cookies de sesión y aquellas cuya fecha y hora de vencimiento es en el pasado no cumplen con los criterios de este filtro. La vida útil de las cookies se calcula a partir de los valores de "edad máxima" o “vence” atributos de cookies. Si se especifican ambos, 'max-age' y se usa para calcular la vida útil de la cookie.

  • dominio

    string opcional

    Valor del atributo cookie de dominio.

  • fecha de vencimiento

    string opcional

    Valor del atributo de cookie de vencimiento.

  • httpOnly

    string opcional

    Existencia del atributo de cookie HttpOnly.

  • maxAge

    número opcional

    Valor del atributo de cookie Max-Age

  • nombre

    string opcional

    Es el nombre de una cookie.

  • ruta de acceso

    string opcional

    Valor del atributo de cookie de ruta de acceso.

  • seguro

    string opcional

    Existencia del atributo Secure cookie

  • sessionCookie

    booleano opcional

    Filtra las cookies de sesión. Las cookies de sesión no tienen un ciclo de vida especificado en ninguno de los valores de "max-age". o “vence” atributos.

  • valor

    string opcional

    Valor de una cookie (se puede rellenar entre comillas dobles)

HeaderFilter

Filtra encabezados de solicitud para varios criterios. Si hay varios criterios, estos se evalúan como una conjunción.

Propiedades

  • nameContains

    string | string[] opcional

    Coincide si el nombre del encabezado contiene todas las cadenas especificadas.

  • nameEquals

    string opcional

    Coincide si el nombre del encabezado es igual a la cadena especificada.

  • Prefijo del nombre

    string opcional

    Coincide si el nombre del encabezado comienza con la cadena especificada.

  • nameSuffix

    string opcional

    Coincide si el nombre del encabezado termina con la cadena especificada.

  • valueContains

    string | string[] opcional

    Coincide si el valor del encabezado contiene todas las cadenas especificadas.

  • valueEquals

    string opcional

    Coincide si el valor del encabezado es igual a la string especificada.

  • valuePrefix

    string opcional

    Coincide si el valor del encabezado comienza con la string especificada.

  • valueSuffix

    string opcional

    Coincide si el valor del encabezado termina con la string especificada.

IgnoreRules

Enmascara todas las reglas que coinciden con los criterios especificados.

Propiedades

  • constructor

    void

    La función constructor se ve de la siguiente manera: 

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

  • hasTag

    string opcional

    Si está establecido, se ignoran las reglas con la etiqueta especificada. Esta omisión no es persistente, solo afecta a las reglas y sus acciones de la misma etapa de solicitud de red. Ten en cuenta que las reglas se ejecutan en orden descendente de sus prioridades. Esta acción afecta a las reglas de menor prioridad que la regla actual. Pueden o no ignorarse las reglas con la misma prioridad.

  • lowerPriorityThan

    número opcional

    Si se establece, se ignoran las reglas con una prioridad menor que el valor especificado. Este límite no se mantiene, solo afecta a las reglas y sus acciones de la misma etapa de solicitud de red.

RedirectByRegEx

Redirecciona una solicitud mediante la aplicación de una expresión regular en la URL. Las expresiones regulares usan la sintaxis RE2.

Propiedades

  • constructor

    void

    La función constructor se ve de la siguiente manera: 

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

  • de

    string

    Un patrón de coincidencia que puede contener grupos de captura. Para acercarse a las expresiones regulares de JavaScript, se hace referencia a los grupos de captura en la sintaxis de Perl ($1, $2, ...) en lugar de en la sintaxis RE2 (\1, \2, ...).

  • para

    string

    Patrón de destino.

RedirectRequest

Acción de evento declarativa que redirecciona una solicitud de red.

Propiedades

RedirectToEmptyDocument

Acción de evento declarativa que redirecciona una solicitud de red a un documento vacío.

Propiedades

RedirectToTransparentImage

Acción de evento declarativa que redirecciona una solicitud de red a una imagen transparente.

Propiedades

RemoveRequestCookie

Elimina una o más cookies de solicitud. Ten en cuenta que es preferible usar la API de cookies, ya que el procesamiento es más económico.

Propiedades

RemoveRequestHeader

Quita el encabezado de la solicitud del nombre especificado. No uses SetRequestHeader y RemoveRequestHeader con el mismo nombre de encabezado en la misma solicitud. Cada nombre de encabezado de solicitud aparece solo una vez en cada solicitud.

Propiedades

RemoveResponseCookie

Elimina una o más cookies de respuesta. Ten en cuenta que es preferible usar la API de cookies, ya que el procesamiento es más económico.

Propiedades

RemoveResponseHeader

Quita todos los encabezados de respuesta de los nombres y valores especificados.

Propiedades

  • constructor

    void

    La función constructor se ve de la siguiente manera: 

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

  • nombre

    string

    Nombre del encabezado de la solicitud HTTP (no distingue mayúsculas de minúsculas).

  • valor

    string opcional

    Valor del encabezado de la solicitud HTTP (no distingue mayúsculas de minúsculas).

RequestCookie

Un filtro o una especificación de una cookie en solicitudes HTTP.

Propiedades

  • nombre

    string opcional

    Es el nombre de una cookie.

  • valor

    string opcional

    Valor de una cookie (se puede rellenar entre comillas dobles)

RequestMatcher

Hace coincidir los eventos de red según diversos criterios.

Propiedades

  • constructor

    void

    La función constructor se ve de la siguiente manera: 

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

  • contentType

    string[] opcional

    Coincide si el tipo de medio MIME de una respuesta (del encabezado Content-Type HTTP) está incluido en la lista.

  • excludeContentType

    string[] opcional

    Coincide si el tipo de medio MIME de una respuesta (del encabezado Content-Type HTTP) no está contenido en la lista.

  • excludeRequestHeaders

    HeaderFilter[] opcional

    Coincide si ninguno de los encabezados de la solicitud coincide con ninguno de los HeaderFilters.

  • excludeResponseHeaders

    HeaderFilter[] opcional

    Coincide si ninguno de los encabezados de respuesta coincide con ninguno de los HeaderFilters.

  • firstPartyForCookiesUrl

    UrlFilter opcional

    Obsoleto

    Se ignora desde la versión 82.

    Coincide si se cumplen las condiciones de UrlFilter para el elemento "propio". URL de la solicitud. La "fuente" La URL de una solicitud, cuando está presente, puede ser diferente de la URL de destino de la solicitud y describe lo que se considera "de origen". en las verificaciones de cookies de terceros.

  • requestHeaders

    HeaderFilter[] opcional

    Coincide si alguno de los encabezados de solicitud coincide con alguno de los encabezados de solicitud.

  • resourceType

    ResourceType[] opcional

    Coincide si el tipo de solicitud de una solicitud está contenido en la lista. Se filtrarán las solicitudes que no coincidan con ninguno de los tipos.

  • responseHeaders

    HeaderFilter[] opcional

    Coincide si alguno de los encabezados de respuesta coincide con uno de los HeaderFilters.

  • etapas

    Etapa[] opcional

    Contiene una lista de cadenas que describen las etapas. Los valores permitidos son "onBeforeRequest", "onBeforeSendHeaders", "onHeadersReceived", "onAuthRequired". Si este atributo está presente, limitará las etapas aplicables a las que se indican. Ten en cuenta que toda la condición solo se aplica en etapas compatibles con todos los atributos.

  • thirdPartyForCookies

    booleano opcional

    Obsoleto

    Se ignora desde la versión 87.

    Si se configura como verdadera, coincide con las solicitudes que están sujetas a políticas de cookies de terceros. Si se configura como falsa, coincide con todas las demás solicitudes.

  • url

    UrlFilter opcional

    Coincide si se cumplen las condiciones de UrlFilter para la URL de la solicitud.

ResponseCookie

Es una especificación de una cookie en las respuestas HTTP.

Propiedades

  • dominio

    string opcional

    Valor del atributo cookie de dominio.

  • fecha de vencimiento

    string opcional

    Valor del atributo de cookie de vencimiento.

  • httpOnly

    string opcional

    Existencia del atributo de cookie HttpOnly.

  • maxAge

    número opcional

    Valor del atributo de cookie Max-Age

  • nombre

    string opcional

    Es el nombre de una cookie.

  • ruta de acceso

    string opcional

    Valor del atributo de cookie de ruta de acceso.

  • seguro

    string opcional

    Existencia del atributo Secure cookie

  • valor

    string opcional

    Valor de una cookie (se puede rellenar entre comillas dobles)

SendMessageToExtension

Activa el evento declarativeWebRequest.onMessage.

Propiedades

SetRequestHeader

Establece el encabezado de la solicitud del nombre especificado en el valor especificado. Si no existía un encabezado con el nombre especificado antes, se crea uno nuevo. La comparación de nombres de encabezados siempre distingue mayúsculas de minúsculas. Cada nombre de encabezado de solicitud aparece solo una vez en cada solicitud.

Propiedades

  • constructor

    void

    La función constructor se ve de la siguiente manera: 

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

  • nombre

    string

    Es el nombre del encabezado de la solicitud HTTP.

  • valor

    string

    Valor del encabezado de la solicitud HTTP.

Stage

Enum

"onBeforeRequest"

"onBeforeSendHeaders"

"onHeadersReceived"

“onAuthRequired”

Eventos

onMessage

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

Se activa cuando se envía un mensaje a través de declarativeWebRequest.SendMessageToExtension desde una acción de la API de solicitud web declarativa.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (details: object) => void

    • detalles

      objeto

      • documentId

        string opcional

        Un UUID del documento que realizó la solicitud

      • El ciclo de vida del documento.

      • frameId

        número

        El valor 0 indica que la solicitud se realiza en el marco principal; un valor positivo indica el ID de un submarco en el que se produce la solicitud. Si se carga el documento de un (sub)marco (type es main_frame o sub_frame), frameId indica el ID de este marco, no el ID del marco externo. Los IDs de marco son únicos dentro de una pestaña.

      • El tipo de marco en el que se produjo la navegación.

      • mensaje

        string

        El mensaje que envió la secuencia de comandos que realiza la llamada

      • method

        string

        Método HTTP estándar

      • parentDocumentId

        string opcional

        Un UUID del documento superior que posee este marco. Esto no se establece si no hay un elemento superior.

      • parentFrameId

        número

        ID del marco que une el marco que envió la solicitud. Configúralo en -1 si no existe un marco superior.

      • requestId

        string

        El ID de la solicitud. Los IDs de solicitud son únicos dentro de una sesión del navegador. Como resultado, podrían usarse para relacionar diferentes eventos de la misma solicitud.

      • de este proceso,

        Etapa

        Es la etapa de la solicitud de red durante la que se activó el evento.

      • tabId

        número

        El ID de la pestaña en la que se realiza la solicitud. Se establece en -1 si la solicitud no está relacionada con una pestaña.

      • timeStamp

        número

        El tiempo en el que se activa este indicador, en milisegundos desde el ciclo de entrenamiento.

      • Cómo se usará el recurso solicitado.

      • url

        string

onRequest

Proporciona la API de Declarative Event, que consta de addRules, removeRules y getRules.

Condiciones

RequestMatcher

Acciones

AddRequestCookie

AddResponseCookie

AddResponseHeader

CancelRequest

EditRequestCookie

EditResponseCookie

RedirectRequest

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

RemoveResponseCookie

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

SendMessageToExtension

IgnoreRules