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 considérablement plus rapide que l'API chrome.webRequest, car elle permet d'enregistrer des règles qui sont évaluées dans le navigateur plutôt que dans le moteur JavaScript, avec à la clé un gain d'efficacité et de temps en termes de latence.

Autorisations

declarativeWebRequest

Vous devez déclarer l'autorisation "declarativeWebRequest" dans le manifeste de l'extension pour utiliser cette API, ainsi que les autorisations d'hôte.

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

Disponibilité

Version bêta &leq MV2

Fichier manifeste

Notez que certains types d'actions non sensibles ne nécessitent pas d'autorisations d'organisateur :

  • CancelRequest
  • IgnoreRules
  • RedirectToEmptyDocument
  • RedirectToTransparentImage

L'action SendMessageToExtension() nécessite des autorisations d'hôte pour tous les hôtes sur lesquels vous souhaitez déclencher un message pour 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 demande à https://www.google.com ou https://anything.else.com
  • Envoyer un message lorsque vous naviguez vers https://www.google.com, mais pas vers 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 Declarative. Vous pouvez enregistrer des règles dans l'objet d'événement chrome.declarativeWebRequest.onRequest.

L'API Declarative Web Request n'accepte qu'un seul type de critère de correspondance, RequestMatcher. RequestMatcher correspond aux requêtes réseau si et seulement si tous les critères listés sont remplis. Le RequestMatcher suivant correspondrait à une requête réseau lorsque l'utilisateur saisit https://www.example.com dans l'omnibox :

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 rejetées par RequestMatcher en raison du schéma. De plus, toutes les demandes d'iframe intégré seront refusées en raison de resourceType.

Pour annuler toutes les requêtes adressé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 demandes à example.com et foobar.com, vous pouvez ajouter une deuxième condition, car chaque condition suffit à 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 Declarative 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, de même, les actions ne peuvent être exécutées qu'à des étapes spécifiques. Les tableaux suivants listent les étapes de la requête compatibles avec les conditions et les actions.

Étapes de la demande 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 la 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 des 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 noter que l'action IgnoreRules n'est pas conservée dans 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 dans la même étape.

Types

AddRequestCookie

Ajoute un cookie à la requête ou remplace un cookie, si 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 termes de calcul.

Propriétés

AddResponseCookie

Ajoute un cookie à la réponse ou remplace un cookie, si 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 termes de 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 partager le même nom, vous devez d'abord supprimer un en-tête de réponse, puis en ajouter un nouveau pour le remplacer.

Propriétés

  • constructor

    vide

    La fonction constructor se présente comme suit : 

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

  • nom

    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 termes de calcul.

Propriétés

  • constructor

    vide

    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 correspondant au 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 termes de calcul.

Propriétés

FilterResponseCookie

Filtre d'un cookie dans les réponses HTTP.

Propriétés

  • ageLowerBound

    number facultatif

    Limite inférieure incluse 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 sont définies sur "maintenant + ageLowerBound" ou une date ultérieure répondent à ce critère. Les cookies de session ne répondent pas aux critères de ce filtre. La durée de vie du cookie est calculée à partir des attributs de cookie "max-age" ou "expires". Si les deux sont spécifiés, "max-age" est utilisé pour calculer la durée de vie du cookie.

  • ageUpperBound

    number facultatif

    Limite supérieure incluse 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 situent dans l'intervalle [maintenant, maintenant + ageUpperBound] répondent à ce critère. Les cookies de session et ceux dont la date et l'heure d'expiration sont passées ne répondent pas au critère de ce filtre. La durée de vie du cookie est calculée à partir des attributs de cookie "max-age" ou "expires". Si les deux sont spécifiés, "max-age" est utilisé pour calculer la durée de vie du cookie.

  • domaine

    chaîne facultatif

    Valeur de l'attribut de cookie "Domain".

  • expire le

    chaîne facultatif

    Valeur de l'attribut de cookie "Expires".

  • httpOnly

    chaîne facultatif

    Existence de l'attribut de cookie HttpOnly.

  • maxAge

    number facultatif

    Valeur de l'attribut de cookie "Max-Age"

  • nom

    chaîne facultatif

    Nom d'un cookie.

  • chemin d'accès

    chaîne facultatif

    Valeur de l'attribut de cookie "Path".

  • sécurisé

    chaîne facultatif

    Existence de l'attribut de cookie sécurisé.

  • sessionCookie

    booléen facultatif

    Filtre les cookies de session. Les cookies de session n'ont pas de durée de vie spécifiée dans les attributs "max-age" ou "expires".

  • valeur

    chaîne facultatif

    Valeur d'un cookie, qui peut être placée entre guillemets doubles.

