Utiliser Fetch

Ce genre de fonctionnalité était auparavant réalisé avec XMLHttpRequest. Fetch fournit une meilleure alternative qui peut être utilisée facilement par d’autres technologies comme 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.

Détection de la fonctionnalité

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

if(self.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:

var myImage = document.querySelector('img');

fetch('flowers.jpg')
.then(function(response) {
  return response.blob();
})
.then(function(myBlob) {
  var 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 <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 (a Response).

Bien sûr c'est juste une réponse HTTP , pas l'image actuelle. Pour extraire le contenu de l'image de la réponse, nous utilisons la méthode blob() (défini sur le mixin Body, qui est implémenté autant par les objets Request que par les objets Response).

Un objet objectURL est ensuite créé à partir du Blob extrait, puis est inseré dans 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() peut accepter, optionnellement, un second paramètre, 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 à 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 fetch() va retourner une 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é 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 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.

En-têtes (Headers)

L'interface Headers vous permet de créer vos propres objets d'en-têtes via le constructeur 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 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", "https://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:

• none: défaut.
• request: guard pour l’en-tête obtenu d'une requête (Request.headers).
• request-no-cors: guard pour l'en-tête obtenu d'une requête créé avec Request.mode no-cors.
• response: guard pour l'en-tête obtenu d'une réponse (Response.headers).
• immutable: majoritairement utilisé pour les ServiceWorkers; retourne un objet en-tête en lecture seule.

Réponses

Comme vous l'avez vu ci-dessus, des instances de 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 ServiceWorkers, quand vous retournez, pour une requête reçue, une réponse personnalisée en utilisant la méthode respondWith():

var myBody = new Blob();

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

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

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

• Response.status —Un entier (valeur par défaut 200) contenant le code de statut de la réponse.
• Response.statusText — Une chaine de caractères (valeur par défaut "OK"), qui correspond au message du statut HTTP.
• Response.ok —vu précedemment, c'est un raccourci pour vérifier que le code de statut et bien compris entre 200 et 299 inclus. Retourne un Boolean.

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:

• ArrayBuffer
• ArrayBufferView (Uint8Array et ses proches)
• Blob/Fichier
• chaine de caractères
• URLSearchParams
• FormData

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

• arrayBuffer()
• blob()
• json()
• text()
• formData()

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

Browser compatibility

Voir aussi

• API ServiceWorker
• HTTP access control (CORS)
• HTTP
• Polyfill pour Fetch
• Exemples de Fetch sur Github