chrome.declarativeWebRequest

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é

Version bêta ≤ MV2

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 ou https://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

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

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)=> {...}

  • 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

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)=> {...}

  • filtre

    RequestCookie

    Filtrez les cookies qui seront modifiés. Toutes les entrées vides sont ignorées.

  • modification

    RequestCookie

    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

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[] optional

    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[] optional

    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)=> {...}

  • 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)=> {...}

  • Source :

    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

RedirectToEmptyDocument

Action d'événement déclarative qui redirige une requête réseau vers un document vide.

Propriétés

RedirectToTransparentImage

Action d'événement déclaratif qui redirige une requête réseau vers une image transparente.

Propriétés

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

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

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

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)=> {...}

  • 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)=> {...}

  • 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ète

    Ignoré 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ète

    Ignoré 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

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)=> {...}

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

      • Cycle de vie dans lequel se trouve le document.

      • frameId

        number

        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 est main_frame ou sub_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.

      • 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

        number

        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

        Scène

        Étape de la requête réseau au cours de laquelle l'événement a été déclenché.

      • tabId

        number

        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

        number

        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

RequestMatcher

Actions

AddRequestCookie

AddResponseCookie

AddResponseHeader

CancelRequest

EditRequestCookie

EditResponseCookie

RedirectRequest

RedirectToTransparentImage

RedirectToEmptyDocument

RedirectByRegEx

RemoveRequestCookie

RemoveResponseCookie

RemoveRequestHeader

RemoveResponseHeader

SetRequestHeader

SendMessageToExtension

IgnoreRules