chrome.declarativeNetRequest

Description

L'API chrome.declarativeNetRequest permet de bloquer ou de modifier les requêtes réseau en spécifiant des règles déclaratives. Cela permet aux extensions de modifier les requêtes réseau sans les intercepter ni afficher leur contenu, et ainsi renforcer la confidentialité.

Autorisations

declarativeNetRequest
declarativeNetRequestWithHostAccess

Les autorisations "declarativeNetRequest" et "declarativeNetRequestWithHostAccess" offrent les mêmes capacités. La différence entre eux réside dans le moment où les autorisations sont demandées ou accordées.

"declarativeNetRequest"
Déclenche un avertissement d'autorisation au moment de l'installation, mais fournit un accès implicite aux règles allow, allowAllRequests et block. Utilisez-le dans la mesure du possible pour éviter de devoir demander un accès complet aux hôtes.
"declarativeNetRequestFeedback"
Active les fonctionnalités de débogage pour les extensions non empaquetées, en particulier getMatchedRules() et onRuleMatchedDebug.
"declarativeNetRequestWithHostAccess"
Aucun avertissement d'autorisation ne s'affiche au moment de l'installation, mais vous devez demander des autorisations d'hôte pour pouvoir effectuer une action sur un hôte. Cela est approprié lorsque vous souhaitez utiliser des règles de requête net déclaratives dans une extension qui dispose déjà d'autorisations d'hôte sans générer d'avertissements supplémentaires.

Garantie de disponibilité

Chrome 84 ou version ultérieure

Manifest

En plus des autorisations décrites précédemment, certains types d'ensembles de règles (les ensembles de règles statiques en particulier) nécessitent de déclarer la clé du fichier manifeste "declarative_net_request", qui doit être un dictionnaire comportant une seule clé appelée "rule_resources". Cette clé est un tableau contenant des dictionnaires de type Ruleset, comme indiqué ci-dessous. Notez que le nom "Ruleset" (Ensemble de règles) n'apparaît pas dans le fichier JSON du fichier manifeste, car il s'agit simplement d'un tableau. Les ensembles de règles statiques sont expliqués plus loin dans ce document.

{
  "name": "My extension",
  ...

  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    }, {
      "id": "ruleset_2",
      "enabled": false,
      "path": "rules_2.json"
    }]
  },
  "permissions": [
    "declarativeNetRequest",
    "declarativeNetRequestFeedback",
  ],
  "host_permissions": [
    "http://www.blogger.com/*",
    "http://*.google.com/*"
  ],
  ...
}

Concepts et utilisation

Pour utiliser cette API, spécifiez un ou plusieurs ensembles de règles. Un ensemble de règles contient un tableau de règles. Une seule règle permet d'effectuer l'une des opérations suivantes:

  • Bloquez une requête réseau.
  • Mettez à niveau le schéma (de HTTP à HTTPS).
  • Évitez le blocage d'une requête en annulant les règles bloquées correspondantes.
  • Redirigez une requête réseau.
  • Modifiez les en-têtes de requête ou de réponse.

Il existe trois types d'ensembles de règles, gérés de manière légèrement différente.

Dynamique
Les extensions restent disponibles entre les sessions de navigateur et les mises à niveau des extensions. Elles sont gérées à l'aide de JavaScript lorsqu'une extension est utilisée.
Session
Effacement des données lorsque le navigateur s'arrête et qu'une nouvelle version de l'extension est installée. Les règles de session sont gérées à l'aide de JavaScript lorsqu'une extension est utilisée.
Statique
Empaquetées, installées et mises à jour lors de l'installation ou de la mise à niveau d'une extension Les règles statiques sont stockées dans des fichiers de règles au format JSON et listées dans le fichier manifeste.

Les sections suivantes expliquent en détail les types de jeux de règles.

Ensembles de règles dynamiques et de portée session

Les ensembles de règles dynamiques et de session sont gérés à l'aide de JavaScript lorsqu'une extension est utilisée.

  • Les règles dynamiques sont conservées entre les sessions de navigateur et les mises à niveau des extensions.
  • Les règles de session sont effacées lorsque le navigateur s'arrête et lorsqu'une nouvelle version de l'extension est installée.

Il n'existe qu'un seul type de jeu de règles. Une extension peut ajouter ou supprimer des règles de manière dynamique en appelant updateDynamicRules() et updateSessionRules(), à condition que le nombre maximal de règles ne soit pas dépassé. Pour en savoir plus sur les limites des règles, consultez la section Limites de règles. Vous trouverez un exemple dans la section Exemples de code.

Ensembles de règles statiques

Contrairement aux règles dynamiques et aux règles de session, les règles statiques sont empaquetées, installées et mises à jour lors de l'installation ou de la mise à niveau d'une extension. Ils sont stockés dans des fichiers de règles au format JSON, qui sont indiqués à l'extension à l'aide des clés "declarative_net_request" et "rule_resources" comme décrit ci-dessus, ainsi que d'un ou plusieurs dictionnaires Ruleset. Un dictionnaire Ruleset contient un chemin d'accès au fichier de règles et un ID pour l'ensemble de règles qu'il contient. Il indique également si l'ensemble de règles est activé ou désactivé. Les deux derniers sont importants lorsque vous activez ou désactivez un ensemble de règles de manière programmatique.

{
  ...
  "declarative_net_request" : {
    "rule_resources" : [{
      "id": "ruleset_1",
      "enabled": true,
      "path": "rules_1.json"
    },
    ...
    ]
  }
  ...
}

Pour tester les fichiers de règles, chargez votre extension non empaquetée. Les erreurs et les avertissements concernant les règles statiques non valides ne s'affichent que pour les extensions non empaquetées. Les règles statiques non valides dans les extensions regroupées sont ignorées.

Examen accéléré

Les modifications apportées aux ensembles de règles statiques peuvent faire l'objet d'un examen accéléré. Consultez Examen accéléré pour les modifications éligibles.

Activer et désactiver des règles et des ensembles de règles statiques

Vous pouvez activer ou désactiver les règles statiques individuelles et les ensembles de règles statiques complets au moment de l'exécution.

L'ensemble des règles et ensembles de règles statiques activés est conservé d'une session de navigateur à l'autre. Elles ne sont pas conservées lors des mises à jour des extensions, ce qui signifie que seules les règles que vous avez choisi de conserver dans vos fichiers de règles sont disponibles après une mise à jour.

Pour des raisons de performances, le nombre de règles et d'ensembles de règles pouvant être activés simultanément est également limité. Appelez getAvailableStaticRuleCount() pour vérifier le nombre de règles supplémentaires pouvant être activées. Pour en savoir plus sur les limites des règles, consultez la section Limites de règles.

