path: root/files/fr/mozilla/add-ons/webextensions/api/webrequest/onbeforerequest/index.html

---
title: webRequest.onBeforeRequest
slug: Mozilla/Add-ons/WebExtensions/API/webRequest/onBeforeRequest
tags:
  - API
  - Add-ons
  - Event
  - Extensions
  - Non-standard
  - Reference
  - WebExtensions
  - onBeforeRequest
  - webRequest
translation_of: Mozilla/Add-ons/WebExtensions/API/webRequest/onBeforeRequest
---
<div>{{AddonSidebar()}}</div>

<p>Cet événement est déclenché lorsqu'une demande est sur le point d'être faite et avant que les en-têtes ne soient disponibles. C'est un bon endroit pour écouter si vous voulez annuler ou rediriger la demande.</p>

<p>Pour annuler ou rediriger la requête, incluez d'abord <code>"blocking"</code> dans l'argument tableau <code>extraInfoSpec</code> pour <code>addListener()</code>. Ensuite, dans la fonction Listener, retournez un objet {{WebExtAPIRef("webRequest.BlockingResponse", "BlockingResponse")}}, en définissant la propriété appropriée :</p>

<ul>
 <li>pour annuler la demande, inclure une propriété <code>cancel</code> avec la valeur <code>true</code>.</li>
 <li>pour rediriger la requête, inclure une propriété <code>redirectUrl</code> avec la valeur fixée à l'URL vers laquelle vous voulez rediriger.</li>
</ul>

<p>Si une extension veut rediriger une URL publique (par exemple HTTPS) ver une <a href="/fr/Add-ons/WebExtensions/user_interface/Extension_pages">page d'extension</a>, de l'extension doit contenir une clé <a href="/fr/Add-ons/WebExtensions/manifest.json/web_accessible_resources">web_accessible_resources</a> qui liste l'URL de la page d'extension.</p>

<p>Lorsque plusieurs gestionnaires de blocage modifient une requête, une seule série de modifications prend effet. Les redirections et les annulations ont la même priorité. Ainsi, si vous avez annulé une requête, vous pouvez voir une autre requête avec la même  <code>requestId</code> à nouveau si un autre gestionnaire de blocage a redirigé la requête.</p>

<p>A partir de Firefox 52, au lieu de renvoyer <code>BlockingResponse</code>, l'auditeur peut renvoyer une  <code><a href="/fr/docs/Web/JavaScript/Reference/Objets_globaux/Promise">Promise</a></code> qui est résolue avec un <code>BlockingResponse</code>. Ceci permet à l'auditeur de traiter la demande de manière asynchrone.</p>

<p>Si vous utilisez le <code>"blocking"</code>, vous devez avoir la <a href="/fr/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">permission de l'API "webRequestBlocking"</a> dans votre manifest.json.</p>

<h2 id="Syntaxe">Syntaxe</h2>

<pre class="syntaxbox brush:js">browser.webRequest.onBeforeRequest.addListener(
  listener,             // function
  filter,               //  object
  extraInfoSpec         //  optional array of strings
)
browser.webRequest.onBeforeRequest.removeListener(listener)
browser.webRequest.onBeforeRequest.hasListener(listener)
</pre>

<p>Les événements ont trois fonctions :</p>

<dl>
 <dt><code>addListener(callback, filter, extraInfoSpec)</code></dt>
 <dd>Ajoute un auditeur à cet événement.</dd>
 <dt><code>removeListener(listener)</code></dt>
 <dd>Arrêtez d'écouter cet événement. L'argument de l'<code>écouteur</code> est l'écouteur à supprimer.</dd>
 <dt><code>hasListener(listener)</code></dt>
 <dd>Vérifiez si <code>l'écouteur</code> est inscrit à cet événement. Renvoie <code>true</code> s'il est à l'écoute, sinon <code>false</code>.</dd>
</dl>

<h2 id="Syntaxe_addListener">Syntaxe addListener</h2>

<h3 id="Paramètres">Paramètres</h3>

