chrome.declarativeNetRequest (original) (raw)

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" offrent les mêmes fonctionnalité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 lors de l'installation, mais fournit un accès implicite aux règles allow, allowAllRequests et block. Utilisez cette option si possible pour éviter de devoir demander un accès complet aux organisateurs.

"declarativeNetRequestFeedback"

Active les fonctionnalités de débogage pour les extensions décompressées, en particulier getMatchedRules() et onRuleMatchedDebug.

"declarativeNetRequestWithHostAccess"

Aucun avertissement d'autorisation n'est affiché lors de l'installation, mais vous devez demander les 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 et versions ultérieures

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 :

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

Dynamique

Elles persistent d'une session de navigation à l'autre et lors des mises à niveau d'extensions, et sont gérées à 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

Empaquetés, installés 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.

Il n'existe qu'un seul type de règles pour chacun de ces ensembles. 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 dans la section Exemples de code.

Ensembles de règles statiques

Contrairement aux règles dynamiques et de session, les règles statiques sont regroupé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 non compressée. Les erreurs et les avertissements concernant les règles statiques non valides ne s'affichent que pour les extensions non compressées. Les règles statiques non valides dans les extensions compressées sont ignorées.

Examen accéléré

Les modifications apportées aux ensembles de règles statiques peuvent être éligibles à un examen accéléré. Consultez Examen accéléré des modifications éligibles.

Activer et désactiver les règles et 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. Aucun des deux n'est conservé 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 les règles statiques, appelez updateStaticRules(). Cette méthode accepte 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 de règles statiques désactivées est limité à 5 000.

Pour activer ou désactiver les ensembles de règles statiques, appelez updateEnabledRulesets(). Cette méthode accepte un objet UpdateRulesetOptions, qui contient des tableaux d'ID de 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 le type de règle, elle 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 "abc" comme sous-chaîne.

{
  "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 autorise 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.comhttps://example.com/abcd https://ab.com
"abc*d" https://abcd.comhttps://example.com/abcxyzd https://abc.com
"| a.example.com" https://a.example.com/https://b.a.example.com/xyzhttps://a.example.company
"|https*" https://example.com http://example.com/http://https.com
"example*^123|" https://example.com/123http://abc.com/example?123 https://example.com/1234https://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 efficaces

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

Envisagez d'utiliser :

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 passant du schéma HTTP à HTTPS) avec une règle correspondante.

Pour chaque extension, le navigateur détermine une liste de règles correspondantes. 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 sélectionne au maximum un candidat par requête. Chrome trouve une règle correspondante en classant toutes les règles correspondantes par ordre de 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'a 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 celle de l'extension installée le plus récemment.

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 crée la liste des modifications à effectuer en recherchant toutes les règles modifyHeaders correspondantes. Comme auparavant, seules les règles dont la priorité est supérieure à celle des règles allow ou allowAllRequests correspondantes sont incluses.

