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 vous pouvez enregistrer des règles qui sont évaluées dans le navigateur plutôt que dans le moteur JavaScript, ce qui réduit les latences aller-retour et permet une plus grande efficacité.

Autorisations

declarativeWebRequest

Vous devez déclarer la requête "declarativeWebRequest" l'autorisation dans le fichier manifeste de l'extension d'utiliser cette et les autorisations d'hôte.

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

Disponibilité

<ph type="x-smartling-placeholder"></ph> Version bêta &amp;leq; MV2

Fichier manifeste

Notez que certains types d'actions non sensibles ne nécessitent pas d'autorisations 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 les requêtes réseau pour lequel vous souhaitez déclencher un message.

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, une telle extension peut configurer une règle pour:

  • Annulez une demande adressée à https://www.google.com ou https://anything.else.com.
  • Envoyer un message lors de la navigation 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 reprend les concepts de l'API Declarative. Vous pouvez vous inscrire à l'objet d'événement chrome.declarativeWebRequest.onRequest.

L'API Declarative Web Request accepte un seul type de critère de correspondance : RequestMatcher. La RequestMatcher établit une correspondance avec les requêtes réseau si et seulement si tous les critères listés sont remplis. Les éléments suivants : RequestMatcher correspond à une requête réseau lorsque l'utilisateur saisit https://www.example.com dans 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é seraient refusées en raison de l'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 Declarative Web Request suit le modèle de cycle de vie pour les requêtes Web du Web API Request Cela signifie que les conditions ne peuvent être testées qu'à des étapes spécifiques d'une requête Web De même, des actions ne peuvent être exécutées qu'à des étapes spécifiques. Les tableaux suivants répertorient les des étapes de requête compatibles avec des conditions et des actions.

Étapes de la 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 les 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 les 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 adressé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 reconnaître que l'action IgnoreRules n'est pas conservée lors de la requête. étapes. Les conditions de l'ensemble des règles sont évaluées à chaque étape d'une requête Web. Si un IgnoreRules est exécutée, elle ne s'applique qu'aux autres actions exécutées pour la même requête Web au même moment.

Types

AddRequestCookie

Ajoute un cookie à la demande 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

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 avoir le même nom, vous devez d'abord supprimer un en-tête de réponse, puis en ajouter un autre afin d'en remplacer un.

Propriétés

CancelRequest

Action d'événement déclarative qui annule une requête réseau.

Propriétés

EditRequestCookie

Modifie un ou plusieurs cookies de 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

    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 qui doivent être remplacés dans les cookies pour créer 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 de cookie dans les réponses HTTP.

