From c05efa8d7ae464235cf83d7c0956e42dc6974103 Mon Sep 17 00:00:00 2001 From: julieng Date: Sat, 2 Oct 2021 17:20:14 +0200 Subject: move *.html to *.md --- .../fr/web/api/fetch_api/basic_concepts/index.html | 64 ----- files/fr/web/api/fetch_api/basic_concepts/index.md | 64 +++++ files/fr/web/api/fetch_api/index.html | 81 ------ files/fr/web/api/fetch_api/index.md | 81 ++++++ files/fr/web/api/fetch_api/using_fetch/index.html | 310 --------------------- files/fr/web/api/fetch_api/using_fetch/index.md | 310 +++++++++++++++++++++ 6 files changed, 455 insertions(+), 455 deletions(-) delete mode 100644 files/fr/web/api/fetch_api/basic_concepts/index.html create mode 100644 files/fr/web/api/fetch_api/basic_concepts/index.md delete mode 100644 files/fr/web/api/fetch_api/index.html create mode 100644 files/fr/web/api/fetch_api/index.md delete mode 100644 files/fr/web/api/fetch_api/using_fetch/index.html create mode 100644 files/fr/web/api/fetch_api/using_fetch/index.md (limited to 'files/fr/web/api/fetch_api') diff --git a/files/fr/web/api/fetch_api/basic_concepts/index.html b/files/fr/web/api/fetch_api/basic_concepts/index.html deleted file mode 100644 index 93a268d89b..0000000000 --- a/files/fr/web/api/fetch_api/basic_concepts/index.html +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: 'Fetch : concepts de départ' -slug: Web/API/Fetch_API/Basic_concepts -translation_of: Web/API/Fetch_API/Basic_concepts ---- -

{{DefaultAPISidebar("Fetch API")}}{{draft}}

- -

L'API Fetch fournit une interface pour récupérer des ressources (y compris depuis le réseau). Elle paraîtra familière à quiconque aura déjà utilisé {{domxref("XMLHttpRequest")}}, mais elle fournit un jeu de fonctionnalités plus puissantes et plus souples. Cet article explique quelques uns des principes de base de l'API Fetch.

- -
-