Pour activer ou désactiver les règles statiques, appelez updateStaticRules(). Cette méthode utilise un objet UpdateStaticRulesOptions, qui contient des tableaux d'ID de règles à activer ou à désactiver. Les ID sont définis à l'aide de la clé "id" du dictionnaire Ruleset.

Pour activer ou désactiver les rulesets statiques, appelez updateEnabledRulesets(). Cette méthode utilise un objet UpdateRulesetOptions, qui contient des tableaux d'ID d'ensembles de règles à activer ou à désactiver. Les ID sont définis à l'aide de la clé "id" du dictionnaire Ruleset.

Créer des règles

Quel que soit leur type, une règle commence par quatre champs, comme indiqué ci-dessous. Alors que les clés "id" et "priority" acceptent un nombre, les clés "action" et "condition" peuvent fournir plusieurs conditions de blocage et de redirection. La règle suivante bloque toutes les requêtes de script provenant de "foo.com" vers n'importe quelle URL ayant "abc" comme sous-chaîne.

{
  "id" : 1,
  "priority": 1,
  "action" : { "type" : "block" },
  "condition" : {
    "urlFilter" : "abc",
    "initiatorDomains" : ["foo.com"],
    "resourceTypes" : ["script"]
  }
}

urlFilter – Caractères correspondants

La clé "condition" d'une règle autorise une clé "urlFilter" pour agir sur les URL d'un domaine spécifié. La création de modèles s'effectue à l'aide de jetons de correspondance de structure. Voici quelques exemples :

urlFilter Correspond à Ne correspond pas
"abc" https://abcd.com
https://example.com/abcd		 https://ab.com
"abc*d" https://abcd.com
https://example.com/abcxyzd		 https://abc.com
"||a.example.com" https://a.example.com/
https://b.a.example.com/xyz		 https://example.com/
"|https*" https://example.com http://example.com/
http://https.com
"example*^123|" https://example.com/123
http://abc.com/example?123		 https://example.com/1234
https://abc.com/example0123

Hiérarchisation des règles

Les règles sont déclenchées par les requêtes envoyées à partir de pages Web. Si plusieurs règles correspondent à une demande particulière, elles doivent être prioritaires. Cette section explique comment ils sont hiérarchisés. L'établissement des priorités s'effectue en deux étapes.

  1. La priorité est déterminée pour les règles d'une extension.
  2. Si plusieurs extensions peuvent appliquer une règle à une requête, la priorité est déterminée pour toutes les extensions qui correspondent à une requête particulière.

Envisagez la mise en correspondance de cette façon: quelle que soit la règle définie par une extension particulière, elle sera prioritaire par rapport aux règles des autres extensions.

Hiérarchisation des règles dans une extension

