WindowOrWorkerGlobalScope.fetch()

O método fetch() do mixin WindowOrWorkerGlobalScope inicia um processo de busca de um recurso da rede. Este, retorna uma promessa que resolve o objeto Response que representa a resposta a sua requisição. 

WorkerOrGlobalScope é implementado por Window e WorkerGlobalScope, o que significa que o método fetch() está disponível em praticamente qualquer contexto em que você possa querer obter recursos.

Uma promessa fetch() rejeita com um TypeError quando um erro de rede é encontrado, embora isso geralmente signifique um problema de permissões ou similar. Uma verificação precisa de um fetch() bem-sucedido incluiria a verificação de uma promessa resolvida, e depois verificando se a propriedade Response.ok possui valor true. Um status HTTP 404 não constitui um erro de rede.

O método fetch() é controlado pela diretiva connect-src da Content Security Policy em vez da diretiva dos recursos que está recuperando.

Sintaxe

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

Parâmetros

input

Isto define o recurso que você deseja buscar. Isto pode ser:

• Um USVString contendo uma URL direta para o recurso que você quer obter. Alguns navegadores aceitam blob: e data: como esquemas.
• Um objeto Request.

init Optional

Um objeto opcional que contém configurações personalizadas que você pode aplicar à requisição. As opções possíveis são:

• method: Método HTTP, por exemplo, GET, POST.
• headers: Qualquer cabeçalho que você queira adicionar à sua requisição, contido dentro de um objeto Headers ou um objeto literal com valores ByteString.
• body: Qualquer corpo que você queira adicionar à sua requisição: podendo ser um Blob, BufferSource, FormData, URLSearchParams, ou um objeto USVString. Note que uma requisição usando os métodos GET ou HEAD não pode ter um corpo.
• mode: O modo que deseja usar para a requisição, por exemplo, cors, no-cors, ou same-origin.
• credentials: A credencial que deseja usar para a requisição: omit, same-origin, ou include. Para enviar automaticamente cookies para o domínio atual, esta opção deve ser fornecida. Começando com o Chrome 50, essa propriedade também usa uma instância FederatedCredential ou uma instância PasswordCredential.
• cache: O modo de cache que deseja usar na requisição: default, no-store, reload, no-cache, force-cache, ou only-if-cached.
• redirect: O modo de redirecionamento pode usar: follow (segue automaticamente o redirecionamento), error (aborta com um erro se ocorrer um redirecionamento), ou manual (manipula redirecionamentos manualmente). No Chrome o padrão foi follow antes do Chrome 47 e manual a partir do Chrome 47.
• referrer: Um USVString especificando no-referrer, client, ou uma URL. O padrão é client.
• referrerPolicy: Especifica o valor do cabeçalho HTTP referer. Pode ser um destes: no-referrer, no-referrer-when-downgrade, origin, origin-when-cross-origin, unsafe-url.
• integrity: Contém o valor de integridade de subrecurso da requisição (por exemplo, sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=).
• signal: Uma instância do objeto FetchSignal; permite que você se comunique com um pedido de busca e controle-o através de um FetchController.
• observe: Um objeto ObserverCallback — o objetivo exclusivo deste objeto é fornecer uma função de retorno de chamada que é executada quando a solicitação fetch é executada. Isto retorna um objeto FetchObserver que pode ser usado para recuperar informações sobre o status de uma solicitação fetch.

Valor de Retorno

Uma Promise que resolve um objeto Response.

Exceptions

Example

In our Fetch Request example (see Fetch Request live) we create a new Request object using the relevant constructor, then fetch it using a fetch() call. Since we are fetching an image, we run Body.blob() on the response to give it the proper MIME type so it will be handled properly, then create an Object URL of it and display it in an <img> element.

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;
});

In our Fetch with init then Request example (see Fetch Request init live) we do the same thing except that we pass in an init object when we invoke 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) {
  ... 
});

Note that you could also pass the init object in with the Request constructor to get the same effect, e.g.:

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

You can also use an object literal as headers in init.

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

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

Specifications

Browser compatibility

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help!

[1] API is implemented behind a preference.

[2] fetch() now defined on WindowOrWorkerGlobalScope mixin.

[3] Hidden behind a preference in 55+ Nightly. In about:config, you need to create two new boolean prefs — dom.fetchObserver.enabled and dom.fetchController.enabled — and set the values of both to true.

See also

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