Description
Remarque:Cette API est obsolète. Consultez plutôt l'API declarativeNetRequest
. Utilisez l'API chrome.declarativeWebRequest
pour intercepter, bloquer ou modifier les requêtes en cours de transfert. Elle est beaucoup plus rapide que l'API chrome.webRequest
, car elle permet d'enregistrer des règles évaluées dans le navigateur plutôt que dans le moteur JavaScript, ce qui réduit les latences aller-retour et améliore l'efficacité.
Autorisations
declarativeWebRequest
Pour utiliser cette API, vous devez déclarer l'autorisation "declarativeWebRequest" dans le fichier manifeste de l'extension, ainsi que les autorisations d'hôte.
{
"name": "My extension",
...
"permissions": [
"declarativeWebRequest",
"*://*/*"
],
...
}
Garantie de disponibilité
Manifest
Notez que certains types d'actions non sensibles ne nécessitent pas d'autorisation d'accès à l'hôte:
CancelRequest
IgnoreRules
RedirectToEmptyDocument
RedirectToTransparentImage
L'action SendMessageToExtension()
nécessite des autorisations d'hôte pour tous les hôtes dont vous souhaitez déclencher un message sur les requêtes réseau.
Toutes les autres actions nécessitent des autorisations d'hôte pour toutes les URL.
Par exemple, si "https://*.google.com/*"
est la seule autorisation d'hôte dont dispose une extension, celle-ci peut configurer une règle pour:
- Annuler une requête envoyée à
https://www.google.com
ouhttps://anything.else.com
. - Envoyez un message lorsque vous accédez à
https://www.google.com
, mais pas àhttps://something.else.com
.
L'extension ne peut pas configurer de règle pour rediriger https://www.google.com
vers https://mail.google.com
.
Règles
L'API Declarative Web Request suit les concepts de l'API déclarative. Vous pouvez enregistrer des règles dans l'objet d'événement chrome.declarativeWebRequest.onRequest
.
L'API Declarative Web Request accepte un seul type de critère de correspondance : RequestMatcher
. RequestMatcher
correspond aux requêtes réseau si et seulement si tous les critères répertoriés sont remplis. L'élément RequestMatcher
suivant correspond à une requête réseau lorsque l'utilisateur saisit https://www.example.com
dans l'ominibox:
var matcher = new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'example.com', schemes: ['http'] },
resourceType: ['main_frame']
});
Les requêtes adressées à https://www.example.com
seraient refusées par RequestMatcher
en raison du schéma.
De plus, toutes les demandes d'iFrame intégré seront refusées pour la raison suivante : resourceType
.
Pour annuler toutes les requêtes envoyées à "example.com", vous pouvez définir une règle comme suit:
var rule = {
conditions: [
new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'example.com' } })
],
actions: [
new chrome.declarativeWebRequest.CancelRequest()
]
};
Pour annuler toutes les requêtes adressées à example.com
et foobar.com
, vous pouvez ajouter une deuxième condition, car chaque condition est suffisante pour déclencher toutes les actions spécifiées:
var rule2 = {
conditions: [
new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'example.com' } }),
new chrome.declarativeWebRequest.RequestMatcher({
url: { hostSuffix: 'foobar.com' } })
],
actions: [
new chrome.declarativeWebRequest.CancelRequest()
]
};
Enregistrez les règles comme suit:
chrome.declarativeWebRequest.onRequest.addRules([rule2]);
Évaluation des conditions et des actions
L'API déclarative Web Request suit le modèle de cycle de vie pour les requêtes Web de l'API Web Request. Cela signifie que les conditions ne peuvent être testées qu'à des étapes spécifiques d'une requête Web et que les actions ne peuvent également être exécutées qu'à des étapes spécifiques. Les tableaux suivants répertorient les étapes de requête compatibles avec les conditions et les actions.
Étapes de requête au cours desquelles les attributs de condition peuvent être traités. | ||||
---|---|---|---|---|
Attribut de condition | onBeforeRequest | onBeforeSendHeaders | onHeadersReceived | onAuthRequired |
url |
✓ | ✓ | ✓ | ✓ |
resourceType |
✓ | ✓ | ✓ | ✓ |
contentType |
✓ | |||
excludeContentType |
✓ | |||
responseHeaders |
✓ | |||
excludeResponseHeaders |
✓ | |||
requestHeaders |
✓ | |||
excludeRequestHeaders |
✓ | |||
thirdPartyForCookies |
✓ | ✓ | ✓ | ✓ |
Étapes de requête au cours desquelles des actions peuvent être exécutées. | ||||
Événement | onBeforeRequest | onBeforeSendHeaders | onHeadersReceived | onAuthRequired |
AddRequestCookie |
✓ | |||
AddResponseCookie |
✓ | |||
AddResponseHeader |
✓ | |||
CancelRequest |
✓ | ✓ | ✓ | ✓ |
EditRequestCookie |
✓ | |||
EditResponseCookie |
✓ | |||
IgnoreRules |
✓ | ✓ | ✓ | ✓ |
RedirectByRegEx |
✓ | ✓ | ||
RedirectRequest |
✓ | ✓ | ||
RedirectToEmptyDocument |
✓ | ✓ | ||
RedirectToTransparentImage |
✓ | ✓ | ||
RemoveRequestCookie |
✓ | |||
RemoveRequestHeader |
✓ | |||
RemoveResponseCookie |
✓ | |||
RemoveResponseHeader |
✓ | |||
SendMessageToExtension |
✓ | ✓ | ✓ | ✓ |
SetRequestHeader |
✓ |
Utiliser des priorités pour remplacer les règles
Les règles peuvent être associées à des priorités, comme décrit dans l'API Events. Ce mécanisme peut être utilisé pour exprimer des exceptions. L'exemple suivant bloque toutes les requêtes envoyées aux images nommées evil.jpg
, sauf sur le serveur "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]);
Il est important de savoir que l'action IgnoreRules
n'est pas conservée entre les étapes de la requête. Toutes les conditions de toutes les règles sont évaluées à chaque étape d'une requête Web. Si une action IgnoreRules
est exécutée, elle ne s'applique qu'aux autres actions exécutées pour la même requête Web à la même étape.
Types
AddRequestCookie
Ajoute un cookie à la demande ou remplace un cookie au cas où un autre cookie du même nom existerait déjà. Notez qu'il est préférable d'utiliser l'API Cookies, car elle est moins coûteuse en calcul.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: AddRequestCookie) => {...}
-
arg
-
retours
-
-
biscuit
Cookie à ajouter à la demande. Aucun champ ne peut être indéfini.
AddResponseCookie
Ajoute un cookie à la réponse ou remplace un cookie au cas où un autre cookie du même nom existe déjà. Notez qu'il est préférable d'utiliser l'API Cookies, car elle est moins coûteuse en calcul.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: AddResponseCookie) => {...}
-
retours
-
-
biscuit
Cookie à ajouter à la réponse. Vous devez spécifier le nom et la valeur.
AddResponseHeader
Ajoute l'en-tête de réponse à la réponse de cette requête Web. Étant donné que plusieurs en-têtes de réponse peuvent porter le même nom, vous devez d'abord les supprimer, puis en ajouter un autre pour en remplacer un.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: AddResponseHeader) => {...}
-
retours
-
-
name
chaîne
Nom de l'en-tête de réponse HTTP.
-
valeur
chaîne
Valeur de l'en-tête de réponse HTTP.
CancelRequest
Action d'événement déclarative qui annule une requête réseau.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: CancelRequest) => {...}
-
arg
-
retours
-
EditRequestCookie
Modifie un ou plusieurs cookies de la requête. Notez qu'il est préférable d'utiliser l'API Cookies, car elle est moins coûteuse en calcul.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: EditRequestCookie) => {...}
-
retours
-
-
filtre
Filtrez les cookies qui seront modifiés. Toutes les entrées vides sont ignorées.
-
modification
Attributs à remplacer dans les cookies ayant appliqué le filtre. Les attributs définis sur une chaîne vide sont supprimés.
EditResponseCookie
Modifie un ou plusieurs cookies de réponse. Notez qu'il est préférable d'utiliser l'API Cookies, car elle est moins coûteuse en calcul.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: EditResponseCookie) => {...}
-
retours
-
-
filtre
Filtrez les cookies qui seront modifiés. Toutes les entrées vides sont ignorées.
-
modification
Attributs à remplacer dans les cookies ayant appliqué le filtre. Les attributs définis sur une chaîne vide sont supprimés.
FilterResponseCookie
Filtre d'un cookie dans les réponses HTTP.
Propriétés
-
ageLowerBound
numéro facultatif
Limite inférieure incluse pour la durée de vie du cookie (spécifiée en secondes après l'heure actuelle). Seuls les cookies dont la date d'expiration est définie sur "now + ageLowerBound" ou ultérieure remplissent ce critère. Les cookies de session ne répondent pas aux critères de ce filtre. La durée de vie des cookies est calculée à partir des attributs "max-age" ou "expires". Si les deux valeurs sont spécifiées, la valeur "max-age" est utilisée pour calculer la durée de vie du cookie.
-
ageUpperBound
numéro facultatif
Limite supérieure d'inclusion de la durée de vie du cookie (spécifiée en secondes après l'heure actuelle). Seuls les cookies dont la date et l'heure d'expiration se trouvent dans l'intervalle [now, now + ageUpperBound] remplissent ce critère. Les cookies de session et les cookies dont la date et l'heure d'expiration sont passées ne répondent pas aux critères de ce filtre. La durée de vie des cookies est calculée à partir des attributs "max-age" ou "expires". Si les deux valeurs sont spécifiées, la valeur "max-age" est utilisée pour calculer la durée de vie du cookie.
-
domaine
string facultatif
Valeur de l'attribut cookie de domaine.
-
expire le, expiration
string facultatif
Valeur de l'attribut de cookie d'expiration.
-
httpOnly
string facultatif
Existence de l'attribut de cookie HttpOnly
-
maxAge
numéro facultatif
Valeur de l'attribut de cookie Max-Age
-
name
string facultatif
Nom d'un cookie.
-
chemin d'accès
string facultatif
Valeur de l'attribut de cookie de chemin.
-
sécurisé
string facultatif
Existence de l'attribut de cookie sécurisé
-
sessionCookie
Booléen facultatif
Filtre les cookies de session. Aucune durée de vie n'est spécifiée pour les cookies de session dans les attributs "max-age" et "expires".
-
valeur
string facultatif
La valeur d'un cookie peut être placée entre guillemets.
HeaderFilter
Filtre les en-têtes de requêtes pour différents critères. Les critères multiples sont évalués comme une conjonction.
Propriétés
-
nameContains
string | string[] facultatif
Correspond si le nom de l'en-tête contient toutes les chaînes spécifiées.
-
nameEquals
string facultatif
Correspond si le nom de l'en-tête est égal à la chaîne spécifiée.
-
namePrefix
string facultatif
Correspond si le nom de l'en-tête commence par la chaîne spécifiée.
-
nameSuffix
string facultatif
Correspond si le nom de l'en-tête se termine par la chaîne spécifiée.
-
valueContains
string | string[] facultatif
Correspond si la valeur de l'en-tête contient toutes les chaînes spécifiées.
-
valueEquals
string facultatif
Correspond si la valeur de l'en-tête est égale à la chaîne spécifiée.
-
valuePrefix
string facultatif
Correspond si la valeur de l'en-tête commence par la chaîne spécifiée.
-
valueSuffix
string facultatif
Correspond si la valeur de l'en-tête se termine par la chaîne spécifiée.
IgnoreRules
Masque toutes les règles correspondant aux critères spécifiés.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: IgnoreRules) => {...}
-
arg
-
retours
-
-
hasTag
string facultatif
Si cette valeur est définie, les règles contenant la balise spécifiée sont ignorées. Cet omission n'est pas conservée. Il n'affecte que les règles et leurs actions associées à la même étape de requête réseau. Notez que les règles sont exécutées dans l'ordre décroissant de leurs priorités. Cette action concerne les règles dont la priorité est inférieure à celle de la règle actuelle. Les règles ayant la même priorité peuvent être ignorées ou non.
-
lowerPriorityThan
numéro facultatif
Si cette règle est définie, les règles dont la priorité est inférieure à la valeur spécifiée sont ignorées. Cette limite n'est pas conservée. Elle n'affecte que les règles et leurs actions associées à la même étape de requête réseau.
RedirectByRegEx
Redirige une requête en appliquant une expression régulière à l'URL. Les expressions régulières utilisent la syntaxe RE2.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: RedirectByRegEx) => {...}
-
arg
-
retours
-
-
depuis
chaîne
Modèle de correspondance pouvant contenir des groupes de capture. Les groupes de capture sont référencés dans la syntaxe Perl ($1, $2, ...) au lieu de la syntaxe RE2 (\1, \2, ...) afin d'être plus proches des expressions régulières JavaScript.
-
pour
chaîne
Modèle de destination.
RedirectRequest
Action d'événement déclarative qui redirige une requête réseau.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: RedirectRequest) => {...}
-
arg
-
retours
-
-
redirectUrl
chaîne
Destination vers laquelle la requête est redirigée.
RedirectToEmptyDocument
Action d'événement déclarative qui redirige une requête réseau vers un document vide.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: RedirectToEmptyDocument) => {...}
-
retours
-
RedirectToTransparentImage
Action d'événement déclaratif qui redirige une requête réseau vers une image transparente.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: RedirectToTransparentImage) => {...}
-
retours
-
RemoveRequestCookie
Supprime un ou plusieurs cookies de la requête. Notez qu'il est préférable d'utiliser l'API Cookies, car elle est moins coûteuse en calcul.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: RemoveRequestCookie) => {...}
-
retours
-
-
filtre
Filtrez les cookies qui seront supprimés. Toutes les entrées vides sont ignorées.
RemoveRequestHeader
Supprime l'en-tête de requête du nom spécifié. N'utilisez pas SetRequestHeader et SupprimerRequestHeader avec le même nom d'en-tête dans la même requête. Chaque nom d'en-tête de requête n'apparaît qu'une seule fois dans chaque requête.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: RemoveRequestHeader) => {...}
-
retours
-
-
name
chaîne
Nom de l'en-tête de requête HTTP (non sensible à la casse).
RemoveResponseCookie
Supprime un ou plusieurs cookies de réponse. Notez qu'il est préférable d'utiliser l'API Cookies, car elle est moins coûteuse en calcul.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: RemoveResponseCookie) => {...}
-
retours
-
-
filtre
Filtrez les cookies qui seront supprimés. Toutes les entrées vides sont ignorées.
RemoveResponseHeader
Supprime tous les en-têtes de réponse des noms et des valeurs spécifiés.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: RemoveResponseHeader) => {...}
-
retours
-
-
name
chaîne
Nom de l'en-tête de requête HTTP (non sensible à la casse).
-
valeur
string facultatif
Valeur de l'en-tête de requête HTTP (non sensible à la casse).
RequestCookie
Filtre ou spécification d'un cookie dans les requêtes HTTP.
Propriétés
-
name
string facultatif
Nom d'un cookie.
-
valeur
string facultatif
La valeur d'un cookie peut être placée entre guillemets.
RequestMatcher
Fait correspondre les événements réseau selon différents critères.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: RequestMatcher) => {...}
-
arg
-
retours
-
-
contentType
string[] facultatif
Recherche une correspondance si le type de média MIME d'une réponse (à partir de l'en-tête HTTP Content-Type) figure dans la liste.
-
excludeContentType
string[] facultatif
Recherche une correspondance si le type de média MIME d'une réponse (à partir de l'en-tête HTTP Content-Type) ne figure pas dans la liste.
-
excludeRequestHeaders
HeaderFilter[] facultatif
Correspond si aucun des en-têtes de requête ne correspond à l'un des HeaderFilters.
-
excludeResponseHeaders
HeaderFilter[] facultatif
Correspond si aucun des en-têtes de réponse ne correspond à l'un des HeaderFilters.
-
firstPartyForCookiesUrl
UrlFilter facultatif
ObsolèteIgnoré depuis la version 82.
Recherche une correspondance si les conditions de l'élément UrlFilter sont remplies pour l'URL "propriétaire" de la requête. L'URL "propriétaire" d'une requête, lorsqu'elle est présente, peut être différente de l'URL cible de la requête. Elle décrit ce qui est considéré comme "propriétaire" en vue des vérifications de cookies tierces.
-
requestHeaders
HeaderFilter[] facultatif
établit une correspondance si certains en-têtes de requête correspondent à l'un des HeaderFilters.
-
resourceType
ResourceType[] facultatif
Établir une correspondance si le type d'une requête est contenu dans la liste. Les requêtes qui ne correspondent à aucun des types seront filtrées.
-
responseHeaders
HeaderFilter[] facultatif
Recherche une correspondance si certains en-têtes de réponse correspondent à l'un des en-têtes HeaderFilters.
-
étapes
Étape[] facultative
Contient une liste de chaînes décrivant les étapes. Les valeurs autorisées sont "onBeforeRequest", "onBeforeSendHeaders", "onHeadersReceived", "onAuthRequired". Si cet attribut est présent, les étapes applicables sont limitées à celles indiquées. Notez que l'ensemble de la condition n'est applicable qu'aux étapes compatibles avec tous les attributs.
-
thirdPartyForCookies
Booléen facultatif
ObsolèteIgnoré depuis la version 87.
Si la valeur est "true", met en correspondance les demandes soumises aux règles relatives aux cookies tiers. Si défini sur "false", correspond à toutes les autres requêtes.
-
url
UrlFilter facultatif
Recherche une correspondance si les conditions de l'élément UrlFilter sont remplies pour l'URL de la requête.
ResponseCookie
Spécification d'un cookie dans les réponses HTTP.
Propriétés
-
domaine
string facultatif
Valeur de l'attribut cookie de domaine.
-
expire le, expiration
string facultatif
Valeur de l'attribut de cookie d'expiration.
-
httpOnly
string facultatif
Existence de l'attribut de cookie HttpOnly
-
maxAge
numéro facultatif
Valeur de l'attribut de cookie Max-Age
-
name
string facultatif
Nom d'un cookie.
-
chemin d'accès
string facultatif
Valeur de l'attribut de cookie de chemin.
-
sécurisé
string facultatif
Existence de l'attribut de cookie sécurisé
-
valeur
string facultatif
La valeur d'un cookie peut être placée entre guillemets.
SendMessageToExtension
Déclenche l'événement declarativeWebRequest.onMessage
.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: SendMessageToExtension) => {...}
-
retours
-
-
message
chaîne
Valeur qui sera transmise dans l'attribut
message
du dictionnaire transmis au gestionnaire d'événements.
SetRequestHeader
Définit l'en-tête de requête du nom spécifié sur la valeur spécifiée. Si un en-tête portant le nom spécifié n'existait pas auparavant, un en-tête est créé. La comparaison des noms d'en-tête n'est toujours pas sensible à la casse. Chaque nom d'en-tête de requête n'apparaît qu'une seule fois dans chaque requête.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: SetRequestHeader) => {...}
-
arg
-
retours
-
-
name
chaîne
Nom de l'en-tête de requête HTTP.
-
valeur
chaîne
Valeur de l'en-tête de requête HTTP.
Stage
Enum
"onBeforeRequest"
"onBeforeSendHeaders"
"onHeadersReceived"
"onAuthRequired"
Événements
onMessage
chrome.declarativeWebRequest.onMessage.addListener(
callback: function,
)
Déclenché lorsqu'un message est envoyé via declarativeWebRequest.SendMessageToExtension
à partir d'une action de l'API de requête Web déclarative.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(details: object) => void
-
détails
objet
-
documentId
string facultatif
Un UUID du document à l'origine de la demande.
-
documentLifecycle
Cycle de vie dans lequel se trouve le document.
-
frameId
Nombre
La valeur 0 indique que la requête se produit dans la trame principale ; une valeur positive indique l'ID d'un sous-frame dans lequel la requête est effectuée. Si le document d'un (sous-)cadre est chargé (
type
estmain_frame
ousub_frame
),frameId
indique l'ID de ce cadre, et non celui du cadre extérieur. Les ID de frame sont uniques au sein d'un onglet. -
frameType
Type de frame dans lequel la navigation s'est produite.
-
message
chaîne
Message envoyé par le script appelant.
-
method
chaîne
Méthode HTTP standard.
-
parentDocumentId
string facultatif
UUID du document parent propriétaire de ce frame. Cette valeur n'est pas définie s'il n'y a pas de parent.
-
parentFrameId
Nombre
ID de la trame qui encapsule la trame qui a envoyé la requête. Définissez la valeur sur -1 si aucun frame parent n'existe.
-
requestId
chaîne
ID de la requête. Les ID de requête sont uniques dans une session de navigateur. Par conséquent, ils peuvent servir à associer différents événements de la même requête.
-
étape
Étape de la requête réseau au cours de laquelle l'événement a été déclenché.
-
tabId
Nombre
L'ID de l'onglet dans lequel la requête a lieu. Définissez cette valeur sur -1 si la requête n'est pas liée à un onglet.
-
timeStamp
Nombre
Heure à laquelle ce signal est déclenché, en millisecondes depuis l'epoch.
-
Mode d'utilisation de la ressource demandée
-
url
chaîne
-
-
onRequest
Fournit l'API Declarative Event composée de addRules
, removeRules
et getRules
.
Conditions
Actions