Dans une seule extension, la hiérarchisation est effectuée selon le processus suivant:

  1. La règle ayant la priorité définie par le développeur la plus élevée (en d'autres termes, le champ "priority") est renvoyée.

  2. Si plusieurs règles ont la priorité la plus élevée définie par le développeur, elles sont classées par ordre de priorité à l'aide du champ "action", dans l'ordre suivant:

    1. allow
    2. allowAllRequests
    3. block
    4. upgradeScheme
    5. redirect

  3. Si le type d'action n'est pas block ou redirect, toutes les règles modifyHeaders correspondantes sont évaluées. Sachez que si certaines règles ont une priorité définie par le développeur inférieure à celle spécifiée pour allow et allowAllRequests, elles sont ignorées.

  4. Si plusieurs règles modifient le même en-tête, la modification est déterminée par le champ "priority" défini par le développeur et par les opérations spécifiées.

    • Si une règle est ajoutée à un en-tête, les règles de priorité inférieure ne peuvent s'ajouter qu'à cet en-tête. Les opérations de définition et de suppression ne sont pas autorisées.
    • Si une règle définit un en-tête, les règles de priorité inférieure ne peuvent s'ajouter qu'à cet en-tête. Aucune autre modification n'est autorisée.
    • Si une règle supprime un en-tête, les règles de priorité inférieure ne peuvent plus modifier l'en-tête.

Hiérarchisation des règles entre les extensions

Si une seule extension comporte une règle qui correspond à une requête, cette règle est appliquée. Toutefois, si plusieurs extensions correspondent à une requête, le processus suivant est utilisé:

  1. Les règles sont classées par ordre de priorité à l'aide du champ "action", dans l'ordre suivant:

    1. block
    2. redirect ou upgradeScheme
    3. allow ou allowAllRequests

  2. Si plusieurs règles correspondent, la dernière extension installée est prioritaire.

Règles de sécurité

Les règles sûres sont définies comme des règles ayant une action block, allow, allowAllRequests ou upgradeScheme. Ces règles sont soumises à un quota de règles dynamiques augmenté.

Limites de règles

Le chargement et l'évaluation des règles dans le navigateur entraînent une surcharge des performances. Par conséquent, certaines limites s'appliquent lors de l'utilisation de l'API. Les limites dépendent du type de règle que vous utilisez.

Règles statiques

Les règles statiques sont celles spécifiées dans les fichiers de règles déclarés dans le fichier manifeste. Une extension peut spécifier jusqu'à 100 rulesets statiques dans la clé du fichier manifeste "rule_resources", mais vous ne pouvez activer que 50 de ces ensembles à la fois. Cette dernière méthode est appelée MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Au total, ces ensembles de règles sont garantis pour au moins 30 000 règles. C'est ce qu'on appelle le GUARANTEED_MINIMUM_STATIC_RULES.

Le nombre de règles disponibles par la suite dépend du nombre de règles activées par toutes les extensions installées dans le navigateur de l'utilisateur. Vous pouvez trouver ce numéro au moment de l'exécution en appelant getAvailableStaticRuleCount(). Vous trouverez un exemple dans la section Exemples de code.

Règles de session

Une extension peut comporter jusqu'à 5 000 règles de session. Il est exposé en tant que MAX_NUMBER_OF_SESSION_RULES.

Avant Chrome 120, le nombre de règles combinées dynamiques et de session était limité à 5 000.

Les règles dynamiques

Une extension peut comporter au moins 5 000 règles dynamiques. Il est exposé en tant que MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

À partir de Chrome 121, la limite supérieure de 30 000 règles disponibles pour les règles dynamiques sécurisées s'élève à MAX_NUMBER_OF_DYNAMIC_RULES. Les règles non sécurisées ajoutées dans la limite de 5 000 seront également comptabilisées dans cette limite.

Avant Chrome 120, le nombre de règles combinées dynamiques et de sessions était limité à 5 000.

Règles utilisant des expressions régulières

Tous les types de règles peuvent utiliser des expressions régulières. Toutefois, le nombre total de règles d'expression régulière de chaque type ne peut pas dépasser 1 000. Il s'agit de la règle MAX_NUMBER_OF_REGEX_RULES.

De plus, la taille de chaque règle doit être inférieure à 2 Ko une fois compilée. Cela correspond à peu près à la complexité de la règle. Si vous essayez de charger une règle qui dépasse cette limite, un avertissement semblable au suivant s'affiche, et la règle est ignorée.

rules_1.json: Rule with id 1 specified a more complex regex than allowed
as part of the "regexFilter" key.

Interactions avec les service workers

Une instruction déclarativeNetRequest ne s'applique qu'aux requêtes qui atteignent la pile réseau. Cela inclut les réponses du cache HTTP, mais pas les réponses qui passent par le gestionnaire onfetch d'un service worker. déclarativeNetRequest n'affecte pas les réponses générées par le service worker ou récupérées à partir de CacheStorage, mais affecte les appels à fetch() effectués dans un service worker.

Ressources accessibles sur le Web

Une règle déclarativeNetRequest ne peut pas rediriger d'une requête de ressource publique vers une ressource inaccessible sur le Web. Cela déclenche une erreur. Cela est vrai même si la ressource accessible sur le Web spécifiée appartient à l'extension de redirection. Pour déclarer des ressources pour declarativeNetRequest, utilisez le tableau "web_accessible_resources" du fichier manifeste.

Exemples

Exemples de code

Mettre à jour les règles dynamiques

L'exemple suivant montre comment appeler updateDynamicRules(). La procédure pour updateSessionRules() est la même.

// Get arrays containing new and old rules
const newRules = await getNewRules();
const oldRules = await chrome.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

// Use the arrays to update the dynamic rules
await chrome.declarativeNetRequest.updateDynamicRules({
  removeRuleIds: oldRuleIds,
  addRules: newRules
});

Mettre à jour des ensembles de règles statiques

L'exemple suivant montre comment activer et désactiver des ensembles de règles tout en tenant compte du nombre d'ensembles de règles statiques disponibles et du nombre maximal d'ensembles de règles statiques activés. Vous devez effectuer cette opération lorsque le nombre de règles statiques dont vous avez besoin dépasse le nombre autorisé. Pour que cela fonctionne, certains de vos ensembles de règles doivent être installés sans en avoir désactivé d'autres (en définissant "Enabled" sur false dans le fichier manifeste).

async function updateStaticRules(enableRulesetIds, disableCandidateIds) {
  // Create the options structure for the call to updateEnabledRulesets()
  let options = { enableRulesetIds: enableRulesetIds }
  // Get the number of enabled static rules
  const enabledStaticCount = await chrome.declarativeNetRequest.getEnabledRulesets();
  // Compare rule counts to determine if anything needs to be disabled so that
  // new rules can be enabled
  const proposedCount = enableRulesetIds.length;
  if (enabledStaticCount + proposedCount > chrome.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await chrome.declarativeNetRequest.updateEnabledRulesets(options);
}

Exemples de règles

Les exemples suivants montrent comment Chrome hiérarchise les règles dans une extension. Lorsque vous les examinez, vous pouvez ouvrir les règles de hiérarchisation dans une fenêtre distincte.

La touche "Priorité"

Ces exemples nécessitent une autorisation d'hôte pour *://*.example.com/*.

Pour déterminer la priorité d'une URL spécifique, examinez les clés "priority" (définies par le développeur), "action" et "urlFilter". Ces exemples font référence à l'exemple de fichier de règles présenté ci-dessous.

Accès à https://google.com
Deux règles s'appliquent à cette URL: celles associées aux ID 1 et 4. La règle portant l'ID 1 s'applique, car "block" actions ont une priorité plus élevée que "redirect" actions. Les autres règles ne s'appliquent pas, car elles concernent des URL plus longues.
Accès à https://google.com/1234
En raison de la longueur de l'URL, la règle associée à l'ID 2 correspond désormais à celle associée aux ID 1 et 4. La règle portant l'ID 2 s'applique, car "allow" a une priorité supérieure à "block" et "redirect".
Accès à https://google.com/12345
Les quatre règles correspondent à cette URL. La règle portant l'ID 3 s'applique, car sa priorité définie par le développeur est la plus élevée du groupe.
[
  {
    "id": 1,
    "priority": 1,
    "action": { "type": "block" },
    "condition": {"urlFilter": "google.com", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 2,
    "priority": 1,
    "action": { "type": "allow" },
    "condition": { "urlFilter": "google.com/123", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 3,
    "priority": 2,
    "action": { "type": "block" },
    "condition": { "urlFilter": "google.com/12345", "resourceTypes": ["main_frame"] }
  },
  {
    "id": 4,
    "priority": 1,
    "action": { "type": "redirect", "redirect": { "url": "https://example.com" } },
    "condition": { "urlFilter": "google.com", "resourceTypes": ["main_frame"] }
  },
]

Redirections

L'exemple ci-dessous nécessite une autorisation d'hôte pour *://*.example.com/*.

L'exemple suivant montre comment rediriger une requête d'example.com vers une page de l'extension elle-même. Le chemin d'accès de l'extension /a.jpg pointe vers chrome-extension://EXTENSION_ID/a.jpg, où EXTENSION_ID est l'ID de votre extension. Pour que cela fonctionne, le fichier manifeste doit déclarer /a.jpg comme ressource accessible sur le Web.

{
  "id": 1,
  "priority": 1,
  "action": { "type": "redirect", "redirect": { "extensionPath": "/a.jpg" } },
  "condition": {
    "urlFilter": "https://www.example.com",
    "resourceTypes": ["main_frame"]
  }
}

La commande suivante utilise la clé "transform" pour rediriger vers un sous-domaine de example.com. Elle utilise une ancre de nom de domaine ("||") pour intercepter les requêtes avec n'importe quel schéma provenant d'example.com. La clé "scheme" dans "transform" spécifie que les redirections vers le sous-domaine utiliseront toujours "https".

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "transform": { "scheme": "https", "host": "new.example.com" }
    }
  },
  "condition": {
    "urlFilter": "||example.com",
    "resourceTypes": ["main_frame"]
  }
}

L'exemple suivant utilise des expressions régulières pour rediriger de https://www.abc.xyz.com/path vers https://abc.xyz.com/path. Dans la clé "regexFilter", notez comment les points sont échappés et que le groupe de capture sélectionne "abc" ou "def". La clé "regexSubstitution" spécifie la première correspondance renvoyée par l'expression régulière à l'aide de "\1". Dans ce cas, "abc" est capturé à partir de l'URL de redirection et placé dans la substitution.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "redirect",
    "redirect": {
      "regexSubstitution": "https://\\1.xyz.com/"
    }
  },
  "condition": {
    "regexFilter": "^https://www\\.(abc|def)\\.xyz\\.com/",
    "resourceTypes": [
      "main_frame"
    ]
  }
}

