browser.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, ce qui renforce la confidentialité.

Autorisations

declarativeNetRequest
declarativeNetRequestWithHostAccess

Les autorisations "declarativeNetRequest" et "declarativeNetRequestWithHostAccess" fournissent les mêmes fonctionnalités. La différence entre les deux 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 cette option dans la mesure du possible pour éviter d'avoir à 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 avant de pouvoir effectuer une action sur un hôte. Cette option est appropriée lorsque vous souhaitez utiliser des règles de requête réseau déclaratives dans une extension qui dispose déjà d'autorisations d'hôte sans générer d'avertissements supplémentaires.

Disponibilité

Chrome 84+ browser.* depuis Chrome 148

Fichier manifeste

En plus des autorisations décrites précédemment, certains types d'ensembles de règles, en particulier les ensembles de règles statiques, nécessitent de déclarer la clé de fichier manifeste "declarative_net_request", qui doit être un dictionnaire avec 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" 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/*"
  ],
  ...
}

Règles et ensembles de règles

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 règle unique effectue l'une des opérations suivantes :

• Bloquer une requête réseau.
• Mettez à niveau le schéma (http vers https).
• Empêchez le blocage d'une requête en annulant les règles de blocage correspondantes.
• Rediriger une requête réseau.
• Modifier 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

Ils persistent d'une session de navigateur à l'autre et d'une mise à niveau d'extension à l'autre, et sont gérés à l'aide de JavaScript lorsqu'une extension est utilisée.

Session

Effacé lorsque le navigateur s'arrête et lorsqu'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

Empaquetté, installé et mis à jour lorsqu'une extension est installée ou mise à niveau. Les règles statiques sont stockées dans des fichiers de règles au format JSON et listées dans le fichier manifeste.

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 d'une session de navigateur à l'autre et lors des 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 ensemble de règles de chaque type. Une extension peut ajouter ou supprimer des règles de manière dynamique en appelant updateDynamicRules() et updateSessionRules(), à condition que les limites de règles ne soient pas dépassées. Pour en savoir plus sur les limites des règles, consultez Limites des règles. Vous trouverez un exemple de ce type dans la section Exemples de code sous Exemples de code.

Ensembles de règles statiques

Contrairement aux règles dynamiques et de session, les règles statiques sont empaquetées, installées et mises à jour lorsqu'une extension est installée ou mise à niveau. Elles sont stockées 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 de plusieurs dictionnaires Ruleset. Un dictionnaire Ruleset contient un chemin d'accès au fichier de règles, un ID pour l'ensemble de règles contenu dans le fichier, et indique 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 décompressée. Les erreurs et les avertissements concernant des règles statiques non valides ne s'affichent que pour les extensions non empaquetées. Les règles statiques non valides dans les extensions empaqueté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é des modifications éligibles.

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

Les règles statiques individuelles et les ensembles de règles statiques complets peuvent être activés ou désactivés 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. Aucune de ces modifications n'est conservée lors des mises à jour de l'extension. Cela signifie que seules les règles que vous avez choisi de laisser 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 Limites des règles.

Pour activer ou désactiver des 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. Le nombre maximal de règles statiques désactivées est de 5 000.

Pour activer ou désactiver des ensembles de règles 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.

Règles de compilation

Quel que soit son type, une règle commence par quatre champs, comme indiqué ci-dessous. Alors que les clés "id" et "priority" prennent 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 contenant la sous-chaîne "abc".

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

Mise en correspondance des URL

Declarative Net Request permet de faire correspondre des URL à l'aide d'une syntaxe de correspondance de modèle ou d'expressions régulières.

Syntaxe des filtres d'URL

La clé "condition" d'une règle permet d'utiliser une clé "urlFilter" pour agir sur les URL d'un domaine spécifié. Vous créez des modèles à l'aide de jetons de correspondance de modèles. 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://a.example.company	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

Expressions régulières

Les conditions peuvent également utiliser des expressions régulières. Consultez la clé "regexFilter". Pour en savoir plus sur les limites qui s'appliquent à ces conditions, consultez Règles utilisant des expressions régulières.

Rédiger des conditions d'URL appropriées

Lorsque vous écrivez des règles, veillez à toujours faire correspondre un domaine entier. Sinon, votre règle peut correspondre à des situations inattendues. Par exemple, lorsque vous utilisez la syntaxe de correspondance de modèles :

• google.com correspond incorrectement à https://example.com/?param=google.com
• ||google.com correspond incorrectement à https://google.company
• https://www.google.com correspond incorrectement à https://example.com/?param=https://www.google.com

À envisager :

• ||google.com/, qui correspond à tous les chemins d'accès et à tous les sous-domaines.
• |https://www.google.com/, qui correspond à tous les chemins d'accès et à aucun sous-domaine.

De même, utilisez les caractères ^ et / pour ancrer une expression régulière. Par exemple, ^https:\/\/www\.google\.com\/ correspond à n'importe quel chemin d'accès sur https://www.google.com.

Évaluation des règles

Les règles DNR sont appliquées par le navigateur à différentes étapes du cycle de vie des requêtes réseau.

Avant la demande

Avant qu'une requête ne soit effectuée, une extension peut la bloquer ou la rediriger (y compris en faisant passer le schéma de HTTP à HTTPS) à l'aide d'une règle correspondante.

