chrome.declarativeWebRequest

Descripción

Nota: Esta API dejó de estar disponible. 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ápido 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 extensión para usar esta API, junto con los permisos de host.

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

Disponibilidad

Canal beta ≤ MV2

Manifest

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 los hosts cuyas solicitudes de red 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, esta extensión puede configurar una regla para lo siguiente:

  • Cancela una solicitud a https://www.google.com o https://anything.else.com.
  • Enviar un mensaje cuando navegues 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 criterios de coincidencia: RequestMatcher. 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 ingrese https://www.example.com en el microservicio:

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, se rechazarán todas las solicitudes de un iframe incorporado debido a la resourceType.

Para cancelar todas las solicitudes de "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 las solicitudes web de la API de solicitud web. Esto significa que las condiciones solo se pueden probar 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 las etapas de la solicitud que son compatibles con las condiciones y las acciones.

Etapas de la solicitud durante las que 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 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 según 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 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 IgnoreRules, solo se aplicará a otras acciones ejecutadas 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 con el mismo nombre. Ten en cuenta que se prefiere usar la API de Cookies, ya que su 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 se prefiere usar la API de Cookies, ya que su 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 quitarlos y, luego, agregar uno nuevo para reemplazar uno.

Propiedades

  • constructor

    void

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

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

  • name

    cadena

    Nombre del encabezado de respuesta HTTP.

  • value

    cadena

    Valor del 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 se prefiere usar la API de Cookies, ya que su 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 generaron el filtro. Se quitan los atributos que se establecen en una cadena vacía.

EditResponseCookie

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

Propiedades

FilterResponseCookie

Un filtro de una cookie en las respuestas HTTP.

Propiedades

  • ageLowerBound

    número opcional

    Límite inferior inclusivo de la duración de la cookie (especificado en segundos después de la hora actual). Solo las cookies cuya fecha y hora de vencimiento se estableció en "ahora + ageLowerBound" o en una versión posterior cumplen con este criterio. Las cookies de sesión no cumplen con el criterio de este filtro. La duración de la cookie se calcula a partir de los atributos 'edad máxima' o 'vencimiento' de la cookie. Si se especifican ambos, el valor de "max-age" se utiliza para calcular la duración de la cookie.

  • ageUpperBound

    número opcional

    Límite superior inclusivo en 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 encuentra en el intervalo [ahora, ahora + ageUpperBound] cumplen con este criterio. Las cookies de sesión y las cookies cuya fecha y hora de vencimiento sea en el pasado no cumplen con el criterio de este filtro. La duración de la cookie se calcula a partir de los atributos 'edad máxima' o 'vencimiento' de la cookie. Si se especifican ambos, el valor de "max-age" se utiliza para calcular la duración de la cookie.

  • dominio

    cadena opcional

    Valor del atributo de cookie de dominio.

  • fecha de vencimiento

    cadena opcional

    Valor del atributo Vencimiento de la cookie.

  • httpOnly

    cadena opcional

    Existencia del atributo de cookie HttpOnly.

  • maxAge

    número opcional

    Valor del atributo de cookie Max-Age

  • name

    cadena opcional

    Es el nombre de una cookie.

  • ruta de acceso

    cadena opcional

    Valor del atributo de cookie de ruta de acceso.

  • 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 un ciclo de vida especificado en ninguno de los atributos "max-age" o "expires".

  • value

    cadena opcional

    Valor de una cookie; puede tener comillas dobles.

HeaderFilter

Filtra los encabezados de la solicitud para varios criterios. Varios criterios se evalúan como una conjunción.