En-têtes

L'exemple suivant supprime tous les cookies d'un frame principal et de tous les sous-frames.

{
  "id": 1,
  "priority": 1,
  "action": {
    "type": "modifyHeaders",
    "requestHeaders": [{ "header": "cookie", "operation": "remove" }]
  },
  "condition": { "resourceTypes": ["main_frame", "sub_frame"] }
}

Types

DomainType

Indique si la requête est propriétaire ou tierce de la trame d'où elle provient. Une requête est considérée comme propriétaire si elle possède le même domaine (eTLD+1) que le frame d'où provient la requête.

Enum

"firstParty"
La requête réseau est liée à la trame d'où elle provient.

"thirdParty"
La requête réseau est un tiers par rapport à la trame d'où elle provient.

ExtensionActionOptions

Chrome 88 ou version ultérieure

Propriétés

  • displayActionCountAsBadgeText

    Booléen facultatif

    Permet d'afficher ou non automatiquement le nombre d'actions sur une page en tant que texte du badge de l'extension. Cette préférence est conservée d'une session à l'autre.

  • tabUpdate

    TabActionCountUpdate facultatif

    Chrome 89 ou version ultérieure

    Détails sur la façon dont le nombre d'actions de l'onglet doit être ajusté.

GetDisabledRuleIdsOptions

Chrome 111 ou version ultérieure

Propriétés

  • rulesetId

    chaîne

    ID correspondant à un élément Ruleset statique.

GetRulesFilter

Chrome 111 ou version ultérieure

Propriétés

  • ruleIds

    number[] facultatif

    Si une valeur est spécifiée, seules les règles avec des ID correspondants sont incluses.

HeaderOperation

Chrome 86 ou version ultérieure

Ceci décrit les opérations possibles pour une règle "modifyHeaders".

Enum

"append"
Ajoute une nouvelle entrée pour l'en-tête spécifié. Cette opération n'est pas possible pour les en-têtes de requêtes.

"set"
Définit une nouvelle valeur pour l'en-tête spécifié et supprime tous les en-têtes existants portant le même nom.

"remove"
Supprime toutes les entrées pour l'en-tête spécifié.

IsRegexSupportedResult

Chrome 87 ou version ultérieure

Propriétés

  • isSupported

    boolean

  • reason

    UnsupportedRegexReason facultatif

    Indique la raison pour laquelle l'expression régulière n'est pas compatible. Fourni uniquement si la valeur de isSupported est "false".

MatchedRule

Propriétés

  • ruleId

    Nombre

    Identifiant d'une règle de correspondance.

  • rulesetId

    chaîne

    ID de l'élément Ruleset auquel cette règle appartient. Pour une règle provenant de l'ensemble de règles dynamiques, cette valeur sera égale à DYNAMIC_RULESET_ID.

MatchedRuleInfo

Propriétés

  • règle

    MatchedRule

  • tabId

    Nombre

    ID de tabulation de l'onglet d'où provient la requête, si l'onglet est toujours actif. Sinon, -1.

  • timeStamp

    Nombre

    Heure à laquelle la règle a été mise en correspondance. Les codes temporels correspondent à la convention JavaScript pour les heures, c'est-à-dire le nombre de millisecondes écoulées depuis l'epoch.

MatchedRuleInfoDebug

Propriétés

  • request

    RequestDetails

    Détails concernant la requête pour laquelle la règle a été mise en correspondance.

  • règle

    MatchedRule

MatchedRulesFilter

Propriétés

  • minTimeStamp

    numéro facultatif

    Si spécifié, établit une correspondance uniquement avec les règles postérieures à l'horodatage donné.

  • tabId

    numéro facultatif

    Si spécifié, correspond uniquement aux règles de l'onglet donné. Correspond aux règles qui ne sont associées à aucun onglet actif si la valeur est définie sur -1.

ModifyHeaderInfo

Chrome 86 ou version ultérieure

Propriétés

  • en-tête

    chaîne

    Nom de l'en-tête à modifier.

  • opération

    HeaderOperation

    Opération à effectuer sur un en-tête.

  • valeur

    chaîne facultatif

    Nouvelle valeur de l'en-tête. Doit être spécifié pour les opérations append et set.

QueryKeyValue

Propriétés

  • clé

    chaîne

  • replaceOnly

    Booléen facultatif

    Chrome 94 ou version ultérieure

    Si la valeur est "true", la clé de requête n'est remplacée que si elle est déjà présente. Sinon, la clé est également ajoutée si elle est manquante. Valeur par défaut : "false".

  • valeur

    chaîne

QueryTransform

Propriétés

  • addOrReplaceParams

    QueryKeyValue[] facultatif

    Liste des paires clé/valeur de requête à ajouter ou à remplacer.

  • removeParams

    string[] facultatif

    Liste des clés de requête à supprimer.

Redirect

Propriétés

  • extensionPath

    chaîne facultatif

    Chemin d'accès relatif au répertoire de l'extension. Doit commencer par "/".

  • regexSubstitution

    chaîne facultatif

    Modèle de substitution pour les règles qui spécifient un regexFilter. La première correspondance de regexFilter dans l'URL sera remplacée par ce format. Dans regexSubstitution, les chiffres échappés par une barre oblique inverse (\1 à \9) peuvent être utilisés pour insérer les groupes de capture correspondants. \0 fait référence à l'intégralité du texte correspondant.

  • transform

    URLTransform facultatif

    Transformations d'URL à effectuer.

  • url

    chaîne facultatif

    URL de redirection. Les redirections vers des URL JavaScript ne sont pas autorisées.

RegexOptions

Chrome 87 ou version ultérieure

Propriétés

  • isCaseSensitive

    Booléen facultatif

    Indique si la valeur regex spécifiée est sensible à la casse. La valeur par défaut est "true".

  • regex

    chaîne

    Expresson habituelle à vérifier.

  • requireCapturing

    Booléen facultatif

    Indique si le regex spécifié doit être capturé ou non. La capture n'est requise que pour les règles de redirection qui spécifient une action regexSubstition. La valeur par défaut est "false".

RequestDetails