Pour chaque extension, le navigateur détermine une liste de règles de correspondance. Les règles avec une action modifyHeaders ne sont pas incluses ici, car elles seront traitées ultérieurement. De plus, les règles avec une condition responseHeaders seront prises en compte ultérieurement (lorsque les en-têtes de réponse seront disponibles) et ne sont pas incluses.

Ensuite, pour chaque extension, Chrome choisit au maximum un candidat par requête. Chrome trouve une règle correspondante en classant toutes les règles correspondantes par priorité. Les règles ayant la même priorité sont classées par action (allow ou allowAllRequests > block > upgradeScheme > redirect).

Si le candidat est une règle allow ou allowAllRequests, ou si le frame dans lequel la requête est effectuée correspondait précédemment à une règle allowAllRequests de priorité supérieure ou égale de cette extension, la requête est "autorisée" et l'extension n'aura aucun effet sur la requête.

Si plusieurs extensions souhaitent bloquer ou rediriger cette requête, une seule action à effectuer est choisie. Pour ce faire, Chrome trie les règles dans l'ordre block > redirect ou upgradeScheme > allow ou allowAllRequests. Si deux règles sont du même type, Chrome choisit la règle de l'extension installée le plus récemment.

Attention : Les fournisseurs de navigateurs ont convenu de ne pas standardiser l'ordre d'exécution des règles ayant la même action et la même priorité. Cela peut changer entre les exécutions ou les versions du navigateur, même lorsque les règles sont réparties entre plusieurs types d'ensembles de règles (par exemple, une règle statique et une règle de session). Lorsque l'ordre est important, vous devez toujours spécifier explicitement une priorité.

Avant l'envoi des en-têtes de requête

Avant que Chrome n'envoie les en-têtes de requête au serveur, ils sont mis à jour en fonction des règles modifyHeaders correspondantes.

Dans une même extension, Chrome dresse la liste des modifications à effectuer en recherchant toutes les règles modifyHeaders correspondantes. Comme précédemment, seules les règles dont la priorité est supérieure à celle des règles allow ou allowAllRequests correspondantes sont incluses.

Ces règles sont appliquées par Chrome dans un ordre tel que les règles d'une extension installée plus récemment sont toujours évaluées avant celles d'une extension plus ancienne. De plus, les règles de priorité supérieure d'une extension sont toujours appliquées avant les règles de priorité inférieure de la même extension. Notamment, même entre les extensions :

• Si une règle ajoute un en-tête, les règles de priorité inférieure ne peuvent qu'ajouter 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, seules les règles de priorité inférieure de la même extension peuvent ajouter des valeurs à 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 pas le modifier davantage.

Une fois la réponse reçue

Une fois les en-têtes de réponse reçus, Chrome évalue les règles avec une condition responseHeaders.

Après avoir trié ces règles par action et priority, et exclu toutes les règles rendues redondantes par une règle allow ou allowAllRequests correspondante (comme lors des étapes de la section "Avant la requête"), Chrome peut bloquer ou rediriger la requête au nom d'une extension.

Notez que si une requête est parvenue à ce stade, elle a déjà été envoyée au serveur, et celui-ci a reçu des données telles que le corps de la requête. Une règle de blocage ou de redirection avec une condition d'en-tête de réponse s'exécutera toujours, mais ne pourra pas bloquer ni rediriger la requête.

Dans le cas d'une règle de blocage, la page qui a effectué la requête reçoit une réponse de blocage, et Chrome met fin à la requête de manière anticipée. Dans le cas d'une règle de redirection, Chrome envoie une nouvelle requête à l'URL de redirection. Assurez-vous de déterminer si ces comportements répondent aux attentes de confidentialité de votre extension.

Si la requête n'est pas bloquée ni redirigée, Chrome applique les règles modifyHeaders. L'application de modifications aux en-têtes de réponse fonctionne de la même manière que celle décrite dans "Avant l'envoi des en-têtes de requête". L'application de modifications aux en-têtes de requête n'a aucun effet, car la requête a déjà été effectuée.

Règles de sécurité

Les règles sécurisées sont définies comme des règles avec une action block, allow, allowAllRequests ou upgradeScheme. Ces règles sont soumises à un quota de règles dynamiques plus élevé.

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 ensembles de règles statiques dans la clé de fichier manifeste "rule_resources", mais seuls 50 de ces ensembles de règles peuvent être activés à la fois. Cela s'appelle une MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Collectivement, ces ensembles de règles sont garantis d'avoir au moins 30 000 règles. C'est ce qu'on appelle l'GUARANTEED_MINIMUM_STATIC_RULES.

Remarque : Avant Chrome 120, les extensions étaient limitées à un total de 50 ensembles de règles statiques, et seulement 10 d'entre eux pouvaient être activés en même temps. Utilisez le champ de fichier manifeste minimum_chrome_version pour limiter les versions de Chrome pouvant installer votre extension.

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

Remarque : À partir de Chrome 128, si un utilisateur désactive une extension via chrome://extensions, les règles statiques de l'extension ne seront plus comptabilisées dans la limite globale de règles statiques. Cela peut libérer un quota de règles statiques pour d'autres extensions, mais cela signifie également que lorsque l'extension est réactivée, elle peut disposer de moins de règles statiques qu'auparavant.

Règles de session

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

Avant Chrome 120, la limite était de 5 000 règles dynamiques et de session combinées.