Chrome applique ces règles 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. À noter que même pour les extensions :

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 inutiles par une règle allow ou allowAllRequests correspondante (comme dans les é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 a atteint cette étape, 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êtes 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 envoyé 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 redirigée. 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 dont l'action est block, allow, allowAllRequests ou upgradeScheme. Ces règles sont soumises à un quota plus élevé pour les règles dynamiques.

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 lorsque vous utilisez 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. Ce dernier est appelé MAX_NUMBER_OF_ENABLED_STATIC_RULESETS. Collectivement, ces ensembles de règles garantissent au moins 30 000 règles. C'est ce qu'on appelle le GUARANTEED_MINIMUM_STATIC_RULES.

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

Règles relatives aux sessions

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, le nombre combiné de règles dynamiques et de session était limité à 5 000.

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 de règles dynamiques sûres est portée à 30 000, et est exposée sous la forme MAX_NUMBER_OF_DYNAMIC_RULES. Toute règle non sécurisée ajoutée dans la limite de 5 000 sera également comptabilisée dans cette limite.

Avant Chrome 120, la limite combinée des règles dynamiques et de session était de 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. On l'appelle MAX_NUMBER_OF_REGEX_RULES.

De plus, chaque règle doit être inférieure à 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 à celui ci-dessous 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 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'affecte pas les réponses générées par le service worker ni celles récupérées à partir de CacheStorage, mais il affecte 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. Cette opération déclenche une erreur. Cela est valable même si la ressource Web accessible spécifiée appartient à l'extension de redirection. Pour déclarer des ressources pour declarativeNetRequest, utilisez le tableau "web_accessible_resources" du fichier manifeste.

L'opération d'ajout n'est acceptée que pour 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).

Lorsque vous ajoutez un en-tête à une requête ou une 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 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 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 utiliser cette méthode 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 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 illustrent la façon dont Chrome hiérarchise les règles dans une extension. Lorsque vous les examinez, vous pouvez ouvrir les règles de priorisation dans une fenêtre distincte.

Clé "priority"

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éfinie par le développeur), "action" et "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 : celles dont les ID sont 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 les 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 ayant 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'extension /a.jpg est résolu en chrome-extension://EXTENSION_ID/a.jpg, où EXTENSION_ID correspond à 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"]
  }
}

L'exemple suivant utilise la clé "transform" pour rediriger vers un sous-domaine d'example.com. Il utilise un ancrage 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 les utilisateurs de 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 redirigée 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"
    ]
  }
}

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 demande est propriétaire ou tierce par rapport au frame dans lequel elle a été générée. Une requête est dite "first party" si elle possède le même domaine (eTLD+1) que le frame dans lequel elle a été générée.

Énumération

"firstParty"
La requête réseau est propriétaire du frame dans lequel elle a été générée.

"thirdParty"
La requête réseau est tierce par rapport au frame dans lequel elle a été lancée.

ExtensionActionOptions

Chrome 88 et versions ultérieures

Propriétés

GetDisabledRuleIdsOptions

Chrome 111 et versions ultérieures

Propriétés

GetRulesFilter

Chrome 111 et versions ultérieures

Propriétés

Chrome 128 et versions ultérieures

Propriétés

Chrome 86 et versions ultérieures

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 et versions ultérieures

Propriétés

MatchedRule

Propriétés

MatchedRuleInfo

Propriétés

MatchedRuleInfoDebug

Propriétés

MatchedRulesFilter

Propriétés

Chrome 86 et versions ultérieures

Propriétés

QueryKeyValue

Propriétés

QueryTransform

Propriétés

Redirect

Propriétés

RegexOptions

Chrome 87 et versions ultérieures

Propriétés

RequestDetails

Propriétés

RequestMethod

Chrome 91 et versions ultérieures

Cela décrit 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

Cette valeur 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

RuleAction

Propriétés

RuleActionType

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

É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 lui correspond.

"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 à partir de la requête réseau.

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

RuleCondition

Propriétés

RuleConditionKeys

É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

RulesMatchedDetails

Propriétés

TabActionCountUpdate

Chrome 89 et versions ultérieures

Propriétés

TestMatchOutcomeResult

Chrome 103 et versions ultérieures

Propriétés

TestMatchRequestDetails

Chrome 103 et versions ultérieures

Propriétés

UnsupportedRegexReason

Chrome 87 et versions ultérieures

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 incorrecte au niveau de la syntaxe 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 et versions ultérieures

Propriétés

UpdateRulesetOptions

Chrome 87 et versions ultérieures

Propriétés

UpdateStaticRulesOptions

Chrome 111 et versions ultérieures

Propriétés

URLTransform

Propriétés

Propriétés

DYNAMIC_RULESET_ID

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

GETMATCHEDRULES_QUOTA_INTERVAL

Intervalle de temps (en minutes) pendant lequel les appels MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL getMatchedRules peuvent être effectués. Les appels supplémentaires échoueront immédiatement et définiront runtime.lastError. Remarque : Les appels getMatchedRules associés à un geste de l'utilisateur sont exemptés du quota.