Propriétés

  • ageLowerBound

    numéro facultatif

    Limite inférieure inclusive pour la durée de vie du cookie (spécifiée en secondes après l'heure actuelle). Uniquement les cookies dont la date et l'heure d'expiration est définie sur "maintenant + ageLowerBound" ou ultérieurement 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 de la valeur "max-age" ou "expires" attributs de cookie. Si les deux valeurs sont spécifiées, la valeur "max-age" sert à calculer la durée de vie du cookie.

  • ageUpperBound

    numéro facultatif

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

  • domaine

    chaîne facultatif

    Valeur de l'attribut de cookie de domaine.

  • expire le

    chaîne facultatif

    Valeur de l'attribut de cookie d'expiration de la date d'expiration.

  • httpOnly

    chaîne facultatif

    Existence de l'attribut de cookie HttpOnly

  • maxAge

    numéro 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 de chemin d'accès.

  • sécurisé

    chaîne facultatif

    Existence de l'attribut de cookie sécurisé

  • sessionCookie

    Booléen facultatif

    Filtre les cookies de session. La durée de vie des cookies de session n'est pas spécifiée dans la valeur "max-age". ou "expires" .

  • valeur

    chaîne facultatif

    Valeur d'un cookie, pouvant être mise entre guillemets doubles.

HeaderFilter

Filtre les en-têtes de requête 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

    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

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

  • valueEquals

    chaîne facultatif

    Correspond 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 règle est définie, les règles associées au tag spécifié sont ignorées. Cette action n'est pas conservée. Elle affecte uniquement les règles et leurs actions au cours de la même étape de requête réseau. Notez que les règles sont exécutées dans l'ordre décroissant de leur priorité. Cette action a une incidence sur 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 persistante. Elle n'affecte que les règles et leurs actions au cours d'une 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

    Schéma de correspondance qui peut 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

    Format 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 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 valeurs spécifiés.

Propriétés

  • constructor

    vide

    La fonction constructor se présente comme suit: 

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

  • nom

    chaîne

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

  • valeur

    chaîne facultatif

    Valeur d'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, pouvant être mise entre guillemets doubles.

RequestMatcher

Fait correspondre 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 média MIME d'une réponse (de l'en-tête HTTP Content-Type) est contenu dans la liste.

  • excludeContentType

    string[] facultatif

    Correspondance si le type de média MIME d'une réponse (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 filtres d'en-tête.

  • excludeResponseHeaders

    HeaderFilter[] facultatif

    Correspond si aucun des en-têtes de réponse ne correspond à l'un des filtres d'en-tête.

  • firstPartyForCookiesUrl

    UrlFilter facultatif

    <ph type="x-smartling-placeholder"></ph> Obsolète

    Ignoré depuis la version 82.

    Correspondance si les conditions d'UrlFilter sont remplies pour le type "propriétaire" URL de la requête. La "propriétaire" L'URL d'une requête, le cas échéant, peut être différente de l'URL cible de la requête et décrit ce qui est considéré comme "propriétaire" afin de contrôler les cookies par des tiers.

  • requestHeaders

    HeaderFilter[] facultatif

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

  • resourceType

    ResourceType[] facultatif

    Correspond si le type de requête d'une requête est contenu dans la liste. Les demandes qui ne peuvent correspondre à aucun de ces types seront filtrées.

  • responseHeaders

    HeaderFilter[] facultatif

    Correspond 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", "onAuthRequired". Si cet attribut est présent, les étapes applicables sont limitées à celles listées. Notez que l'intégralité de la condition n'est applicable qu'aux étapes compatibles avec tous les attributs.

  • thirdPartyForCookies

    Booléen facultatif

    <ph type="x-smartling-placeholder"></ph> Obsolète

    Ignoré depuis la version 87.

    Si la valeur est définie sur "true", établit une correspondance avec les requêtes soumises aux règles relatives aux cookies tiers. S'il est défini sur "false", établit une correspondance avec toutes les autres requêtes.

  • url

    UrlFilter facultatif

    Correspond si les conditions d'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 de domaine.

  • expire le

    chaîne facultatif

    Valeur de l'attribut de cookie d'expiration de la date d'expiration.

  • httpOnly

    chaîne facultatif

    Existence de l'attribut de cookie HttpOnly

  • maxAge

    numéro 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 de chemin d'accès.

  • sécurisé

    chaîne facultatif

    Existence de l'attribut de cookie sécurisé

  • valeur

    chaîne facultatif

    Valeur d'un cookie, pouvant être mise 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 portant le nom spécifié n'existait auparavant, un autre 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

    vide

    La fonction constructor se présente comme suit: 

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

  • nom

    chaîne

    Nom d'en-tête de requête HTTP.

  • valeur

    chaîne

    Valeur d'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

  • rappel

    fonction

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

    (details: object) => void

    • détails

      objet

      • documentId

        chaîne facultatif

        Un UUID du document à l'origine de la demande.

      • Cycle de vie du document.

      • frameId

        Nombre

        La valeur 0 indique que la requête se produit dans le frame principal. une valeur positive indique l'identifiant d'un sous-cadre dans lequel la demande se produit. 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 dans un onglet.

      • Type de cadre 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

        Un UUID du document parent propriétaire de ce cadre. Cette valeur n'est pas définie en l'absence de parent.

      • parentFrameId

        Nombre

        ID de la trame qui encapsule la trame ayant envoyé la requête. Définissez ce paramètre sur -1 si aucun cadre parent n'existe.

      • requestId

        chaîne

        Identifiant de la requête. Les identifiants de requête sont uniques au sein d'une session de navigateur. Par conséquent, ils peuvent être utilisés pour mettre en relation 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

        Nombre

        ID de l'onglet dans lequel la requête a lieu. Définissez ce paramètre sur -1 si la demande n'est pas associée à un onglet.

      • timeStamp

        Nombre

        Heure à laquelle ce signal s'est déclenché, en millisecondes depuis l'époque.

      • Façon dont la ressource demandée sera utilisé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