Les règles dynamiques

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

À partir de Chrome 121, la limite est portée à 30 000 règles pour les règles dynamiques sûres, exposées en tant que MAX_NUMBER_OF_DYNAMIC_RULES. Toutes 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, la limite était de 5 000 règles dynamiques et de session combinées.

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 limite MAX_NUMBER_OF_REGEX_RULES.

De plus, chaque règle doit faire moins de 2 Ko une fois compilée. Cela correspond approximativement à 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 requête declarativeNetRequest ne s'applique qu'aux requêtes qui atteignent la pile réseau. Cela inclut les réponses du cache HTTP, mais peut ne pas inclure les réponses qui passent par le gestionnaire onfetch d'un service worker. declarativeNetRequest n'affectera pas les réponses générées par le service worker ni récupérées à partir de CacheStorage, mais affectera les appels à fetch() effectués dans un service worker.

Ressources accessibles sur le Web

Une règle declarativeNetRequest ne peut pas rediriger une requête de ressource publique vers une ressource qui n'est pas accessible sur le Web. Cela déclenche une erreur. Cela s'applique 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.

Modification d'en-tête

L'opération d'ajout n'est compatible qu'avec les en-têtes de requête suivants : accept, accept-encoding, accept-language, access-control-request-headers, cache-control, connection, content-language, cookie, forwarded, if-match, if-none-match, keep-alive, range, te, trailer, transfer-encoding, upgrade, user-agent, via, want-digest, x-forwarded-for. Cette liste d'autorisation est sensible à la casse (bug 449152902).

Lors de l'ajout à un en-tête de requête ou de réponse, le navigateur utilise le séparateur approprié dans la mesure du possible.

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 browser.declarativeNetRequest.getDynamicRules();
const oldRuleIds = oldRules.map(rule => rule.id);

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

Mettre à jour les ensembles de règles statiques

L'exemple suivant montre comment activer et désactiver des ensembles de règles 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 pouvez procéder ainsi 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 avec certains de vos ensembles de règles désactivés (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 browser.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 > browser.declarativeNetRequest.MAX_NUMBER_OF_ENABLED_STATIC_RULESETS) {
    options.disableRulesetIds = disableCandidateIds
  }
  // Update the enabled static rules
  await browser.declarativeNetRequest.updateEnabledRulesets(options);
}

Exemples de règles

Les exemples suivants illustrent la façon dont Chrome priorise les règles dans une extension. Lorsque vous les examinez, vous pouvez ouvrir les règles de priorisation dans une fenêtre distincte.

La clé "priority"

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

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

Navigation vers https://google.com

Deux règles couvrent cette URL : les règles avec les ID 1 et 4. La règle avec l'ID 1 s'applique, car les actions "block" ont une priorité plus élevée que les actions "redirect". Les autres règles ne s'appliquent pas, car elles concernent des URL plus longues.

Navigation vers https://google.com/1234

En raison de l'URL plus longue, la règle avec l'ID 2 correspond désormais, en plus des règles avec les ID 1 et 4. La règle avec l'ID 2 s'applique, car "allow" a une priorité plus élevée que "block" et "redirect".

Navigation vers https://google.com/12345

Les quatre règles correspondent à cette URL. La règle avec 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 l'autorisation d'hôte pour *://*.example.com/*.

L'exemple suivant montre comment rediriger une requête de example.com vers une page de l'extension elle-même. Le chemin d'accès de l'extension /a.jpg correspond à 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 en tant que 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"]
  }
}

L'exemple suivant utilise la clé "transform" pour rediriger vers un sous-domaine de example.com. Il utilise une ancre de nom de domaine ("||") pour intercepter les requêtes avec n'importe quel schéma de 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 https://www.abc.xyz.com/path vers https://abc.xyz.com/path. Dans la clé "regexFilter", notez que 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 de 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

Cela indique si la requête est propriétaire ou tierce par rapport au frame d'origine. Une requête est dite "first party" si elle a le même domaine (eTLD+1) que le frame d'où elle provient.

Énumération

"firstParty"
La requête réseau est first party par rapport au frame d'origine.

"thirdParty"
La requête réseau est tierce par rapport au frame d'origine.

ExtensionActionOptions

Chrome 88+ browser.* depuis Chrome 148

Propriétés

• displayActionCountAsBadgeText

  boolean facultatif

  Indique si le nombre d'actions pour une page doit s'afficher automatiquement 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+ browser.* depuis Chrome 148

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

GetDisabledRuleIdsOptions

Chrome 111 ou version ultérieure browser.* depuis Chrome 148

Propriétés

• rulesetId

  chaîne

  ID correspondant à un Ruleset statique.

GetRulesFilter

Chrome 111 ou version ultérieure browser.* depuis Chrome 148

Propriétés

• ruleIds

  number[] facultatif

  Si ce paramètre est spécifié, seules les règles dont l'ID correspond sont incluses.

HeaderInfo

Chrome 128+ browser.* depuis Chrome 148

Propriétés

• excludedValues

  string[] facultatif

  Si elle est spécifiée, cette condition n'est pas remplie si l'en-tête existe, mais que sa valeur contient au moins un élément de cette liste. Il utilise la même syntaxe de motif de correspondance que values.

• en-tête

  chaîne

  Nom de l'en-tête. Cette condition ne correspond au nom que si values et excludedValues ne sont pas spécifiés.