Propriétés

  • documentId

    chaîne facultatif

    Chrome 106 ou version ultérieure

    Identifiant unique du document du frame, si cette demande concerne un frame.

  • documentLifecycle

    DocumentLifecycle facultatif

    Chrome 106 ou version ultérieure

    Cycle de vie du document du frame, si cette requête concerne un frame.

  • frameId

    Nombre

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

  • frameType

    FrameType facultatif

    Chrome 106 ou version ultérieure

    Type de trame, si cette requête concerne une trame.

  • demandeur

    chaîne facultatif

    Origine où la requête a été lancée. Cela ne change pas par le biais des redirections. Si l'origine est opaque, la chaîne "null" est utilisée.

  • method

    chaîne

    Méthode HTTP standard.

  • parentDocumentId

    chaîne facultatif

    Chrome 106 ou version ultérieure

    Identifiant unique du document parent du frame, si cette demande concerne un frame et qu'il a un 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.

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

  • Type de ressource de la requête.

  • url

    chaîne

    URL de la requête.

RequestMethod

Chrome 91 ou version ultérieure

Ceci décrit la méthode de requête HTTP d'une requête réseau.

Enum

"get"

"head"

"options"

"patch"

"post"

"put"

ResourceType

Ceci décrit le type de ressource de la requête réseau.

Enum

"main_frame"

"sub_frame"

"script"

"image"

"font"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webbundle"

Rule

Propriétés

  • action

    RuleAction

    L'action à effectuer si cette règle correspond.

  • Condition de déclenchement de la règle.

  • id

    Nombre

    Identifiant permettant d'identifier une règle de manière unique. Obligatoire et doit être supérieur ou égal à 1.

  • campagne

    numéro facultatif

    Priorité des règles. La valeur par défaut est 1. Si spécifié, doit être >= 1.

RuleAction

Propriétés

  • redirection

    Redirection facultatif

    Décrit comment la redirection doit être effectuée. Uniquement valide pour les règles de redirection.

  • requestHeaders

    ModifyHeaderInfo[] facultatif

    Chrome 86 ou version ultérieure

    En-têtes de requête à modifier. Valide uniquement si RuleActionType est défini sur "modifyHeaders".

  • responseHeaders

    ModifyHeaderInfo[] facultatif

    Chrome 86 ou version ultérieure

    En-têtes de réponse à modifier pour la requête. Valide uniquement si RuleActionType est défini sur "modifyHeaders".

  • Type d'action à effectuer.

RuleActionType

Décrit le type d'action à effectuer si une règle RuleCondition donnée correspond.

Enum

"block"
Bloque la requête réseau.

"redirect"
Redirige la requête réseau.

"allow"
Autorisez la requête réseau. La requête ne sera pas interceptée si une règle d'autorisation lui correspond.

"upgradeScheme"
Mettez à jour le schéma de l'URL de la requête réseau en HTTPS si la requête est HTTP ou FTP.

"modifyHeaders"
Modifiez les en-têtes de requête/réponse de la requête réseau.

"allowAllRequests"
Autoriser toutes les requêtes dans une hiérarchie de frames, y compris la requête de frame elle-même.

RuleCondition

Propriétés

  • domainType

    DomainType facultatif

    Indique si la requête réseau est d'origine propriétaire ou tierce dans le domaine d'où elle provient. S'il est omis, toutes les requêtes sont acceptées.

  • domaines

    string[] facultatif

    Obsolète depuis Chrome 101

    Utilisez initiatorDomains à la place

    La règle ne mettra en correspondance que les requêtes réseau provenant de la liste domains.

  • excludedDomains

    string[] facultatif

    Obsolète depuis Chrome 101

    Utilisez excludedInitiatorDomains à la place

    La règle ne correspondra pas aux requêtes réseau provenant de la liste des excludedDomains.

  • excludedInitiatorDomains

    string[] facultatif

    Chrome 101 ou version ultérieure

    La règle ne correspondra pas aux requêtes réseau provenant de la liste des excludedInitiatorDomains. Si la liste est vide ou omise, aucun domaine n'est exclu. Cette valeur est prioritaire sur initiatorDomains.

    Remarques :

    • Les sous-domaines tels que "a.example.com" sont également autorisés.
    • Les entrées ne doivent comporter que des caractères ASCII.
    • Utilisez l'encodage Punycode pour les domaines internationalisés.
    • Cette valeur correspond à l'initiateur de la requête et non à l'URL de la requête.
    • Les sous-domaines des domaines répertoriés sont également exclus.
  • excludedRequestDomains

    string[] facultatif

    Chrome 101 ou version ultérieure

    La règle ne correspond pas aux requêtes réseau lorsque les domaines correspondent à l'un des domaines figurant dans la liste excludedRequestDomains. Si la liste est vide ou omise, aucun domaine n'est exclu. Cette valeur est prioritaire sur requestDomains.

    Remarques :

    • Les sous-domaines tels que "a.example.com" sont également autorisés.
    • Les entrées ne doivent comporter que des caractères ASCII.
    • Utilisez l'encodage Punycode pour les domaines internationalisés.
    • Les sous-domaines des domaines répertoriés sont également exclus.
  • excludedRequestMethods

    RequestMethod[] facultatif

    Chrome 91 ou version ultérieure

    Liste des méthodes de requête auxquelles la règle ne correspond pas. Vous ne devez spécifier qu'un seul des champs requestMethods et excludedRequestMethods. Si aucune de ces deux méthodes n'est spécifiée, toutes les méthodes de requête sont mises en correspondance.

  • excludedResourceTypes

    ResourceType[] facultatif

    Liste des types de ressources auxquels la règle ne correspond pas. Vous ne devez spécifier qu'un seul des champs resourceTypes et excludedResourceTypes. Si aucun de ces éléments n'est spécifié, tous les types de ressources sont bloqués, à l'exception de "main_frame".

  • excludedTabIds

    number[] facultatif

    Chrome 92 ou version ultérieure

    Liste des tabs.Tab.id auxquels la règle ne doit pas correspondre. L'ID tabs.TAB_ID_NONE exclut les requêtes qui ne proviennent pas d'un onglet. Compatible uniquement avec les règles de portée session.

  • initiatorDomains

    string[] facultatif

    Chrome 101 ou version ultérieure

    La règle ne mettra en correspondance que les requêtes réseau provenant de la liste initiatorDomains. Si la liste est omise, la règle est appliquée aux requêtes provenant de tous les domaines. Une liste vide n'est pas autorisée.

    Remarques :

    • Les sous-domaines tels que "a.example.com" sont également autorisés.
    • Les entrées ne doivent comporter que des caractères ASCII.
    • Utilisez l'encodage Punycode pour les domaines internationalisés.
    • Cette valeur correspond à l'initiateur de la requête et non à l'URL de la requête.
    • Les sous-domaines des domaines répertoriés sont également mis en correspondance.
  • isUrlFilterCaseSensitive

    Booléen facultatif

    Indique si urlFilter ou regexFilter (selon la valeur spécifiée) est sensible à la casse. La valeur par défaut est "false".

  • regexFilter

    chaîne facultatif

    Expression régulière à mettre en correspondance avec l'URL de la requête réseau. Cela suit la syntaxe RE2.

    Remarque: Vous ne pouvez spécifier qu'une seule propriété urlFilter ou regexFilter.

    Remarque: regexFilter ne doit être composé que de caractères ASCII. Cette valeur est mise en correspondance avec une URL dans laquelle l'hôte est encodé au format Punycode (dans le cas de domaines internationalisés) et tout autre caractère non ASCII est encodé au format utf-8.

  • requestDomains

    string[] facultatif

    Chrome 101 ou version ultérieure

    La règle ne met en correspondance les requêtes réseau que lorsque le domaine correspond à l'une des requêtes de la liste requestDomains. Si la liste est omise, la règle est appliquée aux requêtes provenant de tous les domaines. Une liste vide n'est pas autorisée.

    Remarques :

    • Les sous-domaines tels que "a.example.com" sont également autorisés.
    • Les entrées ne doivent comporter que des caractères ASCII.
    • Utilisez l'encodage Punycode pour les domaines internationalisés.
    • Les sous-domaines des domaines répertoriés sont également mis en correspondance.
  • requestMethods

    RequestMethod[] facultatif

    Chrome 91 ou version ultérieure

    Liste des méthodes de requête HTTP auxquelles la règle peut correspondre. Une liste vide n'est pas autorisée.

    Remarque: Si vous spécifiez une condition de règle requestMethods, les requêtes qui ne sont pas HTTP(S) seront également exclues, contrairement à excludedRequestMethods.

  • resourceTypes

    ResourceType[] facultatif

    Liste des types de ressources auxquels la règle peut correspondre. Une liste vide n'est pas autorisée.

    Remarque: Cela doit être spécifié pour les règles allowAllRequests et ne peut inclure que les types de ressources sub_frame et main_frame.

  • tabIds

    number[] facultatif

    Chrome 92 ou version ultérieure

    Liste des tabs.Tab.id auxquels la règle doit correspondre. L'ID tabs.TAB_ID_NONE correspond aux requêtes qui ne proviennent pas d'un onglet. Une liste vide n'est pas autorisée. Compatible uniquement avec les règles de portée session.

  • urlFilter

    chaîne facultatif

    Format mis en correspondance avec l'URL de requête réseau. Constructions compatibles:

    '*' : Caractère générique: correspond à n'importe quel nombre de caractères.

    '|' : ancrage gauche/droite: si utilisé à l'une ou l'autre extrémité du format, spécifie le début/la fin de l'URL, respectivement.

    '|| : ancre du nom de domaine: si elle est utilisée au début du format, indique le début d'un (sous-)domaine de l'URL.

    ^ : caractère de séparation: renvoie tout élément sauf une lettre, un chiffre ou l'un des éléments suivants: _, -, . ou %. Elle correspond également à la fin de l'URL.

    Par conséquent, urlFilter se compose des parties suivantes: (ancre gauche/ancre de nom de domaine facultative) + motif + (ancre droite facultative).

    Si cette valeur est omise, toutes les URL sont prises en compte. Une chaîne vide n'est pas autorisée.

    Un format commençant par ||* n'est pas autorisé. Utilisez plutôt *.

    Remarque: Vous ne pouvez spécifier qu'une seule propriété urlFilter ou regexFilter.

    Remarque: urlFilter ne doit être composé que de caractères ASCII. Cette valeur est mise en correspondance avec une URL dans laquelle l'hôte est encodé au format Punycode (dans le cas de domaines internationalisés) et tout autre caractère non ASCII est encodé au format utf-8. Par exemple, lorsque l'URL de la requête est http://abc.trap?q= \n, urlFilter est mis en correspondance avec l'URL http://abc.xn--p1ai/?q=%D1%84.