HeaderFilter

Filtre les en-têtes de requête selon différents critères. Plusieurs critères sont évalués comme une conjonction.

Propriétés

  • nameContains

    string | string[] facultatif

    Correspondance si le nom de l'en-tête contient toutes les chaînes spécifiées.

  • nameEquals

    chaîne facultatif

    Correspond si le nom de l'en-tête est égal à la chaîne spécifiée.

  • namePrefix

    chaîne facultatif

    Correspond si le nom de l'en-tête commence par la chaîne spécifiée.

  • nameSuffix

    chaîne facultatif

    Correspond si le nom de l'en-tête se termine par la chaîne spécifiée.

  • valueContains

    string | string[] facultatif

    La correspondance est établie si la valeur de l'en-tête contient toutes les chaînes spécifiées.

  • valueEquals

    chaîne facultatif

    Établit une correspondance si la valeur de l'en-tête est égale à la chaîne spécifiée.

  • valuePrefix

    chaîne facultatif

    Correspond si la valeur de l'en-tête commence par la chaîne spécifiée.

  • valueSuffix

    chaîne 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

    vide

    La fonction constructor se présente comme suit : 

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

  • hasTag

    chaîne facultatif

    Si cette option est définie, les règles portant le tag spécifié sont ignorées. Cette option n'est pas persistante. Elle n'affecte que les règles et leurs actions de la même étape de requête réseau. Notez que les règles sont exécutées par ordre décroissant de priorité. Cette action affecte les règles de priorité inférieure à la règle actuelle. Les règles ayant la même priorité peuvent être ignorées ou non.

  • lowerPriorityThan

    number facultatif

    Si cette option 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 de 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

    vide

    La fonction constructor se présente comme suit : 

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

  • de

    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, ...) plutôt que dans la syntaxe RE2 (\1, \2, ...) afin de se rapprocher 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éclarative 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 termes de calcul.

Propriétés

RemoveRequestHeader

Supprime l'en-tête de requête portant le nom spécifié. N'utilisez pas SetRequestHeader et RemoveRequestHeader avec le même nom d'en-tête sur la même requête. Le nom de chaque 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 la réponse. Notez qu'il est préférable d'utiliser l'API Cookies, car elle est moins coûteuse en termes de calcul.

Propriétés

RemoveResponseHeader

Supprime tous les en-têtes de réponse portant les noms et valeurs spécifiés.

Propriétés

  • constructor

    vide

    La fonction constructor se présente comme suit : 

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

  • nom

    chaîne

    Nom de l'en-tête de requête HTTP (non sensible à la casse).

  • valeur

    chaîne 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

  • nom

    chaîne facultatif

    Nom d'un cookie.

  • valeur

    chaîne facultatif

    Valeur d'un cookie, qui peut être placée entre guillemets doubles.

RequestMatcher

Établit une correspondance pour les événements réseau selon différents critères.