• valeurs

  string[] facultatif

  Si elle est spécifiée, cette condition est remplie si la valeur de l'en-tête correspond à au moins un modèle de cette liste. Cela permet de faire correspondre les valeurs d'en-tête non sensibles à la casse, ainsi que les constructions suivantes :

  '*' : correspond à n'importe quel nombre de caractères.

  '?' : correspond à zéro ou un caractère.

  Les caractères "*" et "?" peuvent être échappés à l'aide d'une barre oblique inverse, par exemple "\*" et "\?".

HeaderOperation

Chrome 86 et versions ultérieures browser.* depuis Chrome 148

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

Énumération

"append"
Ajoute une entrée pour l'en-tête spécifié. Lorsque vous modifiez les en-têtes d'une requête, cette opération n'est possible que pour certains en-têtes.

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

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

IsRegexSupportedResult

Chrome 87+ browser.* depuis Chrome 148

Propriétés

• isSupported

  booléen

• reason

  UnsupportedRegexReason facultatif

  Spécifie la raison pour laquelle l'expression régulière n'est pas acceptée. Fourni uniquement si isSupported est défini sur "false".

MatchedRule

Propriétés

• ruleId

  nombre

  ID d'une règle de correspondance.

• rulesetId

  chaîne

  ID de la ressource Ruleset à laquelle appartient cette règle. 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 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 correspondront à la convention JavaScript pour les heures, c'est-à-dire le nombre de millisecondes depuis l'epoch.

MatchedRuleInfoDebug

Propriétés

• request

  RequestDetails

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

• règle

  MatchedRule

MatchedRulesFilter

Propriétés

• minTimeStamp

  number facultatif

  Si cette option est spécifiée, seules les règles postérieures au code temporel indiqué sont mises en correspondance.

• tabId

  number facultatif

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

ModifyHeaderInfo

Chrome 86 et versions ultérieures browser.* depuis Chrome 148

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

  boolean facultatif

  Chrome 94+ browser.* depuis Chrome 148

  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'ensemble du texte associé.

• 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+ browser.* depuis Chrome 148

Propriétés

• isCaseSensitive

  boolean facultatif

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

• regex

  chaîne

  Expression régulière à vérifier.

• requireCapturing

  boolean facultatif

  Indique si le regex spécifié nécessite une capture. 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" (inactif).

RequestDetails

Propriétés

• documentId

  chaîne facultatif

  Chrome 106 et versions ultérieures browser.* depuis Chrome 148

  Identifiant unique du document du frame, si cette requête concerne un frame.

• documentLifecycle

  DocumentLifecycle facultatif

  Chrome 106 et versions ultérieures browser.* depuis Chrome 148

  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-)frame est chargé (type est main_frame ou sub_frame), frameId indique l'ID de ce frame, et non l'ID du frame externe. Les ID de frame sont uniques dans un onglet.

• frameType

  FrameType facultatif

  Chrome 106 et versions ultérieures browser.* depuis Chrome 148

  Type de frame, si cette requête concerne un frame.

• initiateur

  chaîne facultatif

  Origine de la requête. Cela ne change pas avec les redirections. S'il s'agit d'une origine opaque, la chaîne "null" sera utilisée.

• method

  chaîne

  Méthode HTTP standard.

• parentDocumentId

  chaîne facultatif

  Chrome 106 et versions ultérieures browser.* depuis Chrome 148

  Identifiant unique du document parent du frame, si cette requête concerne un frame et possède un parent.

• parentFrameId

  nombre

  ID du frame qui encapsule le frame ayant envoyé la requête. Définie sur -1 si aucun frame parent n'existe.

• requestId

  chaîne

  ID de la requête. Les ID de requête sont uniques au sein d'une session de navigateur.

• tabId

  nombre

  ID de l'onglet dans lequel la requête est effectuée. Définie sur -1 si la requête n'est pas liée à un onglet.

• type

  ResourceType

  Type de ressource de la requête.

• url

  chaîne

  URL de la requête.

RequestMethod

Chrome 91 et versions ultérieures browser.* depuis Chrome 148

Il s'agit de la méthode de requête HTTP d'une requête réseau.

Énumération

"connect"

"delete"

"get"

"head"

"options"

"patch"

"post"

"put"

"other"

ResourceType

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

Énumération

"main_frame"

"sub_frame"

"stylesheet"

"script"

"image"

"font"

"object"

"xmlhttprequest"

"ping"

"csp_report"

"media"

"websocket"

"webtransport"

"webbundle"

"other"

Rule

Propriétés

• action

  RuleAction

  Action à effectuer si cette règle est mise en correspondance.

• état

  RuleCondition

  Condition sous laquelle cette règle est déclenchée.

• id

  nombre

  ID qui identifie une règle de manière unique. Obligatoire et doit être supérieur ou égal à 1.

• priorité

  number facultatif

  Priorité de la règle. La valeur par défaut est 1. Si elle est spécifiée, la valeur doit être supérieure ou égale à 1.

RuleAction

Propriétés

• redirection

  Redirection facultatif

  Décrit la façon dont la redirection doit être effectuée. Uniquement valide pour les règles de redirection.

• requestHeaders

  ModifyHeaderInfo[] facultatif

  Chrome 86 et versions ultérieures browser.* depuis Chrome 148

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

