chrome.declarativeWebRequest

Descripción

Nota: Esta API está obsoleta. En su lugar, consulta la API de declarativeNetRequest. 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 porque puedes registrar reglas que se evalúan en el navegador en lugar del motor de JavaScript, lo que reduce las latencias de ida y vuelta y permite una mayor eficiencia.

Permisos

declarativeWebRequest

Debes declarar el permiso "declarativeWebRequest" en el manifiesto de la extensión para usar esta API, 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 en el que desees activar un mensaje en las solicitudes de red.

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, esta puede configurar una regla para hacer lo siguiente:

  • Cancela una solicitud a https://www.google.com o https://anything.else.com.
  • Enviar un mensaje cuando se navega 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 registrar reglas en el objeto de evento chrome.declarativeWebRequest.onRequest.

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

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

El RequestMatcher rechazaría las solicitudes a https://www.example.com debido al esquema. Además, se rechazarían todas las solicitudes de un iframe integrado 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 API de Web Request. Esto significa que las condiciones solo se pueden probar en etapas específicas de una solicitud web y, de la misma manera, las acciones solo se pueden ejecutar en etapas específicas. En las siguientes tablas, se enumeran las etapas de la solicitud que son compatibles con las condiciones y las acciones.

Son las 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 ✓ ✓ ✓ ✓
Son las etapas de la solicitud 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 ✓

Cómo usar prioridades para anular reglas

Las reglas se pueden asociar con prioridades, como se describe en la API de Events. Este mecanismo se puede usar para expresar excepciones. En el siguiente ejemplo, se bloquean todas las solicitudes a las imágenes llamadas 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 las etapas de la solicitud. Todas las condiciones de todas las reglas se evalúan en cada etapa de una solicitud web. Si se ejecuta una acción de IgnoreRules, solo se aplica a otras acciones que se ejecutan para la misma solicitud web en la misma etapa.

Tipos

AddRequestCookie

Agrega una cookie a la solicitud o anula una cookie, en caso de que ya exista otra cookie con el mismo nombre. Ten en cuenta que se prefiere usar la API de Cookies porque es menos costosa desde el punto de vista computacional.

Propiedades

AddResponseCookie

Agrega una cookie a la respuesta o anula una cookie, en caso de que ya exista otra cookie con el mismo nombre. Ten en cuenta que se prefiere usar la API de Cookies porque es menos costosa desde el punto de vista computacional.

Propiedades

AddResponseHeader

Agrega el encabezado de respuesta a la respuesta de esta solicitud web. Como varios encabezados de respuesta pueden compartir el mismo nombre, primero debes quitar un encabezado de respuesta y, luego, agregar uno nuevo para reemplazarlo.

Propiedades

  • constructor

    void

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

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

  • nombre

    string

    Es el nombre del encabezado de respuesta HTTP.

  • valor

    string

    Es el valor del encabezado de respuesta HTTP.

CancelRequest

Es una acción de evento declarativa que cancela una solicitud de red.

Propiedades

EditRequestCookie

Edita una o más cookies de la solicitud. Ten en cuenta que se prefiere usar la API de Cookies porque es menos costosa desde el punto de vista computacional.

Propiedades

  • constructor

    void

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

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

  • filtrar

    RequestCookie

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

  • modificación

    RequestCookie

    Son los atributos que se anularán en las cookies que coincidan con el filtro. Se quitan los atributos que se establecen en una cadena vacía.

EditResponseCookie

Edita una o más cookies de la respuesta. Ten en cuenta que se prefiere usar la API de Cookies porque es menos costosa desde el punto de vista computacional.

Propiedades

  • constructor

    void

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

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

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

  • modificación

    ResponseCookie

    Son los atributos que se anularán en las cookies que coincidan con el filtro. Se quitan los atributos que se establecen en una cadena vacía.

FilterResponseCookie

Es un filtro de una cookie en las respuestas HTTP.

Propiedades

  • ageLowerBound

    número opcional

    Es el límite inferior inclusivo de la vida útil de la cookie (especificado en segundos después de la hora actual). Solo las cookies cuya fecha y hora de vencimiento se establecen en "ahora + ageLowerBound" o en una fecha posterior cumplen con este criterio. Las cookies de sesión no cumplen con el criterio de este filtro. La vida útil de la cookie se calcula a partir de los atributos de cookie "max-age" o "expires". Si se especifican ambos, se usa "max-age" para calcular la vida útil de la cookie.

  • ageUpperBound

    número opcional

    Límite superior inclusivo de la vida útil de la cookie (especificado en segundos después de la hora actual). Solo las cookies cuya fecha y hora de vencimiento se encuentran en el intervalo [ahora, ahora + ageUpperBound] cumplen con este criterio. Las cookies de sesión y las cookies cuya fecha y hora de vencimiento ya pasaron no cumplen con el criterio de este filtro. La vida útil de la cookie se calcula a partir de los atributos de cookie "max-age" o "expires". Si se especifican ambos, se usa "max-age" para calcular la vida útil de la cookie.

  • dominio

    cadena opcional

    Valor del atributo de la cookie de dominio.

  • fecha de vencimiento

    cadena opcional

    Es el valor del atributo de cookie Expires.

  • httpOnly

    cadena opcional

    Existencia del atributo de cookie HttpOnly

  • maxAge

    número opcional

    Valor del atributo de cookie Max-Age

  • nombre

    cadena opcional

    Es el nombre de una cookie.

  • ruta de acceso

    cadena opcional

    Valor del atributo de la cookie Path.

  • seguro

    cadena opcional

    Existencia del atributo de cookie segura.

  • sessionCookie

    booleano opcional

    Filtra las cookies de sesión. Las cookies de sesión no tienen una vida útil especificada en ninguno de los atributos "max-age" o "expires".

  • valor

    cadena opcional

    Es el valor de una cookie, que puede estar completado con comillas dobles.