Ruleset

Propriétés

  • activé

    boolean

    Indique si l'ensemble de règles est activé par défaut.

  • id

    chaîne

    Chaîne non vide identifiant de manière unique l'ensemble de règles. Les ID commençant par "_" sont réservés à un usage interne.

  • chemin d'accès

    chaîne

    Chemin d'accès à l'ensemble de règles JSON relatif au répertoire de l'extension.

RulesMatchedDetails

Propriétés

  • rulesMatchedInfo

    MatchedRuleInfo.

    Règles correspondant au filtre donné.

TabActionCountUpdate

Chrome 89 ou version ultérieure

Propriétés

  • increment

    Nombre

    Montant d'incrémentation du nombre d'actions de l'onglet. Les valeurs négatives diminuent le nombre.

  • tabId

    Nombre

    Onglet pour lequel mettre à jour le nombre d'actions.

TestMatchOutcomeResult

Chrome 103 ou version ultérieure

Propriétés

  • matchedRules

    MatchedRule[]

    Les règles (le cas échéant) correspondant à la requête fictive.

TestMatchRequestDetails

Chrome 103 ou version ultérieure

Propriétés

  • demandeur

    chaîne facultatif

    L'URL de l'initiateur de la requête fictive (le cas échéant).

  • method

    RequestMethod facultatif

    Méthode HTTP standard de la requête fictive. La valeur par défaut est "get" pour les requêtes HTTP. Elle est ignorée pour les requêtes autres que HTTP.

  • tabId

    numéro facultatif

    ID de l'onglet dans lequel la requête fictive a lieu. Il ne doit pas nécessairement correspondre à un ID d'onglet réel. La valeur par défaut est -1, ce qui signifie que la requête n'est pas associée à un onglet.

  • Type de ressource de la requête hypothétique.

  • url

    chaîne

    URL de la requête fictive.

UnsupportedRegexReason

Chrome 87 ou version ultérieure

Décrit la raison pour laquelle une expression régulière donnée n'est pas acceptée.

Enum

"syntaxError"
La syntaxe de l'expression régulière est incorrecte ou elle utilise des fonctionnalités qui ne sont pas disponibles dans la syntaxe RE2.

"memoryLimitExceeded"
L'expression régulière dépasse la limite de mémoire.

UpdateRuleOptions

Chrome 87 ou version ultérieure

Propriétés

  • addRules

    Règle[] facultatif

    Règles à ajouter.

  • removeRuleIds

    number[] facultatif

    Identifiants des règles à supprimer. Tous les ID non valides seront ignorés.

UpdateRulesetOptions

Chrome 87 ou version ultérieure

Propriétés

  • disableRulesetIds

    string[] facultatif

    Ensemble des ID correspondant à un élément Ruleset statique qui doit être désactivé.

  • enableRulesetIds

    string[] facultatif

    Ensemble des ID correspondant à un élément Ruleset statique qui doit être activé.