• responseHeaders

  ModifyHeaderInfo[] facultatif

  Chrome 86 et versions ultérieures browser.* depuis Chrome 148

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

• type

  RuleActionType

  Type d'action à effectuer.

RuleActionType

Décrit le type d'action à effectuer si une condition de règle donnée est remplie.

Énumération

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

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

"allow"
Autorise la requête réseau. La requête ne sera pas interceptée si une règle d'autorisation correspondante existe.

"upgradeScheme"
Mettre à niveau le schéma de l'URL de la requête réseau vers 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"
Autorise toutes les requêtes au sein d'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 propriétaire ou tierce par rapport au domaine d'origine. Si cette option est omise, toutes les requêtes sont acceptées.

• domaines

  string[] facultatif

  Obsolète depuis Chrome 101

  Utiliser initiatorDomains à la place

  La règle ne correspondra qu'aux requêtes réseau provenant de la liste de domains.

• excludedDomains

  string[] facultatif

  Obsolète depuis Chrome 101

  Utiliser excludedInitiatorDomains à la place

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

• excludedInitiatorDomains

  string[] facultatif

  Chrome 101+ browser.* depuis Chrome 148

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

  Remarques :

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

  string[] facultatif

  Chrome 101+ browser.* depuis Chrome 148

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

  Remarques :

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

  RequestMethod[] facultatif

  Chrome 91 et versions ultérieures browser.* depuis Chrome 148

  Liste des méthodes de requête auxquelles la règle ne correspondra pas. Vous ne devez spécifier qu'un seul élément entre requestMethods et excludedRequestMethods. Si aucune de ces options 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 correspondra pas. Vous ne devez spécifier qu'un seul élément entre resourceTypes et excludedResourceTypes. Si aucune de ces valeurs n'est spécifiée, tous les types de ressources sont bloqués, à l'exception de "main_frame".

• excludedResponseHeaders

  HeaderInfo[] facultatif

  Chrome 128+ browser.* depuis Chrome 148

  La règle ne correspond pas si la requête correspond à une condition d'en-tête de réponse de cette liste (si spécifiée). Si les champs excludedResponseHeaders et responseHeaders sont tous deux spécifiés, la propriété excludedResponseHeaders est prioritaire.

• excludedTabIds

  number[] facultatif

  Chrome 92+ browser.* depuis Chrome 148

  Liste des tabs.Tab.id qui ne doivent pas correspondre à la règle. Un ID de 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.

• excludedTopDomains

  string[] facultatif

  Chrome 145+ browser.* depuis Chrome 148

  La règle ne correspondra pas aux requêtes réseau lorsque le domaine du frame de premier niveau associé correspond à l'un des domaines de la liste excludedTopDomains. Si la liste est vide ou omise, aucun domaine n'est exclu. Cette option est prioritaire sur topDomains.

  Remarques :

  • Les sous-domaines tels que "a.example.com" sont également autorisés.
  • Les entrées ne doivent contenir que des caractères ASCII.
  • Utilisez l'encodage Punycode pour les domaines internationalisés.
  • Les sous-domaines des domaines listés sont également exclus.
  • Pour les requêtes sans frame de niveau supérieur associée (par exemple, les requêtes initiées par ServiceWorker), le domaine de l'initiateur de la requête est pris en compte à la place.
• initiatorDomains

  string[] facultatif

  Chrome 101+ browser.* depuis Chrome 148

  La règle ne correspondra qu'aux requêtes réseau provenant de la liste de 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 contenir que des caractères ASCII.
  • Utilisez l'encodage Punycode pour les domaines internationalisés.
  • Cela correspond à l'initiateur de la requête, et non à l'URL de la requête.
  • Les sous-domaines des domaines listés sont également mis en correspondance.
• isUrlFilterCaseSensitive

  boolean facultatif

  Indique si urlFilter ou regexFilter (selon ce qui est spécifié) 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. Elle suit la syntaxe RE2.

  Remarque : Vous ne pouvez spécifier qu'un seul des éléments urlFilter ou regexFilter.

  Remarque : regexFilter ne doit être composé que de caractères ASCII. Cette valeur est comparée à une URL dont l'hôte est encodé au format Punycode (dans le cas de domaines internationalisés) et dont les autres caractères non ASCII sont encodés en UTF-8.

• requestDomains

  string[] facultatif

  Chrome 101+ browser.* depuis Chrome 148

  La règle ne correspondra aux requêtes réseau que si le domaine correspond à l'un des domaines de la liste de 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 contenir que des caractères ASCII.
  • Utilisez l'encodage Punycode pour les domaines internationalisés.
  • Les sous-domaines des domaines listés sont également mis en correspondance.
• requestMethods

  RequestMethod[] facultatif

  Chrome 91 et versions ultérieures browser.* depuis Chrome 148

  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 non HTTP(S) seront également exclues, ce qui n'est pas le cas si vous spécifiez excludedRequestMethods.

• resourceTypes

  ResourceType[] facultatif

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

  Remarque : Vous devez spécifier cette option pour les règles allowAllRequests. Elle ne peut inclure que les types de ressources sub_frame et main_frame.

• responseHeaders

  HeaderInfo[] facultatif

  Chrome 128+ browser.* depuis Chrome 148

  La règle correspond si la requête correspond à une condition d'en-tête de réponse de cette liste (si spécifiée).

