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
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
ohttps://anything.else.com
. - Enviar un mensaje cuando navegues 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 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
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: AddRequestCookie) => {...}
-
argumento
-
resultados
-
-
galleta
Es la cookie que se agregará a la solicitud. Ningún campo puede estar sin definir.
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
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: AddResponseCookie) => {...}
-
argumento
-
resultados
-
-
galleta
Es la cookie que se agregará a la respuesta. Se deben 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 quitarlos y, luego, agregar uno nuevo para reemplazar uno.
Propiedades
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: AddResponseHeader) => {...}
-
argumento
-
resultados
-
-
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
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: CancelRequest) => {...}
-
argumento
-
resultados
-
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) => {...}
-
argumento
-
resultados
-
-
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 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
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: EditResponseCookie) => {...}
-
argumento
-
resultados
-
-
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 generaron el filtro. Se quitan los atributos que se establecen en una cadena vacía.
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
cadena | string[] opcional
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
cadena | string[] 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 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) => {...}
-
argumento
-
resultados
-
-
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) => {...}
-
argumento
-
resultados
-
-
from
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
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: RedirectRequest) => {...}
-
argumento
-
resultados
-
-
redirectUrl
cadena
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
-
resultados
-
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
-
resultados
-
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
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: RemoveRequestCookie) => {...}
-
argumento
-
resultados
-
-
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
-
resultados
-
-
name
cadena
Nombre del encabezado de la solicitud HTTP (no distingue mayúsculas de minúsculas).
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
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: RemoveResponseCookie) => {...}
-
argumento
-
resultados
-
-
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
-
resultados
-
-
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) => {...}
-
argumento
-
resultados
-
-
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
ObsoletoSe 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
ObsoletoSe 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
-
constructor
void
La función
constructor
se ve de la siguiente manera:(arg: SendMessageToExtension) => {...}
-
argumento
-
resultados
-
-
mensaje
cadena
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 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) => {...}
-
argumento
-
resultados
-
-
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.
-
documentLifecycle
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
esmain_frame
osub_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. -
frameType
Es el tipo de marco en el que ocurrió la navegación.
-
mensaje
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,
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
Acciones