Propriétés

  • constructor

    vide

    La fonction constructor se présente comme suit : 

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

  • contentType

    string[] facultatif

    Correspond si le type de contenu MIME d'une réponse (à partir de l'en-tête HTTP Content-Type) est inclus dans la liste.

  • excludeContentType

    string[] facultatif

    Correspond si le type de contenu MIME d'une réponse (à partir de l'en-tête HTTP Content-Type) n'est pas inclus 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.

    Correspondance si les conditions de UrlFilter sont remplies pour l'URL "first party" de la requête. L'URL "first party" 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 "first party" pour les vérifications des cookies tiers.

  • requestHeaders

    HeaderFilter[] facultatif

    Correspond si certains en-têtes de requête correspondent à l'un des HeaderFilters.

  • resourceType

    ResourceType[] facultatif

    Correspond si le type de requête est inclus dans la liste. Les demandes qui ne correspondent à aucun type seront filtrées.

  • responseHeaders

    HeaderFilter[] facultatif

    Correspondance si certains en-têtes de réponse correspondent à l'un des HeaderFilters.

  • étapes

    Stage[] facultatif

    Contient une liste de chaînes décrivant les étapes. Les valeurs autorisées sont "onBeforeRequest", "onBeforeSendHeaders", "onHeadersReceived" et "onAuthRequired". Si cet attribut est présent, il limite les étapes applicables à celles listées. Notez que la condition complète ne s'applique qu'aux étapes compatibles avec tous les attributs.

  • thirdPartyForCookies

    booléen facultatif

    Obsolète

    Ignoré depuis la version 87.

    Si la valeur est définie sur "true", les requêtes qui sont soumises aux règles relatives aux cookies tiers sont mises en correspondance. Si la valeur est définie sur "false", elle correspond à toutes les autres requêtes.

  • url

    UrlFilter facultatif

    Correspond si les conditions de 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

    chaîne facultatif

    Valeur de l'attribut de cookie "Domain".

  • expire le

    chaîne facultatif

    Valeur de l'attribut de cookie "Expires".

  • httpOnly

    chaîne facultatif

    Existence de l'attribut de cookie HttpOnly.

  • maxAge

    number facultatif

    Valeur de l'attribut de cookie "Max-Age"

  • nom

    chaîne facultatif

    Nom d'un cookie.

  • chemin d'accès

    chaîne facultatif

    Valeur de l'attribut de cookie "Path".

  • sécurisé

    chaîne facultatif

    Existence de l'attribut de cookie sécurisé.

  • valeur

    chaîne facultatif

    Valeur d'un cookie, qui peut être placée entre guillemets doubles.

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 aucun en-tête ne portait le nom spécifié auparavant, un nouvel en-tête est créé. La comparaison des noms d'en-têtes n'est jamais sensible à la casse. Le nom de chaque en-tête de requête n'apparaît qu'une seule fois dans chaque requête.

Propriétés

  • constructor

    vide

    La fonction constructor se présente comme suit : 

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

  • nom

    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

Énumération

"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

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (details: object) => void

    • détails

      objet

      • documentId

        chaîne facultatif

        UUID du document qui a effectué la demande.

      • Cycle de vie dans lequel se trouve le document.

      • frameId

        nombre

        La valeur 0 indique que la requête a lieu dans le frame principal. Une valeur positive indique l'ID d'un sous-frame dans lequel la requête a lieu. Si le document d'un (sous-)frame est chargé (type est main_frame ou sub_frame), frameId indique l'ID de ce frame, et non celui du frame extérieur. Les ID de frame sont uniques dans un onglet.

      • Type de frame dans lequel la navigation a eu lieu.

      • message

        chaîne

        Message envoyé par le script appelant.

      • method

        chaîne

        Méthode HTTP standard.

      • parentDocumentId

        chaîne 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 du frame qui contient le frame ayant envoyé la requête. Définissez la valeur sur -1 si aucun frame parent n'existe.

      • requestId

        chaîne

        ID de la demande. Les ID de requête sont uniques dans une session de navigateur. Ils peuvent donc être utilisés pour relier différents événements d'une 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

        nombre

        ID de l'onglet dans lequel la requête est effectuée. Définissez 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.

      • Comment la ressource demandée sera utilisée.

      • url

        chaîne

onRequest

Fournit l'API Declarative Event, qui se compose 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