• tabIds

  number[] facultatif

  Chrome 92+ browser.* depuis Chrome 148

  Liste des tabs.Tab.id auxquels la règle doit correspondre. Un ID de 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.

• topDomains

  string[] facultatif

  Chrome 145+ browser.* depuis Chrome 148

  La règle ne correspondra aux requêtes réseau que lorsque le domaine du frame de premier niveau associé correspondra à l'un des domaines de la liste de topDomains. Si la liste est omise, la règle est appliquée aux requêtes associées à tous les domaines de frame de premier niveau. 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 contenir que des caractères ASCII.
  • Utilisez l'encodage Punycode pour les domaines internationalisés.
  • Les sous-domaines des domaines listés sont également mis en correspondance.
  • Pour les requêtes sans frame de niveau supérieur associée (par exemple, les requêtes initiées par ServiceWorker), le domaine de l'initiateur de la requête est pris en compte à la place.
• urlFilter

  chaîne facultatif

  Modèle mis en correspondance avec l'URL de la requête réseau. Constructions compatibles :

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

  '|' : ancre gauche/droite. Si ce caractère est utilisé à l'une des extrémités du format, il spécifie respectivement le début/la fin de l'URL.

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

  '^' : caractère de séparation. Il correspond à n'importe quel caractère, à l'exception d'une lettre, d'un chiffre ou de l'un des éléments suivants : _, -, . ou %. Cela correspond également à la fin de l'URL.

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

  Si cette option est omise, toutes les URL sont mises en correspondance. Une chaîne vide n'est pas autorisée.

  Un format commençant par ||* n'est pas autorisé. Utilisez * à la place.

  Remarque : Vous ne pouvez spécifier qu'un seul des éléments urlFilter ou regexFilter.

  Remarque : urlFilter ne doit être composé que de caractères ASCII. Cette valeur est comparée à une URL dont l'hôte est encodé au format Punycode (dans le cas de domaines internationalisés) et dont les autres caractères non ASCII sont encodés en UTF-8. Par exemple, lorsque l'URL de la requête est http://abc.рф?q=ф, l'urlFilter sera mis en correspondance avec l'URL http://abc.xn--p1ai/?q=%D1%84.

RuleConditionKeys

Chrome 145+ browser.* depuis Chrome 148

Énumération

"urlFilter"

"regexFilter"

"isUrlFilterCaseSensitive"

"initiatorDomains"

"excludedInitiatorDomains"

"requestDomains"

"excludedRequestDomains"

"topDomains"

"excludedTopDomains"

"domains"

"excludedDomains"

"resourceTypes"

"excludedResourceTypes"

"requestMethods"

"excludedRequestMethods"

"domainType"

"tabIds"

"excludedTabIds"

"responseHeaders"

"excludedResponseHeaders"

Ruleset

Propriétés

• activé

  booléen

  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 de l'ensemble de règles JSON par rapport au répertoire de l'extension.

RulesMatchedDetails

Propriétés

• rulesMatchedInfo

  MatchedRuleInfo[]

  Règles correspondant au filtre donné.

TabActionCountUpdate

Chrome 89+ browser.* depuis Chrome 148

Propriétés

• increment

  nombre

  Valeur d'incrémentation du nombre d'actions de l'onglet. Les valeurs négatives décrémentent le nombre.

• tabId

  nombre

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

TestMatchOutcomeResult

Chrome 103 et versions ultérieures browser.* depuis Chrome 148

Propriétés

• matchedRules

  MatchedRule[]

  Les règles (le cas échéant) qui correspondent à la requête hypothétique.

TestMatchRequestDetails

Chrome 103 et versions ultérieures browser.* depuis Chrome 148

Propriétés

• initiateur

  chaîne facultatif

  URL de l'initiateur (le cas échéant) pour la requête hypothétique.

• method

  RequestMethod facultatif

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

• responseHeaders

  objet facultatif

  Chrome 129+ browser.* depuis Chrome 148

  En-têtes fournis par une réponse hypothétique si la requête n'est pas bloquée ni redirigée avant d'être envoyée. Représenté sous la forme d'un objet qui mappe un nom d'en-tête à une liste de valeurs de chaîne. S'il n'est pas spécifié, la réponse hypothétique renvoie des en-têtes de réponse vides, qui peuvent correspondre à des règles qui correspondent à l'absence d'en-têtes. Exemple : {"content-type": ["text/html; charset=utf-8", "multipart/form-data"]}

• tabId

  number facultatif

  ID de l'onglet dans lequel la requête hypothétique a lieu. Il n'est pas nécessaire qu'il corresponde à un ID d'onglet réel. La valeur par défaut est -1, ce qui signifie que la requête n'est pas liée à un onglet.

• topUrl

  chaîne facultatif

  Chrome 145+ browser.* depuis Chrome 148

  URL du frame de niveau supérieur associé (le cas échéant) pour la requête.

• type

  ResourceType

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

• url

  chaîne

  URL de la requête hypothétique.

UnsupportedRegexReason

Chrome 87+ browser.* depuis Chrome 148

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

Énumération

"syntaxError"
L'expression régulière est syntaxiquement incorrecte ou utilise des fonctionnalités non disponibles dans la syntaxe RE2.

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

UpdateRuleOptions

Chrome 87+ browser.* depuis Chrome 148

Propriétés

• addRules

  Rule[] facultatif

  Règles à ajouter.