Propiedades

  • nameContains

    string|string[] optional

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

  • nameEquals

    cadena opcional

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

  • namePrefix

    cadena opcional

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

  • nameSuffix

    cadena opcional

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

  • valueContains

    string|string[] optional

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

  • valueEquals

    cadena opcional

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

  • valuePrefix

    cadena opcional

    Coincide si el valor del encabezado comienza con la string 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. Esta omisión no persiste, solo afecta a las reglas y sus acciones de la misma etapa de solicitud de la red. Ten en cuenta que las reglas se ejecutan en orden descendente según sus prioridades. Esta acción afecta a las reglas de menor prioridad que la regla actual. Las reglas con la misma prioridad se pueden ignorar o no.

  • lowerPriorityThan

    número opcional

    Si se establece, se ignorarán las reglas con una prioridad inferior al valor especificado. Este límite no se conserva, solo afecta a las reglas y sus acciones en la misma etapa de solicitud de la 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

    cadena

    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 en la sintaxis RE2 (\1, \2, ...) para estar más cerca de las expresiones regulares de JavaScript.

  • para

    cadena

    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 se prefiere usar la API de Cookies, ya que su 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

Quita una o más cookies de respuesta. Ten en cuenta que se prefiere usar la API de Cookies, ya que su 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)=> {...}

  • name

    cadena

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

  • value

    cadena opcional

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

RequestCookie

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

Propiedades

  • name

    cadena opcional

    Es el nombre de una cookie.

  • value

    cadena opcional

    Valor de una cookie; puede tener 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 HTTP Content-Type) está incluido en la lista.

  • excludeContentType

    string[] opcional

    Coincide si el tipo de medio MIME de una respuesta (del encabezado HTTP Content-Type) no está incluido 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 ignoró desde la versión 82.

    Coincide si se cumplen las condiciones del UrlFilter para la URL "propia" de la solicitud. La URL "propia" de una solicitud, cuando está presente, puede ser diferente de la URL de destino de la solicitud y describe lo que se considera "propio" para la verificación de cookies de terceros.

  • requestHeaders

    HeaderFilter[] opcional

    Coincide si algunos de los encabezados de la solicitud coinciden con uno de los HeaderFilters.

  • 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 algunos de los encabezados de respuesta coinciden con uno de los HeaderFilters.

  • etapas

    Stage[] 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 enumeran. Tenga en cuenta que la condición completa solo se aplica en etapas compatibles con todos los atributos.

  • thirdPartyForCookies

    booleano opcional

    Obsoleto

    Se ignoró desde la versión 87.

    Si se configura como verdadera, coincide con las solicitudes que están sujetas a las 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 del UrlFilter para la URL de la solicitud.

ResponseCookie

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

Propiedades

  • dominio

    cadena opcional

    Valor del atributo de cookie de dominio.

  • fecha de vencimiento

    cadena opcional

    Valor del atributo Vencimiento de la cookie.

  • httpOnly

    cadena opcional

    Existencia del atributo de cookie HttpOnly.

  • maxAge

    número opcional

    Valor del atributo de cookie Max-Age

  • name

    cadena opcional

    Es el nombre de una cookie.

  • ruta de acceso

    cadena opcional

    Valor del atributo de cookie de ruta de acceso.

  • seguro

    cadena opcional

    Existencia del atributo de cookie segura

  • value

    cadena opcional

    Valor de una cookie; puede tener comillas dobles.

SendMessageToExtension

Activa el evento declarativeWebRequest.onMessage.

Propiedades

SetRequestHeader

Establece el encabezado de la solicitud del nombre especificado en el valor indicado. Si no existía antes un encabezado con el nombre especificado, se crea uno nuevo. La comparación de nombres de encabezado siempre no 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)=> {...}

  • name

    cadena

    Nombre del encabezado de la solicitud HTTP.

  • value

    cadena

    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

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

      • 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 una subtrama en la que ocurre la solicitud. Si se carga el documento de un (sub)marco (type es main_frame o sub_frame), frameId indica el ID de ese marco, no el ID del marco externo. Los IDs de marco son únicos dentro de una pestaña.

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

      • message

        cadena

        Es el mensaje que envía la secuencia de comandos que realiza la llamada.

      • method

        cadena

        Método HTTP estándar.

      • parentDocumentId

        cadena 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 al marco que envió la solicitud. Se establece en -1 si no existe un marco superior.

      • requestId

        cadena

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

      • de este proceso,

        Etapa

        La etapa de la solicitud de red durante la cual 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

        Es el momento en que se activa esta señal, en milisegundos desde el ciclo de entrenamiento.

      • Cómo se usará el recurso solicitado.

      • url

        cadena

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