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
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
ohttps://anything.else.com
. - Se envía un mensaje cuando navegas a
https://www.google.com
, pero no ahttps://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
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: AddRequestCookie) => {...}
-
argumento
-
muestra
-
-
galleta
Cookie que se agregará a la solicitud. Ningún campo puede estar indefinido.
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
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: AddResponseCookie) => {...}
-
argumento
-
muestra
-
-
galleta
Cookie que se agregará a la respuesta. Es necesario especificar el nombre y el valor.
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) => {...}
-
argumento
-
muestra
-
-
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
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: CancelRequest) => {...}
-
argumento
-
muestra
-
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) => {...}
-
argumento
-
muestra
-
-
filter
Filtra las cookies que se modificarán. Se ignoran todas las entradas vacías.
-
modificación
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
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: EditResponseCookie) => {...}
-
argumento
-
muestra
-
-
filter
Filtra las cookies que se modificarán. Se ignoran todas las entradas vacías.
-
modificación
Atributos que se deben anular en las cookies que configuraron el filtro. Se quitan los atributos que se establecen en una string vacía.
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) => {...}
-
argumento
-
muestra
-
-
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) => {...}
-
argumento
-
muestra
-
-
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
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: RedirectRequest) => {...}
-
argumento
-
muestra
-
-
redirectUrl
string
El destino al que se redirecciona la solicitud.
RedirectToEmptyDocument
Acción de evento declarativa que redirecciona una solicitud de red a un documento vacío.
Propiedades
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: RedirectToEmptyDocument) => {...}
-
argumento
-
muestra
-
RedirectToTransparentImage
Acción de evento declarativa que redirecciona una solicitud de red a una imagen transparente.
Propiedades
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: RedirectToTransparentImage) => {...}
-
argumento
-
muestra
-
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
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: RemoveRequestCookie) => {...}
-
argumento
-
muestra
-
-
filter
Filtra las cookies que se quitarán. Se ignoran todas las entradas vacías.
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
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: RemoveRequestHeader) => {...}
-
argumento
-
muestra
-
-
nombre
string
Nombre del encabezado de la solicitud HTTP (no distingue mayúsculas de minúsculas).
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
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: RemoveResponseCookie) => {...}
-
argumento
-
muestra
-
-
filter
Filtra las cookies que se quitarán. Se ignoran todas las entradas vacías.
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) => {...}
-
argumento
-
muestra
-
-
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) => {...}
-
argumento
-
muestra
-
-
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
ObsoletoSe 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
ObsoletoSe 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
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: SendMessageToExtension) => {...}
-
argumento
-
muestra
-
-
mensaje
string
El valor que se pasará en el atributo
message
del diccionario que se pasa al controlador de eventos.
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) => {...}
-
argumento
-
muestra
-
-
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
-
documentLifecycle
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
esmain_frame
osub_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. -
frameType
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,
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
Acciones