UpdateStaticRulesOptions

Chrome 111 ou version ultérieure

Propriétés

  • disableRuleIds

    number[] facultatif

    Ensemble d'ID correspondant aux règles dans le Ruleset à désactiver.

  • enableRuleIds

    number[] facultatif

    Ensemble d'ID correspondant aux règles du Ruleset à activer.

  • rulesetId

    chaîne

    ID correspondant à un élément Ruleset statique.

URLTransform

Propriétés

  • fragment

    chaîne facultatif

    Nouveau fragment de la requête. Elle doit être vide, auquel cas le fragment existant est effacé, ou commencer par "#".

  • hôte

    chaîne facultatif

    Nouvel hôte pour la requête.

  • mot de passe

    chaîne facultatif

    Nouveau mot de passe pour la requête.

  • chemin d'accès

    chaîne facultatif

    Nouveau chemin d'accès à la requête. S'il est vide, le chemin existant est effacé.

  • port

    chaîne facultatif

    Nouveau port de la requête. Si ce champ est vide, le port existant est effacé.

  • requête

    chaîne facultatif

    Nouvelle requête de la requête. Il doit être vide, auquel cas la requête existante est effacée, ou commencer par un point d'interrogation (?).

  • queryTransform

    QueryTransform facultatif

    Ajoutez, supprimez ou remplacez des paires clé-valeur de requête.

  • schéma

    chaîne facultatif

    Nouveau schéma de la requête. Les valeurs autorisées sont "http", "https", "ftp" et "chrome-extension".

  • nom d'utilisateur

    chaîne facultatif

    Nouveau nom d'utilisateur pour la requête.

Propriétés

DYNAMIC_RULESET_ID

ID de l'ensemble de règles pour les règles dynamiques ajoutées par l'extension.

Valeur

GETMATCHEDRULES_QUOTA_INTERVAL

Intervalle de temps au cours duquel les appels MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules peuvent être effectués, spécifié en minutes. Les appels supplémentaires échouent immédiatement et définissent runtime.lastError. Remarque: Les appels getMatchedRules associés à un geste de l'utilisateur sont exemptés du quota.

Valeur

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 ou version ultérieure

Nombre minimal de règles statiques garanties pour une extension dans l'ensemble de ses ensembles de règles statiques activés. Au-delà de cette limite, toutes les règles sont comptabilisées dans la limite globale de règles statiques.

Valeur

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Nombre de fois où getMatchedRules peut être appelé dans un délai de GETMATCHEDRULES_QUOTA_INTERVAL.

Valeur

20

MAX_NUMBER_OF_DYNAMIC_RULES

Nombre maximal de règles dynamiques qu'une extension peut ajouter.

Valeur

30000

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 ou version ultérieure

Nombre maximal d'Rulesets statiques qu'une extension peut activer simultanément.

Valeur

50

MAX_NUMBER_OF_REGEX_RULES

Nombre maximal de règles d'expression régulière qu'une extension peut ajouter. Cette limite est évaluée séparément pour l'ensemble de règles dynamiques et pour celles spécifiées dans le fichier de ressources de la règle.

Valeur

1000

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 ou version ultérieure

Nombre maximal de règles de portée session qu'une extension peut ajouter.

Valeur

5000

MAX_NUMBER_OF_STATIC_RULESETS

Nombre maximal d'Rulesets statiques qu'une extension peut spécifier dans la clé du fichier manifeste "rule_resources".

Valeur

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 ou version ultérieure

Nombre maximal de règles dynamiques "non sécurisées" qu'une extension peut ajouter.

Valeur

5000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 ou version ultérieure

Nombre maximal de règles "non sécurisées" avec une portée session qu'une extension peut ajouter.

Valeur

5000

SESSION_RULESET_ID

Chrome 90 ou version ultérieure

ID de l'ensemble de règles pour les règles de portée session ajoutées par l'extension.

Valeur

"_session"

Méthodes

getAvailableStaticRuleCount()

Promise Chrome 89 ou version ultérieure 
chrome.declarativeNetRequest.getAvailableStaticRuleCount(
  callback?: function,
)

Renvoie le nombre de règles statiques qu'une extension peut activer avant que la limite globale de règles statiques soit atteinte.

Paramètres

  • rappel

    function facultatif

    Le paramètre callback ressemble à ceci : 

    (count: number) => void

    • nombre

      Nombre

Renvoie

  • Promesse<numéro>

    Chrome 91 ou version ultérieure

    Les promesses sont compatibles avec Manifest V3 et versions ultérieures, mais les rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

getDisabledRuleIds()

Promise Chrome 111 ou version ultérieure 
chrome.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
  callback?: function,
)

Renvoie la liste des règles statiques actuellement désactivées dans l'objet Ruleset donné.

Paramètres

  • Spécifie l'ensemble de règles à interroger.

  • rappel

    function facultatif

    Le paramètre callback ressemble à ceci : 

    (disabledRuleIds: number[]) => void

    • disabledRuleIds

      numéro[]

Renvoie

  • Promesse<numéro[]>

    Les promesses sont compatibles avec Manifest V3 et versions ultérieures, mais les rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

getDynamicRules()

Promesse 
chrome.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
  callback?: function,
)

Renvoie l'ensemble actuel de règles dynamiques pour l'extension. Les appelants peuvent éventuellement filtrer la liste des règles récupérées en spécifiant un filter.

Paramètres

  • filtre

    GetRulesFilter facultatif

    Chrome 111 ou version ultérieure

    Objet permettant de filtrer la liste des règles récupérées.

  • rappel

    function facultatif

    Le paramètre callback ressemble à ceci : 

    (rules: Rule[]) => void

Renvoie

  • Promise<Rule[]>

    Chrome 91 ou version ultérieure

    Les promesses sont compatibles avec Manifest V3 et versions ultérieures, mais les rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

getEnabledRulesets()

Promesse 
chrome.declarativeNetRequest.getEnabledRulesets(
  callback?: function,
)

Renvoie les identifiants pour l'ensemble actuel d'ensembles de règles statiques activés.

Paramètres

  • rappel

    function facultatif

    Le paramètre callback ressemble à ceci : 

    (rulesetIds: string[]) => void

    • rulesetIds

      chaîne[]

Renvoie

  • Promesse<string[]>

    Chrome 91 ou version ultérieure

    Les promesses sont compatibles avec Manifest V3 et versions ultérieures, mais les rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

getMatchedRules()

Promesse 
chrome.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
  callback?: function,
)

