1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
---
title: GlobalFetch.fetch()
slug: Web/API/fetch
tags:
- API
- API Fetch
- Experimental
- Fetch
- GlobalFetch
- Méthode
- Reference
- WindowOrWorkerGlobalScope
- requête
translation_of: Web/API/WindowOrWorkerGlobalScope/fetch
original_slug: Web/API/WindowOrWorkerGlobalScope/fetch
---
<p>{{APIRef("Fetch")}}</p>
<p>La méthode <code><strong>fetch()</strong></code> du mixin {{domxref("WindowOrWorkerGlobalScope")}} démarre le chargement d'une ressource sur le réseau et retourne une promesse qui est résolue dès que la réponse est disponible. La promesse résoud l'objet {{domxref("Response")}} représentant la réponse de votre requête. Cette promesse n'échoue pas en cas d'erreur HTTP, elle n'échoue que sur les problèmes de réseau. Vous devez utiliser un gestionnaire <code>then</code> pour identifier les erreurs HTTP.</p>
<p><code>WindowOrWorkerGlobalScope</code> est aussi bien implémenté par {{domxref("Window")}} que par {{domxref("WorkerGlobalScope")}}, ce qui signifie que la méthode <code>fetch()</code> est disponible dans la plupart des cas où vous pourriez en avoir besoin.</p>
<p>Une promesse {{domxref("GlobalFetch.fetch","fetch()")}} n'est rejetée que 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 de similaire. La promesse ne sera pas rejetée en cas d'erreur HTTP (<code>404</code>, etc.) Pour cela, un gestionnaire <code>then()</code> doit vérifier que la propriété {{domxref("Response.ok")}} ait bien pour valeur <code>true</code> et/ou la valeur de la propriété {{domxref("Response.status")}}.</p>
<p>La méthode <code>fetch()</code> est contrôlée par la directive <code>connect-src</code> de l'entête <a href="/fr/docs/Web/HTTP/Headers/Content-Security-Policy">Content Security Policy</a> plutôt que par la directive de la ressource qui est récupérée.</p>
<div class="note">
<p><strong>Note :</strong> Les paramètres de la méthode <code>fetch()</code> sont identiques à ceux du contructeur d'une {{domxref("Request.Request","Request()")}}.</p>
</div>
<h2 id="Syntaxe">Syntaxe</h2>
<pre class="syntaxbox">const <em>fetchResponsePromise</em> = Promise<Response> fetch(<em>entrée</em>[, <em>init</em>]);</pre>
<h3 id="Paramètres">Paramètres</h3>
<dl>
<dt><code><em>entrée</em></code></dt>
<dd>Définit la ressource que vous voulez obtenir. Cela peut être :
<ul>
<li>Un {{domxref("USVString")}} qui contient l'URL de la ressource à obtenir. Certains navigateurs acceptent <code>blob:</code> et <code>data:</code>.</li>
<li>Un objet {{domxref("Request")}}.</li>
</ul>
</dd>
<dt><code><em>init</em></code> {{optional_inline}}</dt>
<dd>
<p>Un objet qui contient les paramètres de votre requête. Les options possibles sont :</p>
<dl>
<dt><code>method</code></dt>
<dd>La méthode de la requête, par exemple <code>GET</code> ou <code>POST</code>.</dd>
<dt><code>headers</code></dt>
<dd>Les entêtes à ajouter à votre requête, contenues dans un objet {{domxref("Headers")}} ou dans un objet avec des {{domxref("ByteString")}} pour valeurs.</dd>
<dt><code>body</code></dt>
<dd>Le corps de votre requête. Cela peut être un {{domxref("Blob")}}, un {{domxref("BufferSource")}}, un {{domxref("FormData")}}, un {{domxref("URLSearchParams")}}, ou un {{domxref("USVString")}}. Notez cependant qu'une requête avec <code>GET</code> ou <code>HEAD</code> pour méthode ne peut pas avoir de corps.</dd>
<dt><code>mode</code></dt>
<dd>Le mode à utiliser pour cette requête, par exemple <code>cors</code>, <code>no-cors</code>, ou <code>same-origin.</code></dd>
<dt><code>credentials</code></dt>
<dd>Les identifiants à utiliser pour cette requête : <code>omit</code>, <code>same-origin</code>, ou <code>include</code>. 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 {{domxref("FederatedCredential")}} ou une instance de {{domxref("PasswordCredential")}}.</dd>
<dt><code>cache</code></dt>
<dd>Le comportement du cache pour cette requête : <code>default</code>, <code>no-store</code>, <code>reload</code>, <code>no-cache</code>, <code>force-cache</code>, ou <code>only-if-cached</code>.</dd>
<dt><code>redirect</code></dt>
<dd>Le mode de redirection à adopter pour cette requête : <code>follow</code> (suivre les redirections automatiquement), <code>error</code> (abandonner avec une erreur si une redirection a lieu), ou <code>manual</code> (gérer les redirections manuellement). Dans Chrome, la valeur par défaut était <code>follow</code> avant Chrome 47, mais à partir de cette version, c'est <code>manual</code>.</dd>
<dt><code>referrer</code></dt>
<dd>Un USVString qui vaut <code>no-referrer</code>, <code>client</code>, ou qui contient une URL. La valeur par défaut est <code>client</code>.</dd>
<dt><code>referrerPolicy</code></dt>
<dd>Spécifie la valeur de l'entête HTTP referer. Cela peut être <code>no-referrer</code>, <code>no-referrer-when-downgrade</code>, <code>origin</code>, <code>origin-when-cross-origin</code> ou <code>unsafe-url</code>.</dd>
<dt><code>integrity</code></dt>
<dd>Contient la valeur de <a href="/fr/docs/Web/Security/Subresource_Integrity">l'intégrité de la sous-ressource</a> de la requête (par exemple, <code>sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=</code>).</dd>
<dt><code>keepalive</code></dt>
<dd>Peut être utilisée pour autoriser la requête à se poursuivre après la fermeture de la page. Une requête avec ce paramètre est équivalente à l'API {{domxref("Navigator.sendBeacon()")}}.</dd>
<dt><code>signal</code></dt>
<dd>Une instance de {{domxref("AbortSignal")}} vous permettant de communiquer avec une requête et de l'interrompre si vous le souhaitez via un {{domxref("AbortController")}}.</dd>
</dl>
</dd>
</dl>
<h3 id="Valeur_retournée">Valeur retournée</h3>
<p>Une {{domxref("Promise")}} qui se résoud avec un object {{domxref("Response")}}.</p>
<h3 id="Exceptions">Exceptions</h3>
<dl>
<dt><code>AbortError</code></dt>
<dd>La requête a été interrompue à cause d'un appel à la méthode {{domxref("AbortController.abort", "abort()")}} de {{domxref("AbortController")}}.</dd>
<dt><code>TypeError</code></dt>
<dd>L'URL spécifié inclut des identifiants. Ces informations devraient plutôt être fournises via l'en-tête HTTP {{HTTPHeader("Authorization")}}.</dd>
</dl>
<h2 id="Exemple">Exemple</h2>
<p>Dans notre <a href="https://github.com/mdn/fetch-examples/tree/gh-pages/fetch-request">exemple de requête avec fetch</a> (voir <a href="http://mdn.github.io/fetch-examples/fetch-request/">cet exemple en direct</a>) nous créons une nouvelle {{domxref("Request")}} avec le constructeur correspondant, puis on l'envoie en appellant <code>fetch()</code>. Comme nous récupérons une image, nous utilisons la méthode {{domxref("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 {{htmlelement("img")}}.</p>
<pre class="brush: js">const monImage = document.querySelector('img');
let maRequete = new Request('fleurs.jpg');
fetch(maRequete)
.then(function(reponse) {
if (!response.ok) {
throw new Error(`erreur HTTP! statut: ${reponse.status}`);
}
return reponse.blob();
})
.then(function(reponse) {
let URLobjet = URL.createObjectURL(reponse);
monImage.src = URLobjet;
});</pre>
<p>Dans notre <a href="https://github.com/mdn/fetch-examples/tree/gh-pages/fetch-with-init-then-request">exemple fetch avec initialisation et requête</a> (voir <a href="http://mdn.github.io/fetch-examples/fetch-with-init-then-request/">cet exemple en direct</a>) nous faisons la même chose à la différence que nous passons aussi un objet d'initalisation à la méthode <code>fetch</code> :</p>
<pre class="brush: js">const monImage = document.querySelector('img');
let mesEntetes = new Headers();
mesEntetes.append('Content-Type', 'image/jpeg');
const monInit = { method: 'GET',
headers: mesEntetes,
mode: 'cors',
cache: 'default' };
let maRequete = new Request('fleurs.jpg');
fetch(maRequete, monInit).then(function(reponse) {
...
});</pre>
<p>Notez que vous pouvez aussi passer l'objet d'initialisation au constructeur de la requête pour obtenir le même effet, par exemple :</p>
<pre class="brush: js">let maRequete = new Request('fleurs.jpg', monInit);</pre>
<p>Vous pouvez aussi utiliser un objet litéral comme en-têtes dans votre objet d'initalisation.</p>
<pre class="brush: js">const monInit = { method: 'GET',
headers: {
'Content-Type': 'image/jpeg'
},
mode: 'cors',
cache: 'default' };
let maRequete = new Request('fleurs.jpg', monInit);
</pre>
<h2 id="Spécifications">Spécifications</h2>
<table class="standard-table">
<tbody>
<tr>
<th scope="col">Specification</th>
<th scope="col">Statut</th>
<th scope="col">Commentaire</th>
</tr>
<tr>
<td>{{SpecName('Fetch','#fetch-method','fetch()')}}</td>
<td>{{Spec2('Fetch')}}</td>
<td>Définie dans un <code>WindowOrWorkerGlobalScope</code> dans la nouvelle spécification.</td>
</tr>
<tr>
<td>{{SpecName('Fetch','#dom-global-fetch','fetch()')}}</td>
<td>{{Spec2('Fetch')}}</td>
<td>Définition initiale</td>
</tr>
<tr>
<td>{{SpecName('Credential Management')}}</td>
<td>{{Spec2('Credential Management')}}</td>
<td>Ajoute la possiblité d'utiliser une instance de {{domxref("FederatedCredential")}} ou de {{domxref("PasswordCredential")}} comme valeur de <code>init.credentials</code>.</td>
</tr>
</tbody>
</table>
<h2 id="Compatibilité_des_navigateurs">Compatibilité des navigateurs</h2>
<p>{{Compat("api.WindowOrWorkerGlobalScope.fetch")}}</p>
<h2 id="Voir_aussi">Voir aussi</h2>
<ul>
<li><a href="/fr/docs/Web/API/Fetch_API">Fetch API</a></li>
<li><a href="/fr/docs/Web/API/Service_Worker_API">ServiceWorker API</a></li>
<li><a href="/fr/docs/HTTP/Access_control_CORS">HTTP access control (CORS)</a></li>
<li><a href="/fr/docs/HTTP">HTTP</a></li>
</ul>
|