HeaderFilter

Filtra los encabezados de solicitud según varios criterios. Se evalúan varios criterios como una conjunción.

Propiedades

  • nameContains

    cadena | cadena[] opcional

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

  • nameEquals

    cadena opcional

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

  • Prefijo del nombre

    cadena opcional

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

  • nameSuffix

    cadena opcional

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

  • valueContains

    cadena | cadena[] opcional

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

  • valueEquals

    cadena opcional

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

  • valuePrefix

    cadena opcional

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

  • valueSuffix

    cadena opcional

    Coincide si el valor del encabezado termina con la cadena 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

    cadena opcional

    Si se configura, se ignoran las reglas con la etiqueta especificada. Este ignorado no se conserva, solo afecta 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. Es posible que se ignoren o no las reglas con la misma prioridad.

  • lowerPriorityThan

    número opcional

    Si se configura, se ignoran las reglas con una prioridad inferior al valor especificado. Este límite no se conserva, solo afecta las reglas y sus acciones de la misma etapa de solicitud de red.

RedirectByRegEx

Redirecciona una solicitud aplicando 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

    Es un patrón de coincidencia que puede contener grupos de captura. Se hace referencia a los grupos de captura en la sintaxis de Perl ($1, $2,…) en lugar de la sintaxis de RE2 (\1, \2,…) para estar más cerca de las expresiones regulares de JavaScript.

  • a

    string

    Es el patrón de destino.

RedirectRequest

Es una acción de evento declarativa que redirecciona una solicitud de red.

Propiedades

  • constructor

    void

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

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

  • redirectUrl

    string

    Es el destino al que se redirecciona la solicitud.

RedirectToEmptyDocument

Es una 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

Quita una o más cookies de la solicitud. Ten en cuenta que se prefiere usar la API de Cookies porque es menos costosa desde el punto de vista computacional.

Propiedades

RemoveRequestHeader

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

Propiedades

RemoveResponseCookie

Quita una o más cookies de la respuesta. Ten en cuenta que se prefiere usar la API de Cookies porque es menos costosa desde el punto de vista computacional.

Propiedades

RemoveResponseHeader

Quita todos los encabezados de respuesta con 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

    cadena opcional

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

RequestCookie

Es un filtro o una especificación de una cookie en las solicitudes HTTP.

Propiedades

  • nombre

    cadena opcional

    Es el nombre de una cookie.

  • valor

    cadena opcional

    Es el valor de una cookie, que puede estar completado con comillas dobles.

RequestMatcher

Coincide con los eventos de red según varios 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 de HTTP) se incluye en la lista.

  • excludeContentType

    string[] opcional

    Coincide si el tipo de medio MIME de una respuesta (del encabezado HTTP Content-Type) no se incluye 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 la URL de "primera entidad" de la solicitud. La URL de "origen" de una solicitud, cuando está presente, puede ser diferente de la URL de destino de la solicitud y describe lo que se considera "origen" a los efectos de las verificaciones de terceros para las cookies.

  • requestHeaders

    HeaderFilter[] opcional

    Coincide si alguno de los encabezados de la solicitud coincide con uno de los HeaderFilters.

  • resourceType

    ResourceType[] opcional

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

  • responseHeaders

    HeaderFilter[] opcional

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

  • etapas

    Etapa[] opcional

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

  • thirdPartyForCookies

    booleano opcional

    Obsoleto

    Se ignora desde la versión 87.

    Si se establece como verdadero, coincide con las solicitudes que están sujetas a políticas de cookies de terceros. Si se establece como falso, 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

    cadena opcional

    Valor del atributo de la cookie de dominio.

  • fecha de vencimiento

    cadena opcional

    Es el valor del atributo de cookie Expires.

  • httpOnly

    cadena opcional

    Existencia del atributo de cookie HttpOnly

  • maxAge

    número opcional

    Valor del atributo de cookie Max-Age

  • nombre

    cadena opcional

    Es el nombre de una cookie.

  • ruta de acceso

    cadena opcional

    Valor del atributo de la cookie Path.

  • seguro

    cadena opcional

    Existencia del atributo de cookie segura.

  • valor

    cadena opcional

    Es el valor de una cookie, que puede estar completado con 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, se crea uno nuevo. La comparación de nombres de encabezado siempre distingue mayúsculas de minúsculas. Cada nombre de encabezado de la 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

    Es el 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 solicitudes web declarativas.

Parámetros

  • callback

    función

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

    (details: object) => void

    • detalles

      objeto

      • documentId

        cadena opcional

        Es un UUID del documento que realizó la solicitud.

      • Es el ciclo de vida en el que se encuentra el 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 realiza 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 fotogramas son únicos dentro de una pestaña.

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

      • mensaje

        string

        Es el mensaje que envía el script de llamada.

      • método

        string

        Es el método HTTP estándar.

      • parentDocumentId

        cadena opcional

        Es un UUID del documento principal que posee este fotograma. No se establece si no hay un elemento superior.

      • parentFrameId

        número

        ID del iframe que contiene el iframe que envió la solicitud. Se establece en -1 si no existe un fotograma principal.

      • requestId

        string

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

      • de este proceso,

        Etapa

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

      • tabId

        número

        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

        Es la fecha y hora en que se activó este indicador, en milisegundos desde la época.

      • 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