<dl>
 <dt><code>callback</code></dt>
 <dd>
 <p>Fonction qui sera appelée lorsque cet événement se produira. La fonction sera passée les arguments suivants :</p>

 <dl class="reference-values">
  <dt><code>details</code></dt>
  <dd><a href="#details"><code>object</code></a>. Détails sur la demande. Voir les <code><a href="#details">details</a></code> ci-dessous.</dd>
 </dl>

 <p>Les retours : {{WebExtAPIRef('webRequest.BlockingResponse')}}. Si <code>"blocking"</code>est spécifié dans le paramètre <code>extraInfoSpec</code>, l'auditeur d'événement doit retourner un objet <code>BlockingResponse</code>, et peut définir soit son <code>annulation</code>, soit ses propriétés  <code>redirectUrl</code>. A partir de Firefox 52, au lieu de renvoyer <code>BlockingResponse</code>,l'auditeur peut renvoyer une <code><a href="/fr/docs/Web/JavaScript/Reference/Objets_globaux/Promise">Promise</a></code> qui est résolue avec un <code>BlockingResponse</code>. Ceci permet à l'auditeur de traiter la demande de manière asynchrone.</p>
 </dd>
 <dt><code>filter</code></dt>
 <dd>{{WebExtAPIRef('webRequest.RequestFilter')}}. Un filtre qui restreint les événements qui seront envoyés à cet auditeur.</dd>
 <dt><code>extraInfoSpec</code>{{optional_inline}}</dt>
 <dd><code>array</code> de <code>string</code>. Options supplémentaires pour l'événement. Vous pouvez passer n'importe laquelle des valeurs suivantes <span class="im">:</span></dd>
 <dd>
 <ul>
  <li><code>"blocking"</code>: rendre la requête synchrone, de sorte que vous pouvez annuler ou rediriger la requête</li>
  <li><span class="im"><code>"requestBody"</code>: include <code>requestBody</code> dans l'objet <code>details</code> </span>transmis à l'auditeur</li>
 </ul>
 </dd>
</dl>

<h2 id="Objets_supplémentaires">Objets supplémentaires</h2>

<h3 id="détails">détails</h3>

