diff options
Diffstat (limited to 'files/fr/mozilla/add-ons/webextensions/api/webrequest/onbeforesendheaders/index.md')
| -rw-r--r-- | files/fr/mozilla/add-ons/webextensions/api/webrequest/onbeforesendheaders/index.md | 276 |
1 files changed, 132 insertions, 144 deletions
diff --git a/files/fr/mozilla/add-ons/webextensions/api/webrequest/onbeforesendheaders/index.md b/files/fr/mozilla/add-ons/webextensions/api/webrequest/onbeforesendheaders/index.md index e5c2fc28b5..40b32f8165 100644 --- a/files/fr/mozilla/add-ons/webextensions/api/webrequest/onbeforesendheaders/index.md +++ b/files/fr/mozilla/add-ons/webextensions/api/webrequest/onbeforesendheaders/index.md @@ -13,153 +13,144 @@ tags: - webRequest translation_of: Mozilla/Add-ons/WebExtensions/API/webRequest/onBeforeSendHeaders --- -<div>{{AddonSidebar()}}</div> +{{AddonSidebar()}} -<p>Cet événement est déclenché avant l'envoi de données HTTP, mais après que tous les en-têtes HTTP soient disponibles. C'est un bon endroit pour écouter si vous voulez modifier les en-têtes de requête HTTP.</p> +Cet événement est déclenché avant l'envoi de données HTTP, mais après que tous les en-têtes HTTP soient disponibles. C'est un bon endroit pour écouter si vous voulez modifier les en-têtes de requête HTTP. -<p>Pour que les en-têtes de requête soient passés dans l'écouteur avec le reste des données de requête, passez <code>"requestHeaders"</code> dans un tableau <code>extraInfoSpec</code>.</p> +Pour que les en-têtes de requête soient passés dans l'écouteur avec le reste des données de requête, passez `"requestHeaders"` dans un tableau `extraInfoSpec`. -<p>Pour modifier les en-têtes de façon synchrone : passez <code>"blocking"</code> dans <code>extraInfoSpec</code>, puis dans votre événement écouté, retournez un <a href="/fr/Add-ons/WebExtensions/API/webRequest/BlockingResponse" title='An object of this type is returned by event listeners that have set "blocking" in their extraInfoSpec argument.'><code>BlockingResponse</code></a> avec une propriété nommée <code>requestHeaders</code>, dont la valeur est l'ensemble des en-têtes de requête à envoyer.</p> +Pour modifier les en-têtes de façon synchrone : passez `"blocking"` dans `extraInfoSpec`, puis dans votre événement écouté, retournez un [`BlockingResponse`](/fr/Add-ons/WebExtensions/API/webRequest/BlockingResponse 'An object of this type is returned by event listeners that have set "blocking" in their extraInfoSpec argument.') avec une propriété nommée `requestHeaders`, dont la valeur est l'ensemble des en-têtes de requête à envoyer. -<p>Pour modifier les en-têtes de façon asynchrone : passez <code>"blocking"</code> dans <code>extraInfoSpec</code>, puis dans votre event listener, retournez une <code><a href="/fr/docs/Web/JavaScript/Reference/Objets_globaux/Promise">Promise</a></code> qui est résolue avec une <code>BlockingResponse</code>.</p> +Pour modifier les en-têtes de façon asynchrone : passez `"blocking"` dans `extraInfoSpec`, puis dans votre event listener, retournez une [`Promise`](/fr/docs/Web/JavaScript/Reference/Objets_globaux/Promise) qui est résolue avec une `BlockingResponse`. -<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> +Si vous utilisez le `"blocking"`, vous devez avoir la ["permission de l'API "webRequestBlocking"](/fr/Add-ons/WebExtensions/manifest.json/permissions#API_permissions) dans votre manifest.json. -<p>Il est possible d'étendre le conflit ici. Si deux extensions écoutent <code>onBeforeSendHeaders</code> pour la même requête, le deuxième auditeur verra les modifications apportées par le premier auditeur et pourra annuler les modifications apportées par le premier auditeur. Par exemple, si le premier auditeur ajoute un en-tête <code>Cookie</code>, et que le deuxième auditeur supprime tous les en-têtes <code>Cookie</code>, les modifications apportées par le premier auditeur seront perdues. Si vous voulez voir les en-têtes qui sont effectivement envoyés, sans risque qu'une autre extension les modifie par la suite, utilisez {{WebExtAPIRef("webRequest.onSendHeaders", "onSendHeaders")}}, bien que vous ne puissiez pas modifier les en-têtes sur cet événement.</p> +Il est possible d'étendre le conflit ici. Si deux extensions écoutent `onBeforeSendHeaders` pour la même requête, le deuxième auditeur verra les modifications apportées par le premier auditeur et pourra annuler les modifications apportées par le premier auditeur. Par exemple, si le premier auditeur ajoute un en-tête `Cookie`, et que le deuxième auditeur supprime tous les en-têtes `Cookie`, les modifications apportées par le premier auditeur seront perdues. Si vous voulez voir les en-têtes qui sont effectivement envoyés, sans risque qu'une autre extension les modifie par la suite, utilisez {{WebExtAPIRef("webRequest.onSendHeaders", "onSendHeaders")}}, bien que vous ne puissiez pas modifier les en-têtes sur cet événement. -<p>Tous les en-têtes réellement envoyés ne sont pas toujours inclus dans <code>requestHeaders</code>. En particulier, les en-têtes liés à la mise en cache (par exemple, <code>Cache-Control</code>, <code>If-Modified-Since</code>, <code>If-None-Match</code>) ne sont jamais envoyés. De plus, le comportement peut différer d'un navigateur à l'autre.</p> +Tous les en-têtes réellement envoyés ne sont pas toujours inclus dans `requestHeaders`. En particulier, les en-têtes liés à la mise en cache (par exemple, `Cache-Control`, `If-Modified-Since`, `If-None-Match`) ne sont jamais envoyés. De plus, le comportement peut différer d'un navigateur à l'autre. -<p>Selon la spécification, les noms d'en-tête sont insensibles à la casse. Cela signifie que pour être sûr de faire correspondre un en-tête particulier, l'auditeur devrait minuscules le nom avant de le comparer :</p> +Selon la spécification, les noms d'en-tête sont insensibles à la casse. Cela signifie que pour être sûr de faire correspondre un en-tête particulier, l'auditeur devrait minuscules le nom avant de le comparer : -<pre class="brush: js">for (let header of e.requestHeaders) { +```js +for (let header of e.requestHeaders) { if (header.name.toLowerCase() === desiredHeader) { // process header } -}</pre> +} +``` -<p>Le navigateur conserve la casse originale du nom de l'en-tête tel qu'il a été généré par le navigateur. Si l'auditeur de l'extension change la casse, ce changement ne sera pas conservé.</p> +Le navigateur conserve la casse originale du nom de l'en-tête tel qu'il a été généré par le navigateur. Si l'auditeur de l'extension change la casse, ce changement ne sera pas conservé. -<h2 id="Syntaxe">Syntaxe</h2> +## Syntaxe -<pre class="brush: js">browser.webRequest.onBeforeSendHeaders.addListener( +```js +browser.webRequest.onBeforeSendHeaders.addListener( listener, // function filter, // object extraInfoSpec // optional array of strings ) browser.webRequest.onBeforeSendHeaders.removeListener(listener) browser.webRequest.onBeforeSendHeaders.hasListener(listener) -</pre> - -<p>Les événements ont trois fonctions :</p> - -<dl> - <dt><code>addListener(callback, filter, extraInfoSpec)</code></dt> - <dd>Ajouter un auditeur à cet événement.</dd> - <dt><code>removeListener(listener)</code></dt> - <dd>Arrêtez d'écouter cet événement. L'argument <code>listener</code> est l'auditeur à supprimer.</dd> - <dt><code>hasListener(listener)</code></dt> - <dd>Vérifiez si <code>listener</code> est enregistré à cet événement. Retourne <code>true</code> s'il est écouté, 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> - <dt><code>details</code></dt> - <dd><a href="#details"><code>object</code></a>. Détails de la demande. Ceci inclura les en-têtes de demande si vous avez inclus <code>"requestHeaders"</code> dans <code>extraInfoSpec</code>.</dd> - </dl> - - <p>Retourne : {{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 sa propriété <code>requestHeaders</code>.</p> - </dd> - <dt><code>filter</code></dt> - <dd>{{WebExtAPIRef('webRequest.RequestFilter')}}. Un ensemble de filtres qui restreint les événements qui seront envoyés à cet auditeur.</dd> - <dt><code>extraInfoSpec</code>{{optional_inline}}</dt> - <dd><p><code>array</code> de <code>string</code>. Options supplémentaires pour l'événement. Vous pouvez passer n'importe laquelle des valeurs suivantes :</p> - <ul> - <li><code>"blocking"</code>: rendre la requête synchrone, ce qui vous permet de modifier les en-têtes de requête</li> - <li><code>"requestHeaders"</code>: inclure les en-têtes de requête dans l'objet <code>details</code> transmis à l'auditeur</li> - </ul> - </dd> -</dl> - -<h2 id="Objets_supplémentaires">Objets supplémentaires</h2> - -<h3 id="détails">détails</h3> - -<dl> - <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>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>requestHeaders</code>{{optional_inline}}</dt> - <dd>{{WebExtAPIRef('webRequest.HttpHeaders')}}. Les en-têtes de réponse HTTP qui ont été reçus avec cette réponse.</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.onBeforeSendHeaders", 10)}}</p> - -<h2 id="Exemples">Exemples</h2> - -<p>Ce code modifie l'en-tête "User-Agent" pour que le navigateur s'identifie comme étant Opera 12.16, mais uniquement lors de la visite des pages sous "https://httpbin.org/".</p> - -<pre class="brush: js">"use strict"; +``` + +Les événements ont trois fonctions : + +- `addListener(callback, filter, extraInfoSpec)` + - : Ajouter un auditeur à cet événement. +- `removeListener(listener)` + - : Arrêtez d'écouter cet événement. L'argument `listener` est l'auditeur à supprimer. +- `hasListener(listener)` + - : Vérifiez si `listener` est enregistré à cet événement. Retourne `true` s'il est écouté, sinon `false`. + +## Syntaxe addListener + +### Paramètres + +- `callback` + + - : Fonction qui sera appelée lorsque cet événement se produira. La fonction sera passée les arguments suivants : + + - `details` + - : [`object`](#details). Détails de la demande. Ceci inclura les en-têtes de demande si vous avez inclus `"requestHeaders"` dans `extraInfoSpec`. + + Retourne : {{WebExtAPIRef('webRequest.BlockingResponse')}}. si `"blocking"` est spécifié dans le paramètre `extraInfoSpec`, l'auditeur d'événement doit retourner un objet `BlockingResponse`, et peut définir sa propriété `requestHeaders`. + +- `filter` + - : {{WebExtAPIRef('webRequest.RequestFilter')}}. Un ensemble de filtres qui restreint les événements qui seront envoyés à cet auditeur. +- `extraInfoSpec`{{optional_inline}} + + - : `array` de `string`. Options supplémentaires pour l'événement. Vous pouvez passer n'importe laquelle des valeurs suivantes : + + - `"blocking"`: rendre la requête synchrone, ce qui vous permet de modifier les en-têtes de requête + - `"requestHeaders"`: inclure les en-têtes de requête dans l'objet `details` transmis à l'auditeur + +## Objets supplémentaires + +### détails + +- `documentUrl` + - : `string`. 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 `documentUrl` pour l'image ou l'iframe sera "https\://example.com". Pour un document de niveau supérieur, `documentUrl` n'est pas défini. +- `frameId` + - : `integer`. 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é (`type` is `main_frame` or `sub_frame`), `frameId` indique l'ID de ce cadre et non l'ID du cadre extérieur. Les ID de trame sont uniques dans un onglet. +- `method` + - : `string`. Méthode HTTP standard : par exemple, "GET" ou "POST". +- `originUrl` + + - : `string`. 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 `originUrl` de la requête résultante est "https\://example.com". + + L'`originUrl` est souvent mais pas toujours la même chose que `documentUrl`.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 `documentUrl` pour la requête résultante sera le document parent de l'iframe, mais l'`originUrl` sera l'URL du document dans l'iframe qui contenait le lien. + +- `parentFrameId` + - : `integer`. 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. +- `proxyInfo` + + - : `object`. Cette propriété n'est présente que si la demande est proxied. Il contient les propriétés suivantes : + + - `host` + - : `string`. Le nom d'hôte du serveur proxy. + - `port` + - : `integer`. Le numéro de port du serveur proxy. + - `type` + + - : `string`. Le type de serveur proxy. L'un des : + + - "http": proxy HTTP (ou SSL CONNECT pour HTTPS) + - "https": proxy HTTP sur connexion TLS vers proxy + - "socks": SOCKS v5 proxy + - "socks4": SOCKS v4 proxy + - "direct": pas de proxy + - "unknown": proxy inconnu + + - `username` + - : `string`. Nom d'utilisateur pour le service proxy. + - `proxyDNS` + - : `boolean`. 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. + - `failoverTimeout` + - : `integer`. 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. + +- `requestHeaders`{{optional_inline}} + - : {{WebExtAPIRef('webRequest.HttpHeaders')}}. Les en-têtes de réponse HTTP qui ont été reçus avec cette réponse. +- `requestId` + - : `string`. 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. +- `tabId` + - : `integer`. ID de l'onglet dans lequel la demande a lieu. Définir à -1 si la requête n'est pas liée à un onglet. +- `timeStamp` + - : `number`. L'heure à laquelle cet événement s'est déclenché, en [millisecondes depuis l'époque](https://en.wikipedia.org/wiki/Unix_time). +- `type` + - : {{WebExtAPIRef('webRequest.ResourceType')}}. Le type de ressource demandée : par exemple, "image", "script", "stylesheet". +- `url` + - : `string`. Cible de la demande. + +## Compatibilité du navigateur + +{{Compat("webextensions.api.webRequest.onBeforeSendHeaders", 10)}} + +## Exemples + +Ce code modifie l'en-tête "User-Agent" pour que le navigateur s'identifie comme étant Opera 12.16, mais uniquement lors de la visite des pages sous "https\://httpbin.org/". + +```js +"use strict"; /* This is the page for which we want to rewrite the User-Agent header. @@ -194,11 +185,12 @@ browser.webRequest.onBeforeSendHeaders.addListener( {urls: [targetPage]}, ["blocking", "requestHeaders"] ); -</pre> +``` -<p>Ce code est exactement comme l'exemple précédent, sauf que l'auditeur est asynchrone, retournant une <code><a href="/fr/docs/Web/JavaScript/Reference/Objets_globaux/Promise">Promise</a></code> qui est résolue avec les nouveaux en-têtes :</p> +Ce code est exactement comme l'exemple précédent, sauf que l'auditeur est asynchrone, retournant une [`Promise`](/fr/docs/Web/JavaScript/Reference/Objets_globaux/Promise) qui est résolue avec les nouveaux en-têtes : -<pre class="brush: js">"use strict"; +```js +"use strict"; /* This is the page for which we want to rewrite the User-Agent header. @@ -214,8 +206,8 @@ var ua = "Opera/9.80 (X11; Linux i686; Ubuntu/14.10) Presto/2.12.388 Version/12. Rewrite the User-Agent header to "ua". */ function rewriteUserAgentHeaderAsync(e) { - var asyncRewrite = new Promise((resolve, reject) => { - window.setTimeout(() => { + var asyncRewrite = new Promise((resolve, reject) => { + window.setTimeout(() => { for (var header of e.requestHeaders) { if (header.name.toLowerCase() === "user-agent") { header.value = ua; @@ -239,20 +231,17 @@ browser.webRequest.onBeforeSendHeaders.addListener( {urls: [targetPage]}, ["blocking", "requestHeaders"] ); +``` -</pre> - -<p>{{WebExtExamples}}</p> - -<div class="note"><p><strong>Note :</strong></p> - -<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> +{{WebExtExamples}} -<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> +> **Note :** +> +> Cette API est basée sur l'API Chromium [`chrome.webRequest`](https://developer.chrome.com/extensions/webRequest). Cette documentation est dérivée de [`web_request.json`](https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/web_request.json) dans le code Chromium. +> +> 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. -<div class="hidden"> -<pre>// Copyright 2015 The Chromium Authors. All rights reserved. +<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 @@ -279,5 +268,4 @@ browser.webRequest.onBeforeSendHeaders.addListener( // 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> +</pre></div> |