MDN’s new design is in Beta! A sneak peek: https://blog.mozilla.org/opendesign/mdns-new-design-beta/

GlobalFetch.fetch()

Cette fonction est expérimentale
Puisque cette fonction est toujours en développement dans certains navigateurs, veuillez consulter le tableau de compatibilité pour les préfixes à utiliser selon les navigateurs.
Il convient de noter qu'une fonctionnalité expérimentale peut voir sa syntaxe ou son comportement modifié dans le futur en fonction des évolutions de la spécification.

La méthode fetch() du mixin GlobalFetch va chercher une ressource. Elle retourne une promesse qui résoud une Response, représentant la réponse de votre requête.

GlobalFetch est aussi bien implémenté par Window que par WorkerGlobalScope, ce qui signifie que la méthode fetch() est disponible dans la plupart des cas où vous pourriez en avoir besoin.

Une promesse fetch() peut être rejetée avec une TypeError quand un problème de réseau est rencontré, même si en réalité cela signifie généralement qu'il y a un problème de permissions ou quelque chose comme cela. Une vérification complète d'un fetch() réussi devrait inclure la vérification de la réussite de la promesse, puis que la propriété Response.ok ait bien pour valeur true. Un code HTTP 404 n'est pas une erreur de réseau.

La méthode fetch() est contrôlée par la directive connect-src de l'entête Content Security Policy plutôt que par la directive de la ressource qui est récupérée.

Les paramètres de la méthode fetch() sont identiques à ceux du contructeur d'une Request().

Syntaxe

Promise<Response> fetch(entrée[, init]);

Paramètres

Entrée
Défini la ressource que vous voulez collecter. Cela peut être :
  • Un USVString qui contient l'URL de la ressource à obtenir. Certains navigateurs acceptent blob: et data:.
  • Un objet Request.
init Facultatif
Un objet qui contient les paramètres de votre requête. Les options possibles sont :
  • method : La méthode de la requête, par exemple GET ou POST.
  • headers : Les entêtes à ajouter à votre requête, contenues dans un objet Headers ou dans un objet avec des ByteString pour valeurs.
  • body : Le corps de votre requête. Cela peut être un Blob, un BufferSource, un FormData, un URLSearchParams, ou un USVString. Notez cependant qu'une requête avec GET ou HEAD pour méthode ne peut pas avoir de corps.
  • mode : Le mode à utiliser pour cette requête, par exemple cors, no-cors, ou same-origin.
  • credentials : Les identifiants à utiliser pour cette requête : omit, same-origin, ou include. Pour envoyer automatiquement les cookies pour le domaine actuel, cette option doit être définie. À partir de Chrome 50, cette propriété peut aussi prendre un objet FederatedCredential ou une instance de PasswordCredential.
  • cache : Le comportement du cache pour cette requête : default, no-store, reload, no-cache, force-cache, ou only-if-cached.
  • redirect : Le mode de redirection à adopter pour cette requête : follow (suivre les redirections automatiquement), error (abandonner avec une erreur si une redirection a lieu), ou manual (gérer les redirections manuellement). Dans Chrome, la valeur par défaut était follow avant Chrome 47, mais à partir de cette version, c'est manual.
  • referrer : Un USVString qui vaut no-referrerclient, ou qui contient une URL. La valeur par défaut est client.
  • referrerPolicy : Spécifie la valeur de l'entête HTTP referer. Cela peut être no-referrer, no-referrer-when-downgrade, origin, origin-when-cross-origin ou unsafe-url.
  • integrity : Contient la valeur de l'intégrité de la sous-ressource de la requête (par exemple, sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=).

Valeur retournée

Une Promise qui se résoud avec un object Response.

Exceptions

Type Description
TypeError Depuis Firefox 43, fetch() enverra une TypeError si l'URL contient des identifiants, comma dans http://user:password@example.com.

Exemple

Dans notre exemple de requête avec fetch (voir cet exemple en direct) nous créons une nouvelle Request avec le constructeur correspondant, puis on l'envoie en appellant fetch(). Comme nous récupérons une image, nous utilisons la méthode Body.blob() sur la réponse pour lui donner le bon type MIME pour qu'elle soit gérée correctement, puis l'on crée l'URL correspondant à cet objet et on l'affiche dans un élément <img>.

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

var maRequete = new Request('fleurs.jpg');

fetch(maRequete).then(function(reponse) {
  return reponse.blob();
}).then(function(reponse) {
  var URLobjet = URL.createObjectURL(reponse);
  monImage.src = URLobjet;
});

Dans notre exemple fetch avec initialisation et requête (voir cet exemple en direct) nous faisons la même chose à la différence que nous passons aussi un objet d'initalisation à la méthode fetch :

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

var mesEntetes = new Headers();
mesEntetes.append('Content-Type', 'image/jpeg');

var monInit = { method: 'GET',
               headers: myHeaders,
               mode: 'cors',
               cache: 'default' };

var maRequete = new Request('fleurs.jpg');

fetch(maRequete, monInit).then(function(reponse) {
  ... 
});

Notez que vous pouvez aussi passer l'objet d'initialisation au constructeur de la requête pour obtenir le même effet, par exemple :

var maRequete = new Request('fleurs.jpg', monInit);

Vous pouvez aussi utiliser un objet litéral comme entêtes dans votre objet d'initalisation.

var monInit = { method: 'GET',
               headers: {
                   'Content-Type': 'image/jpeg'
               },
               mode: 'cors',
               cache: 'default' };

var maRequete = new Request('fleurs.jpg', monInit);

Spécifications

Specification Statut Commentaire
Fetch
La définition de 'fetch()' dans cette spécification.
Standard évolutif Définition initiale
Credential Management Level 1 Brouillon de l'éditeur Ajoute la possiblité d'utiliser une instance de FederatedCredential ou de PasswordCredential comme valeur de init.credentials.

Compatibilité des navigateurs

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Support basique 42.0 39 (39)
34[1]
Pas de support 29
28[1]
Pas de support
Diffuser le corps de la réponse au fur et à mesure 43.0 ? ? ? ?
Support de blob: et data: 48.0        
referrerPolicy 52.0     39  
Feature Android Android Webview Firefox Mobile (Gecko) Firefox OS (Gecko) IE Phone Opera Mobile Safari Mobile Chrome for Android
Support basique Pas de support 42.0 Pas de support Pas de support Pas de support Pas de support Pas de support 42.0
Diffuser le corps de la réponse au fur et à mesure Pas de support 43.0 ? ? ? ? ? 43.0
Support de blob: et data: Pas de support 43.0           43.0
referrerPolicy Pas de support 52.0       39   52.0

[1] Cette API est implentée mais doit être activée avec une préférence.

Voir aussi

Étiquettes et contributeurs liés au document

 Contributeurs à cette page : Hell_Carlito, Bat41
 Dernière mise à jour par : Hell_Carlito,