• removeRuleIds

  number[] facultatif

  ID des règles à supprimer. Les ID non valides seront ignorés.

UpdateRulesetOptions

Chrome 87+ browser.* depuis Chrome 148

Propriétés

• disableRulesetIds

  string[] facultatif

  Ensemble d'ID correspondant à un Ruleset statique qui doit être désactivé.

• enableRulesetIds

  string[] facultatif

  Ensemble d'ID correspondant à un Ruleset statique qui doit être activé.

UpdateStaticRulesOptions

Chrome 111 ou version ultérieure browser.* depuis Chrome 148

Propriétés

• disableRuleIds

  number[] facultatif

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

• enableRuleIds

  number[] facultatif

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

• rulesetId

  chaîne

  ID correspondant à un Ruleset statique.

URLTransform

Propriétés

• fragment

  chaîne facultatif

  Nouveau fragment de la requête. Doit être vide (auquel cas le fragment existant est effacé) ou commencer par "#".

• hôte

  chaîne facultatif

  Nouvel hôte de 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 de la requête. Si ce champ est vide, le chemin d'accès existant est effacé.

• port

  chaîne facultatif

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

• requête

  chaîne facultatif

  Nouvelle requête pour la demande. Doit être vide (auquel cas la requête existante est effacée) ou commencer par "?".

• 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

"_dynamic"

GETMATCHEDRULES_QUOTA_INTERVAL

Intervalle de temps pendant lequel les appels MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules peuvent être effectués, spécifié en minutes. Les appels supplémentaires échoueront immédiatement et définiront runtime.lastError. Remarque : Les appels getMatchedRules associés à un geste de l'utilisateur ne sont pas soumis au quota.

Valeur

10

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89+ browser.* depuis Chrome 148

Nombre minimal de règles statiques garanti pour une extension dans ses ensembles de règles statiques activés. Toutes les règles au-delà de cette limite seront comptabilisées dans la limite globale de règles statiques.

Valeur

30000

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Nombre de fois que getMatchedRules peut être appelé sur une période 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+ browser.* depuis Chrome 148

Nombre maximal de Rulesets statiques qu'une extension peut activer à tout moment.

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 celles spécifiées dans le fichier de ressources de règles.

Valeur

1 000

MAX_NUMBER_OF_SESSION_RULES

Navigateur Chrome 120+ browser.* depuis Chrome 148

Nombre maximal de règles limitées à la session qu'une extension peut ajouter.

Valeur

5 000

MAX_NUMBER_OF_STATIC_RULESETS

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

Valeur

100

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Navigateur Chrome 120+ browser.* depuis Chrome 148

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

Valeur

5 000

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Navigateur Chrome 120+ browser.* depuis Chrome 148

Nombre maximal de règles "unsafe" limitées à la session qu'une extension peut ajouter.

Valeur

5 000

SESSION_RULESET_ID

Chrome 90+ browser.* depuis Chrome 148

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()

Chrome 89+ browser.* depuis Chrome 148

browser.declarativeNetRequest.getAvailableStaticRuleCount(): Promise<number>

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

Renvoie

• Promise<number>

  Chrome 91 et versions ultérieures browser.* depuis Chrome 148

getDisabledRuleIds()

Chrome 111 ou version ultérieure browser.* depuis Chrome 148

browser.declarativeNetRequest.getDisabledRuleIds(
  options: GetDisabledRuleIdsOptions,
): Promise<number[]>

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

Paramètres

• options

  GetDisabledRuleIdsOptions

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

Renvoie

• Promise<number[]>

  Promesse qui se résout avec une liste d'ID correspondant aux règles désactivées dans cet ensemble de règles.

getDynamicRules()

browser.declarativeNetRequest.getDynamicRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

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 browser.* depuis Chrome 148

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

Renvoie

• Promise<Rule[]>

  Chrome 91 et versions ultérieures browser.* depuis Chrome 148

  Promesse qui se résout avec l'ensemble de règles dynamiques. La promesse peut être rejetée en cas d'erreurs internes temporaires.

getEnabledRulesets()

browser.declarativeNetRequest.getEnabledRulesets(): Promise<string[]>

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

Renvoie

• Promise<string[]>

  Chrome 91 et versions ultérieures browser.* depuis Chrome 148

  Promesse qui se résout avec une liste d'ID, où chaque ID correspond à un Ruleset statique activé.

getMatchedRules()

browser.declarativeNetRequest.getMatchedRules(
  filter?: MatchedRulesFilter,
): Promise<RulesMatchedDetails>

Renvoie 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'tabId spécifié dans filter. Remarque : Les règles qui ne sont pas associées à un document actif et qui ont été mises en correspondance il y a plus de cinq minutes ne seront pas renvoyées.

Paramètres

• filtre

  MatchedRulesFilter facultatif

  Objet permettant de filtrer la liste des règles correspondantes.

Renvoie

• Promise<RulesMatchedDetails>

  Chrome 91 et versions ultérieures browser.* depuis Chrome 148

  Promesse qui se résout une fois que la liste des règles correspondantes a été récupérée. En cas d'erreur, la promesse sera rejetée. Cela peut se produire pour plusieurs raisons, par exemple si les autorisations sont insuffisantes ou si le quota est dépassé.

getSessionRules()

Chrome 90+ browser.* depuis Chrome 148

