WindowOrWorkerGlobalScope.fetch()

Il metodo fetch() del mixin WindowOrWorkerGlobalScope avvia il processo di recupero di una risorsa dalla rete. Questo ritorna una "promise" che si risolve all'oggetto Response che rappresenta la risposta alla tua richiesta.

WorkerOrGlobalScope è implementato sia da Window sia da WorkerGlobalScope, ciò significa che il metodo fetch() è disponibile in quasi tutti i contesti nei quali potresti voler recuperare risorse..

Una promise fetch() responge con un TypeError quando viene incontrato un errore di rete, sebbene questo stia spesso a significare un errore di permessi o simili. Un controllo accurato per un fetch() di successo richiederebbe di controllare che la promise si sia risolta,  e anche il controllo che la proprietà Response.ok ha valore true. Uno stato HTTP 404 non costituisce un errore di rete.

Il metodo fetch() è controllato dalla direttiva connect-src della Content Security Policy piuttosto che dalla direttiva delle risorse che sta recuperando.

Sintassi

Promise<Response> fetch(input[, init]);

Parametri

input

Definisce la risorsa ceh vuoi recuperare. Questa può essere:

• Una USVString contenente l'URL diretto della risorsa che vuoi recuperare. Alcuni browsers accettano blob: e data: come schemi.
• Un oggetto Request.

init Optional

Un oggetto opzioni contenente qualsiasi impostazione personalizzata che si vuole applicare alla richiesta. Le opzioni possibili sono:

• method: Il metodo di richiesta, es., GET, POST.
• headers: Qualsiasi header si voglia aggiungere alla richiesta, contenuto in un oggetto Headers o un oggetto letterale con valori ByteString.
• body: Qualsiasi corpo si voglia aggiungere alla richiesta: può essere un oggetto Blob, BufferSource, FormData, URLSearchParams, o USVString. Si noti che una richiesta che usa il metodo GET o HEAD non può avere un corpo.
• mode: La modalità che si vuole usare per la richiesta, es., cors, no-cors, o same-origin.
• credentials: Le credenziali che si vuole vengano usate per la richiesta: omit, same-origin, o include. Per inviare automaticamente dei cookies per il dominio corrente, questa opzione deve essere indicata. Iniziando da Chrome 50, questa proprietà accetta anche un'istanza FederatedCredential o PasswordCredential.
• cache: La modalità cache ceh si vuole usare per la richiesta: default, no-store, reload, no-cache, force-cache, o only-if-cached.
• redirect: Il metodo di reindirizzamento: follow (seguire automaticamente i reindirizzamenti), error (interrompere con un errore se avviene un reindirizzamento), o manual (gestire manualmente i reindirizzamento). In Chrome il valore di default è follow (prima di Chrome 47 era impostato a manual).
• referrer: Una USVString che specifica no-referrer, client, o una URL. Il valore predefinito è client.
• referrerPolicy: Specifica il valore dello header HTTP del referente. Può essere: no-referrer, no-referrer-when-downgrade, origin, origin-when-cross-origin, unsafe-url.
• integrity: Contiene il valore di integrità della sottorisorsa (subresource integrity) della richiesta (es., sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=).
• keepalive: L'opzione keepalive può essere usata per premettere alla richiesta di sopravvivere alla pagina. Il recupero di una risorsa con l'opzione keepalive sostituisce l'API Navigator.sendBeacon(). 
• signal: Un'istanza oggetto AbortSignal; permette di comunicare con una richiesta di recupero e di interromperla se lo si desidera con un AbortController.

Valore di ritorno

Una Promise che risolve ad un oggetto Response.

Eccezioni

Esempi

Nel nostro esempio Fetch Request (vedi Fetch Request live) viene creata un nuovo oggetto Request usando il costruttore relativo, per poi recuperarlo con una chiamata fetch(). Siccome stiamo recuperando un'immagine, eseguiamo Body.blob() alla risposta per dargli il tipo MIME adeguato in modo che venga gestito correttamente, poi creiamo un Oggetto URL dello stesso e lo mostriamo in un elemento <img>.

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

var myRequest = new Request('flowers.jpg');

fetch(myRequest).then(function(response) {
  return response.blob();
}).then(function(response) {
  var objectURL = URL.createObjectURL(response);
  myImage.src = objectURL;
});

Nel nostro esempio Fetch with init then Request (vedi Fetch Request init live) facciamo la stessa cosa eccetto che passiamo un oggetto per l'inizializzazione quando invochiamo fetch():

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

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

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

var myRequest = new Request('flowers.jpg');

fetch(myRequest,myInit).then(function(response) {
  ... 
});

Si noti che si può passare l'oggetto per l'inizializzazione insieme al costruttore Request per ottenere lo stesso effetto, es.:

var myRequest = new Request('flowers.jpg', myInit);

Si può anche usare un oggetto letterale come headers in init.

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

var myRequest = new Request('flowers.jpg', myInit);

Specificazioni

Compatibilità Browser

Vedi anche

• Fetch API
• ServiceWorker API
• HTTP access control (CORS)
• HTTP