Affiche toutes les règles correspondant à l'extension. Les appelants peuvent éventuellement filtrer la liste des règles correspondantes en spécifiant un filter. Cette méthode n'est disponible que pour les extensions disposant de l'autorisation "declarativeNetRequestFeedback" ou de l'autorisation "activeTab" accordée pour l'élément tabId spécifié dans filter. Remarque: Les règles qui ne sont pas associées à un document actif pour lequel les correspondances ont été trouvées il y a plus de cinq minutes ne sont pas renvoyées.

Paramètres

Renvoie

  • Chrome 91 ou version ultérieure

    Les promesses sont compatibles avec Manifest V3 et versions ultérieures, mais les rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

getSessionRules()

Promise Chrome 90 ou version ultérieure 
chrome.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
  callback?: function,
)

Affiche l'ensemble actuel de règles de portée session pour l'extension. Les appelants peuvent éventuellement filtrer la liste des règles récupérées en spécifiant un filter.

Paramètres

  • filtre

    GetRulesFilter facultatif

    Chrome 111 ou version ultérieure

    Objet permettant de filtrer la liste des règles récupérées.

  • rappel

    function facultatif

    Le paramètre callback ressemble à ceci : 

    (rules: Rule[]) => void

Renvoie

  • Promise<Rule[]>

    Chrome 91 ou version ultérieure

    Les promesses sont compatibles avec Manifest V3 et versions ultérieures, mais les rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

isRegexSupported()

Promise Chrome 87 ou version ultérieure 
chrome.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
  callback?: function,
)

Vérifie si l'expression régulière donnée peut être utilisée en tant que condition de règle regexFilter.

Paramètres

Renvoie

  • Chrome 91 ou version ultérieure

    Les promesses sont compatibles avec Manifest V3 et versions ultérieures, mais les rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

setExtensionActionOptions()

Promise Chrome 88 ou version ultérieure 
chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
  callback?: function,
)

Configure si le nombre d'actions pour les onglets doit être affiché en tant que texte de badge de l'action de l'extension et permet d'incrémenter ce nombre d'actions.

Paramètres

  • rappel

    function facultatif

    Chrome 89 ou version ultérieure

    Le paramètre callback ressemble à ceci : 

    () => void

Renvoie

  • Promise<void>

    Chrome 91 ou version ultérieure

    Les promesses sont compatibles avec Manifest V3 et versions ultérieures, mais les rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

testMatchOutcome()

Promise Chrome 103 ou version ultérieure 
chrome.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
  callback?: function,
)

Vérifie si l'une des règles déclarativeNetRequest de l'extension correspond à une requête hypothétique. Remarque: Disponible uniquement pour les extensions non empaquetées, car elle est uniquement destinée au développement d'extensions.

Paramètres

Renvoie

  • Les promesses sont compatibles avec Manifest V3 et versions ultérieures, mais les rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

updateDynamicRules()

Promesse 
chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
  callback?: function,
)

Modifie l'ensemble actuel de règles dynamiques pour l'extension. Les règles dont les ID sont répertoriés dans options.removeRuleIds sont d'abord supprimées, puis les règles fournies dans options.addRules sont ajoutées. Remarques :

  • Cette mise à jour se produit en une seule opération atomique: soit toutes les règles spécifiées sont ajoutées et supprimées, soit une erreur est renvoyée.
  • Ces règles sont conservées d'une session de navigateur à l'autre et lors des mises à jour d'extensions.
  • Les règles statiques spécifiées dans le package d'extension ne peuvent pas être supprimées à l'aide de cette fonction.
  • MAX_NUMBER_OF_DYNAMIC_RULES est le nombre maximal de règles dynamiques qu'une extension peut ajouter. Le nombre de règles non sécurisées ne doit pas dépasser MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES.

Paramètres

  • Chrome 87 ou version ultérieure
  • rappel

    function facultatif

    Le paramètre callback ressemble à ceci : 

    () => void

Renvoie

  • Promise<void>

    Chrome 91 ou version ultérieure

    Les promesses sont compatibles avec Manifest V3 et versions ultérieures, mais les rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

updateEnabledRulesets()

Promesse 
chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
  callback?: function,
)

Met à jour l'ensemble des ensembles de règles statiques activés pour l'extension. Les ensembles de règles dont les ID sont répertoriés dans options.disableRulesetIds sont d'abord supprimés, puis les ensembles de règles listés dans options.enableRulesetIds sont ajoutés. Notez que l'ensemble d'ensembles de règles statiques activés est conservé d'une session à l'autre, mais pas entre les mises à jour d'extension. Par exemple, la clé du fichier manifeste rule_resources détermine l'ensemble d'ensembles de règles statiques activés lors de chaque mise à jour d'extension.

Paramètres

  • Chrome 87 ou version ultérieure
  • rappel

    function facultatif

    Le paramètre callback ressemble à ceci : 

    () => void

Renvoie

  • Promise<void>

    Chrome 91 ou version ultérieure

    Les promesses sont compatibles avec Manifest V3 et versions ultérieures, mais les rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

updateSessionRules()

Promise Chrome 90 ou version ultérieure 
chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
  callback?: function,
)

Modifie l'ensemble actuel de règles de portée session pour l'extension. Les règles dont les ID sont répertoriés dans options.removeRuleIds sont d'abord supprimées, puis les règles fournies dans options.addRules sont ajoutées. Remarques :

  • Cette mise à jour se produit en une seule opération atomique: soit toutes les règles spécifiées sont ajoutées et supprimées, soit une erreur est renvoyée.
  • Ces règles ne sont pas conservées d'une session à l'autre et sont sauvegardées en mémoire.
  • MAX_NUMBER_OF_SESSION_RULES est le nombre maximal de règles de session qu'une extension peut ajouter.

Paramètres

  • rappel

    function facultatif

    Le paramètre callback ressemble à ceci : 

    () => void

Renvoie

  • Promise<void>

    Chrome 91 ou version ultérieure

    Les promesses sont compatibles avec Manifest V3 et versions ultérieures, mais les rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

updateStaticRules()

Promise Chrome 111 ou version ultérieure 
chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
  callback?: function,
)

Désactive et active des règles statiques individuelles dans un élément Ruleset. Les modifications apportées aux règles appartenant à un Ruleset désactivé prendront effet la prochaine fois que celle-ci sera activée.

Paramètres

Renvoie

  • Promise<void>

    Les promesses sont compatibles avec Manifest V3 et versions ultérieures, mais les rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

Événements

onRuleMatchedDebug

chrome.declarativeNetRequest.onRuleMatchedDebug.addListener(
  callback: function,
)

Déclenché lorsqu'une règle est mise en correspondance avec une requête. Disponible uniquement pour les extensions non empaquetées avec l'autorisation "declarativeNetRequestFeedback", car celle-ci est uniquement destinée au débogage.

Paramètres