browser.declarativeNetRequest.getSessionRules(
  filter?: GetRulesFilter,
): Promise<Rule[]>

Renvoie l'ensemble actuel de règles de portée de 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 browser.* depuis Chrome 148

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

Renvoie

• Promise<Rule[]>

  Chrome 91 et versions ultérieures browser.* depuis Chrome 148

  Promesse qui se résout avec l'ensemble des règles limitées à la session.

isRegexSupported()

Chrome 87+ browser.* depuis Chrome 148

browser.declarativeNetRequest.isRegexSupported(
  regexOptions: RegexOptions,
): Promise<IsRegexSupportedResult>

Vérifie si l'expression régulière donnée sera acceptée en tant que condition de règle regexFilter.

Paramètres

• regexOptions

  RegexOptions

  Expression régulière à vérifier.

Renvoie

• Promise<IsRegexSupportedResult>

  Chrome 91 et versions ultérieures browser.* depuis Chrome 148

  Promesse qui se résout avec des détails indiquant si l'expression régulière est compatible et, si ce n'est pas le cas, la raison.

setExtensionActionOptions()

Chrome 88+ browser.* depuis Chrome 148

browser.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise<void>

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

Paramètres

• options

  ExtensionActionOptions

Renvoie

• Promise<void>

  Chrome 91 et versions ultérieures browser.* depuis Chrome 148

testMatchOutcome()

Chrome 103 et versions ultérieures browser.* depuis Chrome 148

browser.declarativeNetRequest.testMatchOutcome(
  request: TestMatchRequestDetails,
): Promise<TestMatchOutcomeResult>

Vérifie si l'une des règles declarativeNetRequest de l'extension correspond à une requête hypothétique. Remarque : Cette option n'est disponible que pour les extensions non empaquetées, car elle n'est destinée qu'à être utilisée pendant le développement de l'extension.

Paramètres

• request

  TestMatchRequestDetails

Renvoie

• Promise<TestMatchOutcomeResult>

  Promesse qui se résout avec les détails des règles correspondantes.

updateDynamicRules()

browser.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
): Promise<void>

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

• Cette mise à jour s'effectue 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 d'une mise à jour d'extension à l'autre.
• 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

• options

  UpdateRuleOptions

  Chrome 87+ browser.* depuis Chrome 148

Renvoie

• Promise<void>

  Chrome 91 et versions ultérieures browser.* depuis Chrome 148

  Promesse qui se résout une fois la mise à jour terminée. En cas d'erreur, la promesse sera rejetée et aucune modification ne sera apportée à l'ensemble de règles. Cela peut se produire pour plusieurs raisons, par exemple un format de règle non valide, un ID de règle en double, un nombre de règles maximal dépassé, des erreurs internes, etc.

updateEnabledRulesets()

browser.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
): Promise<void>

Met à jour l'ensemble des ensembles de règles statiques activés pour l'extension. Les ensembles de règles dont les ID sont listé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 des ensembles de règles statiques activés est conservé d'une session à l'autre, mais pas d'une mise à jour d'extension à l'autre. Autrement dit, la clé de fichier manifeste rule_resources détermine l'ensemble des ensembles de règles statiques activés à chaque mise à jour d'extension.

Paramètres

• options

  UpdateRulesetOptions

  Chrome 87+ browser.* depuis Chrome 148

Renvoie

• Promise<void>

  Chrome 91 et versions ultérieures browser.* depuis Chrome 148

  Promesse qui se résout une fois la mise à jour terminée. En cas d'erreur, la promesse sera rejetée et aucune modification ne sera apportée à l'ensemble des ensembles de règles activés. Cela peut se produire pour plusieurs raisons, par exemple des ID d'ensemble de règles non valides, un dépassement de la limite du nombre de règles ou des erreurs internes.

updateSessionRules()

Chrome 90+ browser.* depuis Chrome 148

browser.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
): Promise<void>

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

• Cette mise à jour s'effectue 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

• options

  UpdateRuleOptions

Renvoie

• Promise<void>

  Chrome 91 et versions ultérieures browser.* depuis Chrome 148

  Promesse qui se résout une fois la mise à jour terminée. En cas d'erreur, la promesse sera rejetée et aucune modification ne sera apportée à l'ensemble de règles. Cela peut se produire pour plusieurs raisons, par exemple un format de règle non valide, un ID de règle en double, un nombre de règles maximal dépassé, etc.

updateStaticRules()

Chrome 111 ou version ultérieure browser.* depuis Chrome 148

browser.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise<void>

Désactive et active des règles statiques individuelles dans un Ruleset. Les modifications apportées aux règles appartenant à un Ruleset désactivé prendront effet la prochaine fois qu'il sera activé.

Paramètres

• options

  UpdateStaticRulesOptions

Renvoie

• Promise<void>

  Promesse qui se résout une fois la mise à jour terminée. En cas d'erreur, la promesse sera rejetée et aucune modification ne sera apportée aux règles statiques activées.

Événements

onRuleMatchedDebug

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

Déclenché lorsqu'une règle correspond à une requête. Disponible uniquement pour les extensions non empaquetées avec l'autorisation "declarativeNetRequestFeedback", car elle est destinée à être utilisée uniquement à des fins de débogage.

Paramètres

• callback

  fonction

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

  (info: MatchedRuleInfoDebug) => void

  • info

    MatchedRuleInfoDebug