Note : This article will be added to over time. If you find a Fetch concept that you feel needs explaining better, let someone know on the MDN discussion forum, or Mozilla IRC (#mdn room.)

-
- -

In a nutshell

- -

At the heart of Fetch are the Interface abstractions of HTTP {{domxref("Request")}}s, {{domxref("Response")}}s, {{domxref("Headers")}}, and {{domxref("Body")}} payloads, along with a {{domxref("GlobalFetch.fetch","global fetch")}} method for initiating asynchronous resource requests. Because the main components of HTTP are abstracted as JavaScript objects, it is easy for other APIs to make use of such functionality.

- -

Service Workers is an example of an API that makes heavy use of Fetch.

- -

Fetch takes the asynchronous nature of such requests one step further. The API is completely {{jsxref("Promise")}}-based.

- -

Guard

- -

Guard is a feature of {{domxref("Headers")}} objects, with possible values of immutable, request, request-no-cors, response, or none, depending on where the header is used.

- -

When a new {{domxref("Headers")}} object is created using the {{domxref("Headers.Headers","Headers()")}} {{glossary("constructor")}}, its guard is set to none (the default). When a {{domxref("Request")}} or {{domxref("Response")}} object is created, it has an associated {{domxref("Headers")}} object whose guard is set as summarized below:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
new object's typecreating constructorguard setting of associated {{domxref("Headers")}} object
{{domxref("Request")}}{{domxref("Request.Request","Request()")}}request
{{domxref("Request.Request","Request()")}} with {{domxref("Request.mode","mode")}} of no-corsrequest-no-cors
{{domxref("Response")}}{{domxref("Response.Response","Response()")}}response
{{domxref("Response.error","error()")}} or {{domxref("Response.redirect","redirect()")}} methodsimmutable
- -

A header's guard affects the {{domxref("Headers.set","set()")}}, {{domxref("Headers.delete","delete()")}}, and {{domxref("Headers.append","append()")}} methods which change the header's contents. A TypeError is thrown if you try to modify a {{domxref("Headers")}} object whose guard is immutable. However, the operation will work if

- - diff --git a/files/fr/web/api/fetch_api/basic_concepts/index.md b/files/fr/web/api/fetch_api/basic_concepts/index.md new file mode 100644 index 0000000000..93a268d89b --- /dev/null +++ b/files/fr/web/api/fetch_api/basic_concepts/index.md @@ -0,0 +1,64 @@ +--- +title: 'Fetch : concepts de départ' +slug: Web/API/Fetch_API/Basic_concepts +translation_of: Web/API/Fetch_API/Basic_concepts +--- +

{{DefaultAPISidebar("Fetch API")}}{{draft}}

+ +

L'API Fetch fournit une interface pour récupérer des ressources (y compris depuis le réseau). Elle paraîtra familière à quiconque aura déjà utilisé {{domxref("XMLHttpRequest")}}, mais elle fournit un jeu de fonctionnalités plus puissantes et plus souples. Cet article explique quelques uns des principes de base de l'API Fetch.

+ +
+

Note : This article will be added to over time. If you find a Fetch concept that you feel needs explaining better, let someone know on the MDN discussion forum, or Mozilla IRC (#mdn room.)

+
+ +

In a nutshell

+ +

At the heart of Fetch are the Interface abstractions of HTTP {{domxref("Request")}}s, {{domxref("Response")}}s, {{domxref("Headers")}}, and {{domxref("Body")}} payloads, along with a {{domxref("GlobalFetch.fetch","global fetch")}} method for initiating asynchronous resource requests. Because the main components of HTTP are abstracted as JavaScript objects, it is easy for other APIs to make use of such functionality.

+ +

Service Workers is an example of an API that makes heavy use of Fetch.

+ +

Fetch takes the asynchronous nature of such requests one step further. The API is completely {{jsxref("Promise")}}-based.

+ +

Guard

+ +

Guard is a feature of {{domxref("Headers")}} objects, with possible values of immutable, request, request-no-cors, response, or none, depending on where the header is used.

+ +

When a new {{domxref("Headers")}} object is created using the {{domxref("Headers.Headers","Headers()")}} {{glossary("constructor")}}, its guard is set to none (the default). When a {{domxref("Request")}} or {{domxref("Response")}} object is created, it has an associated {{domxref("Headers")}} object whose guard is set as summarized below:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
new object's typecreating constructorguard setting of associated {{domxref("Headers")}} object
{{domxref("Request")}}{{domxref("Request.Request","Request()")}}request
{{domxref("Request.Request","Request()")}} with {{domxref("Request.mode","mode")}} of no-corsrequest-no-cors
{{domxref("Response")}}{{domxref("Response.Response","Response()")}}response
{{domxref("Response.error","error()")}} or {{domxref("Response.redirect","redirect()")}} methodsimmutable
+ +

A header's guard affects the {{domxref("Headers.set","set()")}}, {{domxref("Headers.delete","delete()")}}, and {{domxref("Headers.append","append()")}} methods which change the header's contents. A TypeError is thrown if you try to modify a {{domxref("Headers")}} object whose guard is immutable. However, the operation will work if

+ + diff --git a/files/fr/web/api/fetch_api/index.html b/files/fr/web/api/fetch_api/index.html deleted file mode 100644 index 49ae613fb1..0000000000 --- a/files/fr/web/api/fetch_api/index.html +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: API Fetch -slug: Web/API/Fetch_API -translation_of: Web/API/Fetch_API ---- -

{{DefaultAPISidebar("Fetch API")}}

- -

L'API Fetch fournit une interface pour la récupération de ressources (e.g., à travers le réseau.) Elle paraîtra familière à tout utilisateur de {{domxref("XMLHttpRequest")}}, mais cette nouvelle API propose néanmoins un ensemble de fonctionnalités plus souples et plus puissantes.

- -

Concepts et usage

- -

Fetch fournit une définition générique des objets {{domxref("Request")}} et {{domxref("Response")}} (et d'autres choses impliquées par les requêtes réseau). Ainsi il sera possible de les utiliser dès que nécessaire à l'avenir, même si c'est dans le cadre de service workers, de l'API Cache ou d'autres mécanismes similaires qui manipulent ou modifient des requêtes et des réponses, ou n'importe quelle situation qui pourrait requérir que vous génériez vos propres réponses au moyen d'un programme.

- -

Elle fournit également une définition pour des concepts associés tels que CORS et la sémantique de l'en-tête HTTP origin, supplantant les définitions précédemment proposées ailleurs.

- -

Pour effectuer une requête et obtenir une ressource, utilisez la méthode {{domxref("GlobalFetch.fetch")}}. Elle est implémentée dans de multiples interfaces, et en particulier dans {{domxref("Window")}} et {{domxref("WorkerGlobalScope")}}. Ce qui la rend disponible de la même manière dans tout contexte où vous souhaiteriez récupérer des ressources.

- -

La méthode fetch() prend un argument obligatoire, le chemin vers la ressource souhaitée. Elle retourne une promesse qui résout la {{domxref("Response")}} de cette requête, qu'elle soit couronnée de succès ou non. Vous pouvez aussi optionnellement lui passer un objet d'options init comme second argument (voir {{domxref("Request")}}.)

- -

Une fois que la {{domxref("Response")}} a été retournée, il y a un ensemble de méthodes disponibles pour déterminer ce que doit être le contenu du corps et comment il doit être manipulé (voir {{domxref("Body")}}.)

- -

Vous pourriez créer une requête et une réponse directement en utilisant les constructeurs {{domxref("Request.Request","Request()")}} et {{domxref("Response.Response","Response()")}}, même s'il est improbable que vous procédiez ainsi. Il est plus probable cependant que leur création résulte des actions d'une autre API (par exemple, {{domxref("FetchEvent.respondWith")}} des service workers).

- -
-

Note : Pour en savoir plus sur l'utilisation des fonctionnalités de l'API Fetch et en approfondir les concepts, consulter respectivement Utiliser Fetch et Fetch, les concepts de base.

-
- -

Interrompre un fetch

- -

Les navigateurs ont commencé à ajouter le support expérimental des interfaces {{DOMxRef("AbortController")}} et {{DOMxRef("AbortSignal")}} (connue aussi sous le nom d'API d'interruption), qui autorisent les opérations telles que Fetch et XHR à être interrompue si elles ne sont pas encore achevées. Voir les pages des interfaces pour plus de détails.

- -

Les interfaces de Fetch

- -
-
{{domxref("GlobalFetch")}}
-
La méthode fetch() est utilisée pour récuperer une ressource.
-
{{domxref("Headers")}}
-
Représente les en-têtes de requête et de réponse, vous permettant de les consulter et de prendre différentes décisions en fonction du résultat.
-
{{domxref("Request")}}
-
Représente la requête d'une ressource.
-
{{domxref("Response")}}
-
Représente la réponse à une requête.
-
- -

Mixin de Fetch

- -
-
{{domxref("Body")}}
-
Fournit les méthodes relatives au corps de la requête/réponse, vous permettant  de déclarer quel est son type de contenu et comment il doit être manipulé.
-
- -

Spécifications

- - - - - - - - - - - - - - -
SpécificationStatutCommentaire
{{SpecName('Fetch')}}{{Spec2('Fetch')}}Définition initiale
- -

Compatibilité Navigateurs

- -

{{Compat("api.WindowOrWorkerGlobalScope.fetch")}}

- -

Voir aussi

- - diff --git a/files/fr/web/api/fetch_api/index.md b/files/fr/web/api/fetch_api/index.md new file mode 100644 index 0000000000..49ae613fb1 --- /dev/null +++ b/files/fr/web/api/fetch_api/index.md @@ -0,0 +1,81 @@ +--- +title: API Fetch +slug: Web/API/Fetch_API +translation_of: Web/API/Fetch_API +--- +

{{DefaultAPISidebar("Fetch API")}}

+ +

L'API Fetch fournit une interface pour la récupération de ressources (e.g., à travers le réseau.) Elle paraîtra familière à tout utilisateur de {{domxref("XMLHttpRequest")}}, mais cette nouvelle API propose néanmoins un ensemble de fonctionnalités plus souples et plus puissantes.

+ +

Concepts et usage

+ +

Fetch fournit une définition générique des objets {{domxref("Request")}} et {{domxref("Response")}} (et d'autres choses impliquées par les requêtes réseau). Ainsi il sera possible de les utiliser dès que nécessaire à l'avenir, même si c'est dans le cadre de service workers, de l'API Cache ou d'autres mécanismes similaires qui manipulent ou modifient des requêtes et des réponses, ou n'importe quelle situation qui pourrait requérir que vous génériez vos propres réponses au moyen d'un programme.

+ +

Elle fournit également une définition pour des concepts associés tels que CORS et la sémantique de l'en-tête HTTP origin, supplantant les définitions précédemment proposées ailleurs.

+ +

Pour effectuer une requête et obtenir une ressource, utilisez la méthode {{domxref("GlobalFetch.fetch")}}. Elle est implémentée dans de multiples interfaces, et en particulier dans {{domxref("Window")}} et {{domxref("WorkerGlobalScope")}}. Ce qui la rend disponible de la même manière dans tout contexte où vous souhaiteriez récupérer des ressources.

+ +

La méthode fetch() prend un argument obligatoire, le chemin vers la ressource souhaitée. Elle retourne une promesse qui résout la {{domxref("Response")}} de cette requête, qu'elle soit couronnée de succès ou non. Vous pouvez aussi optionnellement lui passer un objet d'options init comme second argument (voir {{domxref("Request")}}.)

+ +

Une fois que la {{domxref("Response")}} a été retournée, il y a un ensemble de méthodes disponibles pour déterminer ce que doit être le contenu du corps et comment il doit être manipulé (voir {{domxref("Body")}}.)

+ +

Vous pourriez créer une requête et une réponse directement en utilisant les constructeurs {{domxref("Request.Request","Request()")}} et {{domxref("Response.Response","Response()")}}, même s'il est improbable que vous procédiez ainsi. Il est plus probable cependant que leur création résulte des actions d'une autre API (par exemple, {{domxref("FetchEvent.respondWith")}} des service workers).

+ +
+

Note : Pour en savoir plus sur l'utilisation des fonctionnalités de l'API Fetch et en approfondir les concepts, consulter respectivement Utiliser Fetch et Fetch, les concepts de base.

+
+ +

Interrompre un fetch

+ +

Les navigateurs ont commencé à ajouter le support expérimental des interfaces {{DOMxRef("AbortController")}} et {{DOMxRef("AbortSignal")}} (connue aussi sous le nom d'API d'interruption), qui autorisent les opérations telles que Fetch et XHR à être interrompue si elles ne sont pas encore achevées. Voir les pages des interfaces pour plus de détails.

+ +

Les interfaces de Fetch

+ +
+
{{domxref("GlobalFetch")}}
+
La méthode fetch() est utilisée pour récuperer une ressource.
+
{{domxref("Headers")}}
+
Représente les en-têtes de requête et de réponse, vous permettant de les consulter et de prendre différentes décisions en fonction du résultat.
+
{{domxref("Request")}}
+
Représente la requête d'une ressource.
+
{{domxref("Response")}}
+
Représente la réponse à une requête.
+
+ +

Mixin de Fetch

+ +
+
{{domxref("Body")}}
+
Fournit les méthodes relatives au corps de la requête/réponse, vous permettant  de déclarer quel est son type de contenu et comment il doit être manipulé.
+
+ +

Spécifications

+ + + + + + + + + + + + + + +
SpécificationStatutCommentaire
{{SpecName('Fetch')}}{{Spec2('Fetch')}}Définition initiale
+ +

Compatibilité Navigateurs

+ +

{{Compat("api.WindowOrWorkerGlobalScope.fetch")}}

+ +

Voir aussi

+ + diff --git a/files/fr/web/api/fetch_api/using_fetch/index.html b/files/fr/web/api/fetch_api/using_fetch/index.html deleted file mode 100644 index 04a5708c1a..0000000000 --- a/files/fr/web/api/fetch_api/using_fetch/index.html +++ /dev/null @@ -1,310 +0,0 @@ ---- -title: Utiliser Fetch -slug: Web/API/Fetch_API/Using_Fetch -tags: - - API - - BODY - - Expérimental(2) - - Fetch - - Guide - - Promesse - - Promise - - Response - - request -translation_of: Web/API/Fetch_API/Using_Fetch ---- -

{{DefaultAPISidebar("Fetch API")}}

- -

L'API Fetch fournit une interface JavaScript pour l'accès et la manipulation des parties de la pipeline HTTP, comme les requêtes et les réponses. Cela fournit aussi une méthode globale {{domxref("GlobalFetch.fetch","fetch()")}} qui procure un moyen facile et logique de récupérer des ressources à travers le réseau de manière asynchrone.

- -

Ce genre de fonctionnalité était auparavant réalisé avec {{domxref("XMLHttpRequest")}}. Fetch fournit une meilleure alternative qui peut être utilisée facilement par d’autres technologies comme {{domxref("ServiceWorker_API", "Service Workers")}}. Fetch fournit aussi un endroit unique et logique pour la définition d'autres concepts liés à HTTP comme CORS et les extensions d'HTTP.

- -

L'état actuel du support par les navigateurs

- -

Le support de Fetch est à ses débuts, mais les choses progressent. Il a été activé par défaut sur Firefox 39 et supérieur, et sur Chrome 42 et supérieur.

- -

Si vous souhaitez l'utiliser maintenant, il y a un polyfill Fetch disponible qui recrée la fonctionnalité pour les navigateurs qui ne le supportent pas. Gardez à l'esprit qu'il est au stade expérimental et pas encore complètement fonctionnel.

- -
-

Note : Certaines préoccupations ont été soulevées sur le fait que la spécification de Fetch est en contradition avec la spécification de Streams; cependant, les prévisions montrent une intention d'intégrer Streams avec Fetch: pour plus d'informations reportez vous à Fetch API integrated with Streams.

-
- -

Détection de la fonctionnalité

- -

Le support de l'API Fetch peut être détecté en vérifiant l'existence de {{domxref("Headers")}}, {{domxref("Request")}}, {{domxref("Response")}} ou {{domxref("GlobalFetch.fetch","fetch()")}} sur la portée de {{domxref("Window")}} ou de {{domxref("Worker")}}. Par exemple, vous pouvez faire cela dans votre script :

- -
if (window.fetch) {
-    // exécuter ma requête fetch ici
-} else {
-    // Faire quelque chose avec XMLHttpRequest?
-}
- -

Créer une requête fetch

- -

Une requête fetch basique est vraiment simple à initier. Jetez un coup d'œil au code suivant :

- -
const myImage = document.querySelector('img');
-
-fetch('flowers.jpg')
-.then(function(response) {
-  return response.blob();
-})
-.then(function(myBlob) {
-  const objectURL = URL.createObjectURL(myBlob);
-  myImage.src = objectURL;
-});
-
-
- -

Ici nous récupérons une image à travers le réseau et l'insérons dans un élément {{htmlelement("img")}}. L'utilisation la plus simple de fetch() prend un argument — le chemin de la ressource que nous souhaitons récupérer — et retourne une promesse (promise) contenant, en réponse, un objet (de type {{domxref("Response")}}).

- -

Bien sûr, il s'agit seulement d'une réponse HTTP, pas exactement de l'image. Pour extraire le contenu de l'image de la réponse, nous utilisons la méthode {{domxref("Body.blob","blob()")}} (définie sur le mixin {{domxref("Body")}}, qui est implémenté autant par les objets {{domxref("Request")}} que par les objets {{domxref("Response")}}).

- -
-

Note : Le mixin Body a aussi des méthodes similaires pour extraire d'autres types contenu ; pour plus d'informations regardez la section {{anch("Corps")}}.

-
- -

Un objet objectURL est ensuite créé à partir du {{domxref("Blob")}} extrait, puis est inseré dans {{domxref("img")}}.

- -

Les requêtes Fetch sont controllées par la directive connect-src du Content Security Policy plutôt que par la directive de la ressource dont il s’agit de la récupération.

- -

Fournir des options à la requête

- -

La méthode fetch() accepte un second paramètre, optionnel ; un objet init qui vous permet de contrôler un certain nombre de réglages :

- -
var myHeaders = new Headers();
-
-var myInit = { method: 'GET',
-               headers: myHeaders,
-               mode: 'cors',
-               cache: 'default' };
-
-fetch('flowers.jpg',myInit)
-.then(function(response) {
-  return response.blob();
-})
-.then(function(myBlob) {
-  var objectURL = URL.createObjectURL(myBlob);
-  myImage.src = objectURL;
-});
-
-
- -

Reportez-vous à {{domxref("GlobalFetch.fetch","fetch()")}} pour la liste complète des options disponibles, et plus de détails.

- -

Vérifier que la récupération a réussi

- -

Une promesse {{domxref("GlobalFetch.fetch","fetch()")}} va retourner une {{jsxref("TypeError")}} quand un problème réseau s'est produit. Cependant, il peut aussi s'agir d'un problème de permission ou quelque chose de similaire — un code HTTP 404 ne constitue pas une erreur réseau, par exemple. Un bon test de la réussite de fetch() devrait inclure la vérification que la promesse soit résolue, puis vérifier que la propriété {{domxref("Response.ok")}} ait la valeur true. Le code devrait ressembler à ce qui suit:

- -
fetch('flowers.jpg').then(function(response) {
-  if(response.ok) {
-    response.blob().then(function(myBlob) {
-      var objectURL = URL.createObjectURL(myBlob);
-      myImage.src = objectURL;
-    });
-  } else {
-    console.log('Mauvaise réponse du réseau');
-  }
-})
-.catch(function(error) {
-  console.log('Il y a eu un problème avec l\'opération fetch: ' + error.message);
-});
- -

Fournir votre propre objet requête

- -

Plutôt que de transmettre le chemin de la ressource que vous souhaitez récupérer avec l'appel fetch(), vous pouvez créer un objet de requête en utilisant le constructeur {{domxref("Request.Request","Request()")}}, et le transmettre à la méthode fetch() en tant qu’argument:

- -
var myHeaders = new Headers();
-
-var myInit = { method: 'GET',
-               headers: myHeaders,
-               mode: 'cors',
-               cache: 'default' };
-
-var myRequest = new Request('flowers.jpg',myInit);
-
-fetch(myRequest,myInit)
-.then(function(response) {
-  return response.blob();
-})
-.then(function(myBlob) {
-  var objectURL = URL.createObjectURL(myBlob);
-  myImage.src = objectURL;
-});
- -

Request() accepte exactement les mêmes paramètres que la méthode fetch(). Vous pouvez même lui transmettre un objet Request existant pour en créer une copie :

- -
var anotherRequest = new Request(myRequest,myInit);
- -

C'est très pratique, si le corps de la requête et de la réponse ne sont utilisés qu'une fois seulement. Cette manière de faire une copie permet de ré-utiliser la requête/réponse, en changeant juste les options du init si nécessaire.

- -
-

Note : Il y a aussi une méthode {{domxref("Request.clone","clone()")}} qui créer une copie. Cela a une sémantique légèrement différente à l'autre méthode de copie— La première va échouer si l'ancien corps de la requête a déjà été lu (même pour copier une réponse), alors qu'avec clone() non.

-
- -

En-têtes (Headers)

- -

L'interface {{domxref("Headers")}} vous permet de créer vos propres objets d'en-têtes via le constructeur {{domxref("Headers.Headers","Headers()")}}. Un objet en-tête est un simple ensemble de plusieurs clé-valeurs:

- -
var content = "Hello World";
-var myHeaders = new Headers();
-myHeaders.append("Content-Type", "text/plain");
-myHeaders.append("Content-Length", content.length.toString());
-myHeaders.append("X-Custom-Header", "ProcessThisImmediately");
- -

On peut atteindre le même résultat en transmettant un tableau de tableaux ou un objet littéral au constructeur:

- -
myHeaders = new Headers({
-  "Content-Type": "text/plain",
-  "Content-Length": content.length.toString(),
-  "X-Custom-Header": "ProcessThisImmediately",
-});
- -

Le contenu peut être interrogé et récupéré:

- -
console.log(myHeaders.has("Content-Type")); // true
-console.log(myHeaders.has("Set-Cookie")); // false
-myHeaders.set("Content-Type", "text/html");
-myHeaders.append("X-Custom-Header", "AnotherValue");
-
-console.log(myHeaders.get("Content-Length")); // 11
-console.log(myHeaders.getAll("X-Custom-Header")); // ["ProcessThisImmediately", "AnotherValue"]
-
-myHeaders.delete("X-Custom-Header");
-console.log(myHeaders.getAll("X-Custom-Header")); // [ ]
- -

Certaines de ces opérations sont seulement utiles dans {{domxref("ServiceWorker_API","ServiceWorkers")}}, mais elles fournissent une bien meilleur API pour la manipulation des en-têtes.

- -

Toutes les méthodes d'en-tête provoquent une erreur TypeError si un nom d’en-tête utilisé n'est pas un nom d’en-tête HTTP valide. Les opérations de mutation vont provoquer une erreur TypeError si il y a une protection immutable (voir ci-dessous). Sinon elles vont échouer en silence. Par exemple :

- -
var myResponse = Response.error();
-try {
-  myResponse.headers.set("Origin", "http://mybank.com");
-} catch(e) {
-  console.log("Ne peut pas prétendre être une banque!");
-}
- -

Un bon cas d'utilisation des en-têtes est de vérifier que le type de contenu récupéré est correct avant de poursuivre le traitement. Par exemple:

- -
fetch(myRequest).then(function(response) {
-  var contentType = response.headers.get("content-type");
-  if(contentType && contentType.indexOf("application/json") !== -1) {
-    return response.json().then(function(json) {
-      // traitement du JSON
-    });
-  } else {
-    console.log("Oops, nous n'avons pas du JSON!");
-  }
-});
- -

Protection (Guard)

- -

Puisque les en-têtes peuvent être envoyés dans les requêtes et reçus dans les réponses, et ont diverses limitations sur quelles informations peuvent et doivent être mutables, les objets en-tête ont une propriété guard. Ce n'est pas exposé au Web, mais cela définit quelle opération de mutation est autorisée sur l'objet en-tête.

- -

Les valeurs possibles de la propriété guard sont:

- - - -
-

Note : Vous ne pouvez pas ajouter ou définir sur une requête protegée une en-tête Content-Length. De manière similaire, ajouter Set-Cookie dans l'en-tête de réponse n'est pas autorisé: les ServiceWorkers ne sont pas autorisés à gérer des cookies via des réponses synthétisées.

-
- -

Réponses

- -

Comme vous l'avez vu ci-dessus, des instances de {{domxref("Response")}} sont retournées quand la promesse de fetch() est résolue.

- -

Elles peuvent aussi être programmées dans le code via JavaScript, mais c'est seulement utile concernant les {{domxref("ServiceWorker_API", "ServiceWorkers")}}, quand vous retournez, pour une requête reçue, une réponse personnalisée en utilisant la méthode {{domxref("FetchEvent.respondWith","respondWith()")}}:

- -
var myBody = new Blob();
-
-addEventListener('fetch', function(event) {
-  event.respondWith(new Response(myBody, {
-    headers: { "Content-Type" : "text/plain" }
-  });
-)});
- -

Le constructeur {{domxref("Response.Response","Response()")}} prend deux arguments optionnels —le corps de la réponse, et un objet d'options (similaire à l'objet que {{domxref("Request.Request","Request()")}} accepte).

- -

Les propriétés de réponse les plus communes que vous allez utiliser sont:

- - - -
-

Note : La méthode statique {{domxref("Response.error","error()")}} retourne simplement une réponse d'erreur. De manière similaire, {{domxref("Response.redirect","redirect()")}} retourne une réponse de redirection vers une URL spécifique. Elles sont aussi pertinentes pour les Service Workers.

-
- -

Corps

- -

Autant une requête qu'une réponse peut contenir un corps avec des données. Un corps est une instance de n'importe lequel des types suivants:

- - - -

Le mixin {{domxref("Body")}} définit les méthodes suivantes pour extraire le corps (implémenté autant par la {{domxref("Request")}} que par la {{domxref("Response")}}). Elles retournent toutes une promesse qui sera éventuellement résolue avec le contenu actuel.

- - - -

Ceci rend l'usage de données non textuelles plus facile qu’avec XHR.

- -

Le corps des requêtes peut être défini en passant les paramètres du corps:

- -
var form = new FormData(document.getElementById('login-form'));
-fetch("/login", {
-  method: "POST",
-  body: form
-})
- -

Les Requêtes et Réponses (et par extension la fonction fetch()), vont tenter de déterminer le type de contenu. Une requête va automatiquement définir un en-tête Content-Type  si rien n'est défini dans le dictionnaire [NDLT: configuration d'initialisation].

- -

Spécifications

- - - - - - - - - - - - - - -
SpécificationStatutCommentaire
{{SpecName('Fetch')}}{{Spec2('Fetch')}}Définition initiale
- -

Compatibilité navigateur

- -

{{Compat("api.WindowOrWorkerGlobalScope.fetch")}}

- -

Voir aussi

- - diff --git a/files/fr/web/api/fetch_api/using_fetch/index.md b/files/fr/web/api/fetch_api/using_fetch/index.md new file mode 100644 index 0000000000..04a5708c1a --- /dev/null +++ b/files/fr/web/api/fetch_api/using_fetch/index.md @@ -0,0 +1,310 @@ +--- +title: Utiliser Fetch +slug: Web/API/Fetch_API/Using_Fetch +tags: + - API + - BODY + - Expérimental(2) + - Fetch + - Guide + - Promesse + - Promise + - Response + - request +translation_of: Web/API/Fetch_API/Using_Fetch +--- +

{{DefaultAPISidebar("Fetch API")}}

+ +

L'API Fetch fournit une interface JavaScript pour l'accès et la manipulation des parties de la pipeline HTTP, comme les requêtes et les réponses. Cela fournit aussi une méthode globale {{domxref("GlobalFetch.fetch","fetch()")}} qui procure un moyen facile et logique de récupérer des ressources à travers le réseau de manière asynchrone.

+ +

Ce genre de fonctionnalité était auparavant réalisé avec {{domxref("XMLHttpRequest")}}. Fetch fournit une meilleure alternative qui peut être utilisée facilement par d’autres technologies comme {{domxref("ServiceWorker_API", "Service Workers")}}. Fetch fournit aussi un endroit unique et logique pour la définition d'autres concepts liés à HTTP comme CORS et les extensions d'HTTP.

+ +

L'état actuel du support par les navigateurs

+ +

Le support de Fetch est à ses débuts, mais les choses progressent. Il a été activé par défaut sur Firefox 39 et supérieur, et sur Chrome 42 et supérieur.

+ +

Si vous souhaitez l'utiliser maintenant, il y a un polyfill Fetch disponible qui recrée la fonctionnalité pour les navigateurs qui ne le supportent pas. Gardez à l'esprit qu'il est au stade expérimental et pas encore complètement fonctionnel.

+ +
+

Note : Certaines préoccupations ont été soulevées sur le fait que la spécification de Fetch est en contradition avec la spécification de Streams; cependant, les prévisions montrent une intention d'intégrer Streams avec Fetch: pour plus d'informations reportez vous à Fetch API integrated with Streams.

+
+ +

Détection de la fonctionnalité

+ +

Le support de l'API Fetch peut être détecté en vérifiant l'existence de {{domxref("Headers")}}, {{domxref("Request")}}, {{domxref("Response")}} ou {{domxref("GlobalFetch.fetch","fetch()")}} sur la portée de {{domxref("Window")}} ou de {{domxref("Worker")}}. Par exemple, vous pouvez faire cela dans votre script :

+ +
if (window.fetch) {
+    // exécuter ma requête fetch ici
+} else {
+    // Faire quelque chose avec XMLHttpRequest?
+}
+ +

Créer une requête fetch

+ +

Une requête fetch basique est vraiment simple à initier. Jetez un coup d'œil au code suivant :

+ +
const myImage = document.querySelector('img');
+
+fetch('flowers.jpg')
+.then(function(response) {
+  return response.blob();
+})
+.then(function(myBlob) {
+  const objectURL = URL.createObjectURL(myBlob);
+  myImage.src = objectURL;
+});
+
+
+ +

Ici nous récupérons une image à travers le réseau et l'insérons dans un élément {{htmlelement("img")}}. L'utilisation la plus simple de fetch() prend un argument — le chemin de la ressource que nous souhaitons récupérer — et retourne une promesse (promise) contenant, en réponse, un objet (de type {{domxref("Response")}}).

+ +

Bien sûr, il s'agit seulement d'une réponse HTTP, pas exactement de l'image. Pour extraire le contenu de l'image de la réponse, nous utilisons la méthode {{domxref("Body.blob","blob()")}} (définie sur le mixin {{domxref("Body")}}, qui est implémenté autant par les objets {{domxref("Request")}} que par les objets {{domxref("Response")}}).

+ +
+

Note : Le mixin Body a aussi des méthodes similaires pour extraire d'autres types contenu ; pour plus d'informations regardez la section {{anch("Corps")}}.

+
+ +

Un objet objectURL est ensuite créé à partir du {{domxref("Blob")}} extrait, puis est inseré dans {{domxref("img")}}.

+ +

Les requêtes Fetch sont controllées par la directive connect-src du Content Security Policy plutôt que par la directive de la ressource dont il s’agit de la récupération.

+ +

Fournir des options à la requête

+ +

La méthode fetch() accepte un second paramètre, optionnel ; un objet init qui vous permet de contrôler un certain nombre de réglages :

+ +
var myHeaders = new Headers();
+
+var myInit = { method: 'GET',
+               headers: myHeaders,
+               mode: 'cors',
+               cache: 'default' };
+
+fetch('flowers.jpg',myInit)
+.then(function(response) {
+  return response.blob();
+})
+.then(function(myBlob) {
+  var objectURL = URL.createObjectURL(myBlob);
+  myImage.src = objectURL;
+});
+
+
+ +

Reportez-vous à {{domxref("GlobalFetch.fetch","fetch()")}} pour la liste complète des options disponibles, et plus de détails.

+ +

Vérifier que la récupération a réussi

+ +

Une promesse {{domxref("GlobalFetch.fetch","fetch()")}} va retourner une {{jsxref("TypeError")}} quand un problème réseau s'est produit. Cependant, il peut aussi s'agir d'un problème de permission ou quelque chose de similaire — un code HTTP 404 ne constitue pas une erreur réseau, par exemple. Un bon test de la réussite de fetch() devrait inclure la vérification que la promesse soit résolue, puis vérifier que la propriété {{domxref("Response.ok")}} ait la valeur true. Le code devrait ressembler à ce qui suit:

+ +
fetch('flowers.jpg').then(function(response) {
+  if(response.ok) {
+    response.blob().then(function(myBlob) {
+      var objectURL = URL.createObjectURL(myBlob);
+      myImage.src = objectURL;
+    });
+  } else {
+    console.log('Mauvaise réponse du réseau');
+  }
+})
+.catch(function(error) {
+  console.log('Il y a eu un problème avec l\'opération fetch: ' + error.message);
+});
+ +

Fournir votre propre objet requête

+ +

Plutôt que de transmettre le chemin de la ressource que vous souhaitez récupérer avec l'appel fetch(), vous pouvez créer un objet de requête en utilisant le constructeur {{domxref("Request.Request","Request()")}}, et le transmettre à la méthode fetch() en tant qu’argument:

+ +
var myHeaders = new Headers();
+
+var myInit = { method: 'GET',
+               headers: myHeaders,
+               mode: 'cors',
+               cache: 'default' };
+
+var myRequest = new Request('flowers.jpg',myInit);
+
+fetch(myRequest,myInit)
+.then(function(response) {
+  return response.blob();
+})
+.then(function(myBlob) {
+  var objectURL = URL.createObjectURL(myBlob);
+  myImage.src = objectURL;
+});
+ +

Request() accepte exactement les mêmes paramètres que la méthode fetch(). Vous pouvez même lui transmettre un objet Request existant pour en créer une copie :

+ +
var anotherRequest = new Request(myRequest,myInit);
+ +

C'est très pratique, si le corps de la requête et de la réponse ne sont utilisés qu'une fois seulement. Cette manière de faire une copie permet de ré-utiliser la requête/réponse, en changeant juste les options du init si nécessaire.

+ +
+

Note : Il y a aussi une méthode {{domxref("Request.clone","clone()")}} qui créer une copie. Cela a une sémantique légèrement différente à l'autre méthode de copie— La première va échouer si l'ancien corps de la requête a déjà été lu (même pour copier une réponse), alors qu'avec clone() non.

+
+ +

En-têtes (Headers)

+ +

L'interface {{domxref("Headers")}} vous permet de créer vos propres objets d'en-têtes via le constructeur {{domxref("Headers.Headers","Headers()")}}. Un objet en-tête est un simple ensemble de plusieurs clé-valeurs:

+ +
var content = "Hello World";
+var myHeaders = new Headers();
+myHeaders.append("Content-Type", "text/plain");
+myHeaders.append("Content-Length", content.length.toString());
+myHeaders.append("X-Custom-Header", "ProcessThisImmediately");
+ +

On peut atteindre le même résultat en transmettant un tableau de tableaux ou un objet littéral au constructeur:

+ +
myHeaders = new Headers({
+  "Content-Type": "text/plain",
+  "Content-Length": content.length.toString(),
+  "X-Custom-Header": "ProcessThisImmediately",
+});
+ +

Le contenu peut être interrogé et récupéré:

+ +
console.log(myHeaders.has("Content-Type")); // true
+console.log(myHeaders.has("Set-Cookie")); // false
+myHeaders.set("Content-Type", "text/html");
+myHeaders.append("X-Custom-Header", "AnotherValue");
+
+console.log(myHeaders.get("Content-Length")); // 11
+console.log(myHeaders.getAll("X-Custom-Header")); // ["ProcessThisImmediately", "AnotherValue"]
+
+myHeaders.delete("X-Custom-Header");
+console.log(myHeaders.getAll("X-Custom-Header")); // [ ]
+ +

Certaines de ces opérations sont seulement utiles dans {{domxref("ServiceWorker_API","ServiceWorkers")}}, mais elles fournissent une bien meilleur API pour la manipulation des en-têtes.

+ +

Toutes les méthodes d'en-tête provoquent une erreur TypeError si un nom d’en-tête utilisé n'est pas un nom d’en-tête HTTP valide. Les opérations de mutation vont provoquer une erreur TypeError si il y a une protection immutable (voir ci-dessous). Sinon elles vont échouer en silence. Par exemple :

+ +
var myResponse = Response.error();
+try {
+  myResponse.headers.set("Origin", "http://mybank.com");
+} catch(e) {
+  console.log("Ne peut pas prétendre être une banque!");
+}
+ +

Un bon cas d'utilisation des en-têtes est de vérifier que le type de contenu récupéré est correct avant de poursuivre le traitement. Par exemple:

+ +
fetch(myRequest).then(function(response) {
+  var contentType = response.headers.get("content-type");
+  if(contentType && contentType.indexOf("application/json") !== -1) {
+    return response.json().then(function(json) {
+      // traitement du JSON
+    });
+  } else {
+    console.log("Oops, nous n'avons pas du JSON!");
+  }
+});
+ +

Protection (Guard)

+ +

Puisque les en-têtes peuvent être envoyés dans les requêtes et reçus dans les réponses, et ont diverses limitations sur quelles informations peuvent et doivent être mutables, les objets en-tête ont une propriété guard. Ce n'est pas exposé au Web, mais cela définit quelle opération de mutation est autorisée sur l'objet en-tête.

+ +

Les valeurs possibles de la propriété guard sont:

+ + + +
+

Note : Vous ne pouvez pas ajouter ou définir sur une requête protegée une en-tête Content-Length. De manière similaire, ajouter Set-Cookie dans l'en-tête de réponse n'est pas autorisé: les ServiceWorkers ne sont pas autorisés à gérer des cookies via des réponses synthétisées.

+
+ +

Réponses

+ +

Comme vous l'avez vu ci-dessus, des instances de {{domxref("Response")}} sont retournées quand la promesse de fetch() est résolue.

+ +

Elles peuvent aussi être programmées dans le code via JavaScript, mais c'est seulement utile concernant les {{domxref("ServiceWorker_API", "ServiceWorkers")}}, quand vous retournez, pour une requête reçue, une réponse personnalisée en utilisant la méthode {{domxref("FetchEvent.respondWith","respondWith()")}}:

+ +
var myBody = new Blob();
+
+addEventListener('fetch', function(event) {
+  event.respondWith(new Response(myBody, {
+    headers: { "Content-Type" : "text/plain" }
+  });
+)});
+ +

Le constructeur {{domxref("Response.Response","Response()")}} prend deux arguments optionnels —le corps de la réponse, et un objet d'options (similaire à l'objet que {{domxref("Request.Request","Request()")}} accepte).

+ +

Les propriétés de réponse les plus communes que vous allez utiliser sont:

+ + + +
+

Note : La méthode statique {{domxref("Response.error","error()")}} retourne simplement une réponse d'erreur. De manière similaire, {{domxref("Response.redirect","redirect()")}} retourne une réponse de redirection vers une URL spécifique. Elles sont aussi pertinentes pour les Service Workers.

+
+ +

Corps

+ +

Autant une requête qu'une réponse peut contenir un corps avec des données. Un corps est une instance de n'importe lequel des types suivants:

+ + + +

Le mixin {{domxref("Body")}} définit les méthodes suivantes pour extraire le corps (implémenté autant par la {{domxref("Request")}} que par la {{domxref("Response")}}). Elles retournent toutes une promesse qui sera éventuellement résolue avec le contenu actuel.

+ + + +

Ceci rend l'usage de données non textuelles plus facile qu’avec XHR.

+ +

Le corps des requêtes peut être défini en passant les paramètres du corps:

+ +
var form = new FormData(document.getElementById('login-form'));
+fetch("/login", {
+  method: "POST",
+  body: form
+})
+ +

Les Requêtes et Réponses (et par extension la fonction fetch()), vont tenter de déterminer le type de contenu. Une requête va automatiquement définir un en-tête Content-Type  si rien n'est défini dans le dictionnaire [NDLT: configuration d'initialisation].

+ +

Spécifications

+ + + + + + + + + + + + + + +
SpécificationStatutCommentaire
{{SpecName('Fetch')}}{{Spec2('Fetch')}}Définition initiale
+ +

Compatibilité navigateur

+ +

{{Compat("api.WindowOrWorkerGlobalScope.fetch")}}

+ +

Voir aussi

+ + -- cgit v1.2.3-54-g00ecf