<dl class="reference-values">
 <dt><code>documentUrl</code></dt>
 <dd><code>string</code>. URL du document dans lequel la ressource sera chargée. Par exemple, si la page web "https://example.com" contient une image ou un iframe, alors le <code>documentUrl</code> pour l'image ou l'iframe sera "https://example.com". Pour un document de niveau supérieur, <code>documentUrl</code> n'est pas défini.</dd>
 <dt><code>frameAncestors</code></dt>
 <dd><code>array</code>. Contient des informations pour chaque document dans la hiérarchie des cadres jusqu'au document de niveau supérieur. Le premier élément du tableau contient des informations sur le parent immédiat du document demandé, et le dernier élément contient des informations sur le document de niveau supérieur. Si la charge est réellement pour le document de niveau supérieur, alors ce tableau est vide.</dd>
 <dd>
 <dl class="reference-values">
  <dt><code>url</code></dt>
  <dd><code>string</code>. URL à partir de laquelle le document a été chargé.</dd>
  <dt><code>frameId</code></dt>
  <dd><code>integer</code>. Le <code>frameId</code> du document. <code>details.frameAncestors[0].frameId</code> est le même que <code>details.parentFrameId</code>.</dd>
 </dl>
 </dd>
 <dt><code>frameId</code></dt>
 <dd><code>integer</code>. Zéro si la requête se produit dans le cadre principal ; une valeur positive est l'ID d'une sous-trame dans laquelle la requête se produit. Si le document d'un (sous-)cadre est chargé (<code>type</code> is <code>main_frame</code> or <code>sub_frame</code>), <code>frameId</code> indique l'ID de ce cadre et non l'ID du cadre extérieur. Les ID de trame sont uniques dans un onglet.</dd>
 <dt><code>method</code></dt>
 <dd><code>string</code>. Méthode HTTP standard : par exemple, "GET" ou "POST".</dd>
 <dt><code>originUrl</code></dt>
 <dd>
 <p><code>string</code>. URL de la ressource qui a déclenché la requête. Par exemple, si "https://example.com" contient un lien, et que l'utilisateur clique sur le lien, alors <code>originUrl</code> de la requête résultante est "https://example.com".</p>

 <p>L'<code>originUrl</code> est souvent mais pas toujours la même chose que <code>documentUrl</code>.Par exemple, si une page contient une iframe, et que l'iframe contient un lien qui charge un nouveau document dans l'iframe, alors le <code>documentUrl</code> pour la requête résultante sera le document parent de l'iframe, mais l'<code>originUrl</code> sera l'URL du document dans l'iframe qui contenait le lien.</p>
 </dd>
 <dt><code>parentFrameId</code></dt>
 <dd><code>integer</code>. de la trame qui contient la trame qui a envoyé la requête. Réglé à -1 s'il n'existe pas de l'iframe parent.</dd>
 <dt><code>proxyInfo</code></dt>
 <dd>
 <p><code>object</code>. Cette propriété n'est présente que si la demande est proxied. Il contient les propriétés suivantes :</p>

 <dl>
  <dt><code>host</code></dt>
  <dd><code>string</code>. Le nom d'hôte du serveur proxy.</dd>
  <dt><code>port</code></dt>
  <dd><code>integer</code>. Le numéro de port du serveur proxy.</dd>
  <dt><code>type</code></dt>
  <dd>
  <p><code>string</code>. Le type de serveur proxy. L'un des :</p>

  <ul>
   <li>"http": proxy HTTP (ou SSL CONNECT pour HTTPS)</li>
   <li>"https": proxy HTTP sur connexion TLS vers proxy</li>
   <li>"socks": SOCKS v5 proxy</li>
   <li>"socks4": SOCKS v4 proxy</li>
   <li>"direct": pas de proxy</li>
   <li>"unknown": proxy inconnu</li>
  </ul>
  </dd>
  <dt><code>username</code></dt>
  <dd><code>string</code>. Nom d'utilisateur pour le service proxy.</dd>
  <dt><code>proxyDNS</code></dt>
  <dd><code>boolean</code>. Vrai si le proxy exécutera une résolution de nom de domaine basée sur le nom d'hôte fourni, ce qui signifie que le client ne doit pas faire sa propre recherche DNS.</dd>
  <dt><code>failoverTimeout</code></dt>
  <dd><code>integer</code>. Délai d'attente de basculement en secondes. Si la connexion par proxy échoue, le proxy ne sera pas utilisé à nouveau pendant cette période.</dd>
 </dl>
 </dd>
 <dt><code>requestBody</code>{{optional_inline}}</dt>
 <dd><code>object</code>. Contient les données du corps de la requête HTTP. Seulement si <code>extraInfoSpec</code> contient <code>"requestBody"</code>.</dd>
 <dd>
 <dl class="reference-values">
  <dt><code>error</code>{{optional_inline}}</dt>
  <dd><code>string</code>. Ce paramètre est défini si des erreurs ont été rencontrées lors de l'obtention des données du corps de la demande.</dd>
  <dt><code>formData</code>{{optional_inline}}</dt>
  <dd><code>object</code>. Cet objet est présent si la méthode de requête est POST et que le corps est une séquence de paires clé-valeur codées en UTF-8 sous la forme "multipart/form-data" ou "application/x-www-form-urlencoded".</dd>
  <dd>Il s'agit d'un dictionnaire dans lequel chaque clé contient la liste de toutes les valeurs de cette clé. Par exemple: <code>{'key': ['value1', 'value2']}</code>. Si les données sont d'un autre type de support, ou si elles sont malformées, l'objet n'est pas présent.</dd>
  <dt><code>raw</code>{{optional_inline}}</dt>
  <dd><code>array</code> of <code>{{WebExtAPIRef('webRequest.UploadData')}}</code>. Si la méthode de requête est PUT ou POST, et que le corps n'est pas déjà analysé dans <code>formData</code>, alors ce tableau contient les éléments de corps de requête non analysés.</dd>
 </dl>
 </dd>
 <dt><code>requestId</code></dt>
 <dd><code>string</code>. L'ID de la demande. Les ID de requête sont uniques au sein d'une session de navigateur, de sorte que vous pouvez les utiliser pour relier différents événements associés à la même requête.</dd>
 <dt><code>tabId</code></dt>
 <dd><code>integer</code>. ID de l'onglet dans lequel la demande a lieu. Définir à -1 si la requête n'est pas liée à un onglet.</dd>
 <dt><code>timeStamp</code></dt>
 <dd><code>number</code>. L'heure à laquelle cet événement s'est déclenché, en <a href="https://en.wikipedia.org/wiki/Unix_time">millisecondes depuis l'époque</a>.</dd>
 <dt><code>type</code></dt>
 <dd>{{WebExtAPIRef('webRequest.ResourceType')}}. Le type de ressource demandée : par exemple, "image", "script", "stylesheet".</dd>
 <dt><code>url</code></dt>
 <dd><code>string</code>. Cible de la demande.</dd>
</dl>

<h2 id="Compatibilité_du_navigateur">Compatibilité du navigateur</h2>

<p>{{Compat("webextensions.api.webRequest.onBeforeRequest", 10)}}</p>

<h3 id="Ordre_de_résolution_DNS_lorsque_BlockingResponse_est_utilisé">Ordre de résolution DNS lorsque BlockingResponse est utilisé</h3>