GUARANTEED_MINIMUM_STATIC_RULES

Chrome 89 et versions ultérieures

Nombre minimal de règles statiques garanties 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 des règles statiques.

MAX_GETMATCHEDRULES_CALLS_PER_INTERVAL

Nombre de fois que getMatchedRules peut être appelé au cours d'une période de GETMATCHEDRULES_QUOTA_INTERVAL.

MAX_NUMBER_OF_DYNAMIC_RULES

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

MAX_NUMBER_OF_ENABLED_STATIC_RULESETS

Chrome 94 et versions ultérieures

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

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

MAX_NUMBER_OF_SESSION_RULES

Chrome 120 et versions ultérieures

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

MAX_NUMBER_OF_STATIC_RULESETS

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

MAX_NUMBER_OF_UNSAFE_DYNAMIC_RULES

Chrome 120 et versions ultérieures

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

MAX_NUMBER_OF_UNSAFE_SESSION_RULES

Chrome 120 et versions ultérieures

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

SESSION_RULESET_ID

Chrome 90 et versions ultérieures

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

Méthodes

getAvailableStaticRuleCount()

Chrome 89 et versions ultérieures

chrome.declarativeNetRequest.getAvailableStaticRuleCount(): Promise

Renvoie le nombre de règles statiques qu'une extension peut activer avant d'atteindre la limite globale de règles statiques.

Renvoie

getDisabledRuleIds()

Chrome 111 et versions ultérieures

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

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

Paramètres

Renvoie

getDynamicRules()

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

Renvoie

getEnabledRulesets()

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

Renvoie les ID de l'ensemble actuel de règles statiques activées.

Renvoie

getMatchedRules()

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

Paramètres

Renvoie

getSessionRules()

Chrome 90 et versions ultérieures

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

Renvoie

isRegexSupported()

Chrome 87 et versions ultérieures

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

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

Paramètres

Renvoie

setExtensionActionOptions()

Chrome 88 et versions ultérieures

chrome.declarativeNetRequest.setExtensionActionOptions(
  options: ExtensionActionOptions,
): Promise

Configure si le nombre d'actions pour les onglets doit être affiché sous forme de texte du badge de l'action d'extension et fournit un moyen d'incrémenter ce nombre d'actions.

Paramètres

Renvoie

testMatchOutcome()

Chrome 103 et versions ultérieures

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

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

Paramètres

Renvoie

updateDynamicRules()

chrome.declarativeNetRequest.updateDynamicRules(
  options: UpdateRuleOptions,
): Promise

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 fournies dans options.addRules sont ajoutées. Remarques :

Paramètres

Renvoie

updateEnabledRulesets()

chrome.declarativeNetRequest.updateEnabledRulesets(
  options: UpdateRulesetOptions,
): Promise

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 ceux 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. En d'autres termes, la clé de fichier manifeste rule_resources déterminera l'ensemble des ensembles de règles statiques activés à chaque mise à jour d'extension.

Paramètres

Renvoie

updateSessionRules()

Chrome 90 et versions ultérieures

chrome.declarativeNetRequest.updateSessionRules(
  options: UpdateRuleOptions,
): Promise

Modifie l'ensemble actuel de règles de portée 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 fournies dans options.addRules sont ajoutées. Remarques :

Paramètres

Renvoie

updateStaticRules()

Chrome 111 et versions ultérieures

chrome.declarativeNetRequest.updateStaticRules(
  options: UpdateStaticRulesOptions,
): Promise

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

Renvoie

Événements

onRuleMatchedDebug

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

Déclenché lorsqu'une règle correspond à une requête. Cette option n'est disponible que pour les extensions décompressées disposant de l'autorisation "declarativeNetRequestFeedback", car elle est destinée à être utilisée à des fins de débogage uniquement.

Paramètres