<p>En ce qui concerne la résolution DNS lorsque BlockingResponse est utilisé avec  OnBeforeRequest : Dans le canal HTTP, avec réponse de blocage se produit avant la résolution DNS et avant la connexion spéculative. Pour les autres canaux, une connexion spéculative peut provoquer des requêtes DNS avant onBeforeRequest. Cet ordre n'est pas quelque chose sur quoi un développeur d'extension devrait se fier, car il peut varier d'un navigateur à l'autre, et encore moins d'une version de navigateur à l'autre, et encore moins d'un canal de requête à l'autre. Référez-vous <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=1466099">à la clarification du problème de BugZilla fournie par les développeurs Mozilla sur la commande de la résolution DNS</a></p>

<h2 id="Exemples">Exemples</h2>

<p>Ce code enregistre l'URL de chaque ressource demandée qui correspond au modèle  <a href="/fr/Add-ons/WebExtensions/Match_patterns#&lt;all_urls>">&lt;all_urls&gt;</a> :</p>

<pre class="brush: js">function logURL(requestDetails) {
  console.log("Loading: " + requestDetails.url);
}

browser.webRequest.onBeforeRequest.addListener(
  logURL,
  {urls: ["&lt;all_urls&gt;"]}
);</pre>

<p>Ce code annule les demandes d'images qui sont faites aux URLs sous "https://mdn.mozillademos.org/" (pour voir l'effet, visitez n'importe quelle page de MDN qui contient des images, comme <a href="/fr/docs/Mozilla/Firefox/Developer_Edition">Firefox Developer Edition</a>):</p>

<pre class="brush: js">// match pattern for the URLs to redirect
var pattern = "https://mdn.mozillademos.org/*";

// cancel function returns an object
// which contains a property `cancel` set to `true`
function cancel(requestDetails) {
  console.log("Canceling: " + requestDetails.url);
  return {cancel: true};
}

// add the listener,
// passing the filter argument and "blocking"
browser.webRequest.onBeforeRequest.addListener(
  cancel,
  {urls: [pattern], types: ["image"]},
  ["blocking"]
);
</pre>

<p>Ce code remplace, par redirection, toutes les demandes de réseau pour des images qui sont faites à des URLs sous "https://mdn.mozillademos.org/" (pour voir l'effet, visitez n'importe quelle page de MDN qui contient des images, comme <a href="/fr/docs/Mozilla/Firefox/Developer_Edition">Firefox Developer Edition</a>) :</p>

<pre class="brush: js">// match pattern for the URLs to redirect
var pattern = "https://mdn.mozillademos.org/*";

// redirect function
// returns an object with a property `redirectURL`
// set to the new URL
function redirect(requestDetails) {
  console.log("Redirecting: " + requestDetails.url);
  return {
    redirectUrl: "https://38.media.tumblr.com/tumblr_ldbj01lZiP1qe0eclo1_500.gif"
  };
}

// add the listener,
// passing the filter argument and "blocking"
browser.webRequest.onBeforeRequest.addListener(
  redirect,
  {urls:[pattern], types:["image"]},
  ["blocking"]
);</pre>

<p>Ce code est exactement comme l'exemple précédent, sauf que l'auditeur traite la requête de manière asynchrone. Il renvoie une <code><a href="/fr/docs/Web/JavaScript/Reference/Objets_globaux/Promise">Promise</a></code> qui définit une minuterie et se résout avec l'URL de redirection lorsque la minuterie expire :</p>

<pre class="brush: js">// match pattern for the URLs to redirect
var pattern = "https://mdn.mozillademos.org/*";

// URL we will redirect to
var redirectUrl = "https://38.media.tumblr.com/tumblr_ldbj01lZiP1qe0eclo1_500.gif";

// redirect function returns a Promise
// which is resolved with the redirect URL when a timer expires
function redirectAsync(requestDetails) {
  console.log("Redirecting async: " + requestDetails.url);
  return new Promise((resolve, reject) =&gt; {
    window.setTimeout(() =&gt; {
      resolve({redirectUrl});
    }, 2000);
  });
}

// add the listener,
// passing the filter argument and "blocking"
browser.webRequest.onBeforeRequest.addListener(
  redirectAsync,
  {urls: [pattern], types: ["image"]},
  ["blocking"]
);</pre>

<p>{{WebExtExamples}}</p>

<div class="note"><strong>Remerciements :</strong>

<p>Cette API est basée sur l'API Chromium <a href="https://developer.chrome.com/extensions/webRequest"><code>chrome.webRequest</code></a>. Cette documentation est dérivée de <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/web_request.json"><code>web_request.json</code></a> dans le code Chromium.</p>

<p>Les données de compatibilité relatives à Microsoft Edge sont fournies par Microsoft Corporation et incluses ici sous la licence Creative Commons Attribution 3.0 pour les États-Unis.</p>
</div>

<div class="hidden">
<pre>// Copyright 2015 The Chromium Authors. All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
//    * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//    * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//    * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</pre>
</div>