fetch()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2017.

O método global fetch() inicia o processo de busca de um recurso da rede, retornando uma promessa que é cumprida assim que a resposta estiver disponível.

A promessa é resolvida para o objeto Response que representa a resposta à sua solicitação. A promessa não rejeita erros de HTTP - apenas rejeita erros de rede. Você deve usar os manipuladores then para chechar erros de HTTP.

WindowOrWorkerGlobalScope é implementado por Window e WorkerGlobalScope, o que significa que o método fetch() está disponível em praticamente qualquer contexto no qual você queira buscar recursos.

Uma promessa fetch() só é rejeitada quando um erro de rede é encontrado (que é geralmente quando há um problema de permissão ou similar). Uma promessa fetch() não rejeita erros HTTP (404, etc.). Em vez disso, um manipulador then() deve checar as propriedades Response.ok e/ou Response.status.

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

Nota: Os parâmetros do método fetch() são idênticos aos do construtor Request().

Sintaxe

js
const fetchResponsePromise = fetch(resource [, init])

Parâmetros

resource

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

  • String ou qualquer outro objeto com um stringifier — incluindo um objeto URL — que fornece a URL do recurso que você deseja buscar.
  • Um objeto Request.
init Optional

Um objeto contendo quaisquer configurações customizadas que você deseja aplicar à solicitação. As opções possíveis são:

method

O método da requisição, por exemplo GET, POST. Observe que o cabeçalho Origin não é definido em requisições Fetch com um método de HEAD ou GET. (Este comportamento foi corrigido no Firefox 65 — consulte Erro do Firefox 1508661).

headers

Qualquer cabeçalho que você queira adicionar à sua requisição, contido dentro de um objeto Headers ou um objeto literal com valores String. Observe que alguns nomes são proibidos.

body

Qualquer corpo que você queira adicionar à sua requisição: podendo ser um Blob, BufferSource, FormData, URLSearchParams, USVString, ou um objeto ReadableStream. Note que uma requisição usando os métodos GET or 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

Controla o que os navegadores fazem com as credenciais (cookies, entradas de Autenticação HTTP, e certificados de cliente TLS). Deve ser uma das seguintes strings:

omit

Diz aos navegadores para excluir credenciais da requisição, e ignorar quaisquer credenciais enviadas de volta na resposta (por exemplo, qualquer cabeçalho Set-Cookie).

same-origin

Diz aos navegadores para incluir credenciais com requisições para URLs da mesma origem, e usar quaisquer credenciais enviadas de volta nas respostas de URLs da mesma origem.

include

Diz aos navegadores para incluir credenciais em ambas requisições same-origin e cross-origin, e sempre use as credenciais enviadas de volta nas respostas.

Nota: As credenciais podem ser incluídas em requisições cross-origin simples e "finais", mas não devem ser incluídas em requisições de comprovação de CORS.

cache

Uma string indicando como a requisição vai interagir com o cache HTTP do navegador. Os valores possíveis, default, no-store, reload, no-cache, force-cache, e only-if-cached, estão documentados no artigo para a propriedade cache do objeto Request.

redirect

Como lidar com uma resposta redirect:

  • follow: Segue os redirecionamentos automaticamente. A menos que esteja definido de outra forma, o redirecionamento é definido, por padrão, como follow.
  • error: Aborta com um erro se o redirecionamento ocorrer.
  • manual: O autor da chamada pretende processar a resposta em outro contexto. Veja WHATWG fetch standard para mais informações.
referrer

Uma USVString especificando o referenciador da requisição. Isso pode ser uma URL same-origin, about:client, ou uma string vazia.

referrerPolicy

Especifica a referrer policy para usar para a requisição. Pode ser no-referrer, no-referrer-when-downgrade, same-origin, origin, strict-origin, origin-when-cross-origin, strict-origin-when-cross-origin ou unsafe-url.

integrity

Contém o valor subresource integrity da requisição (por exemplo, sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE=).

keepalive

A opção keepalive pode ser usada para permitir que a requisição sobreviva à página. A busca com a flag keepalive é uma substituição para a API Navigator.sendBeacon().

signal

Uma instância de objeto AbortSignal; permite comunicar com uma requisição fetch e abortá-la, se desejado, por meio de um AbortController.

Valor de retorno

Uma Promise que resolve para um objeto Response.

Exceções

AbortError

A requisição foi abortada devido a uma chamada ao AbortController ou ao método abort().

TypeError

Pode ocorrer pelos seguintes motivos:

Motivo Exemplos de falha
Nome do cabeçalho inválido
// space in "C ontent-Type"
const headers = {
    "C ontent-Type": "text/xml",
    "Breaking-Bad": "<3"
};
fetch('https://example.com/', { headers });
        
Valor do cabeçalho inválido. O objeto header deve conter exatamente dois elementos.
const headers = [
    ["Content-Type", "text/html", "extra"],
    ["Accept"],
];
fetch('https://example.com/', { headers });
        
URL inválida ou esquema, ou está usando um esquema que fetch não suporta, ou está usando um esquema que não é suportado por um modo de requisição específico.
fetch('blob://example.com/', { mode: 'cors' })
        
URL que inclui credenciais
fetch('https://user:password@example.com/')
        
URL de referência inválida
fetch('https://example.com/', {
  referrer: './abc\u0000df'
})
        
Modos inválidos (navigate and websocket)
fetch('https://example.com/', { mode: 'navigate' })
        
Se o modo de cache da requisição é "only-if-cached" e o modo da requisição é diferente de "same-origin".
fetch('https://example.com/', {
  cache: 'only-if-cached',
  mode: 'no-cors'
})
        
Se o método da requisição for um token de nome inválido ou um dos cabeçalhos proibidos: CONNECT, TRACE or TRACK
fetch('https://example.com/', { method: 'CONNECT' })
        
Se o modo da requisição é "no-cors" e o método da requisição não é um método CORS-safe-listed (GET, HEAD ou POST)
fetch('https://example.com/', {
  method: 'CONNECT',
  mode: 'no-cors'
})
        
Se o método da requisição é GET ou HEAD e o corpo não for nulo(null) ou undefined.
fetch('https://example.com/', {
  method: 'GET',
  body: new FormData()
})
        
Se fetch gera um erro de rede.

Exemplos

No nosso exemplo de requisição Fetch (veja Fetch Request live) nós criamos um novo objeto Request usando um constructor relevante, depois buscamos isso usando uma chamada ao fetch(). Uma vez que estamos buscando uma imagem, executamos Response.blob() na resposta para dar a ela o tipo MIME adequado para que lidemos adequadamente handled properly, então criamos um Objeto URL disso e exibimos isso em um elemento <img>.

js
const myImage = document.querySelector("img");

let myRequest = new Request("flowers.jpg");

fetch(myRequest)
  .then(function (response) {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.blob();
  })
  .then(function (response) {
    let objectURL = URL.createObjectURL(response);
    myImage.src = objectURL;
  });

No exemplo Fetch with init then Request (veja Fetch Request init live), nós fazemos a mesma coisa exceto que passamos em um objeto init quando invocamos o fetch():

js
const myImage = document.querySelector("img");

let myHeaders = new Headers();
myHeaders.append("Accept", "image/jpeg");

const myInit = {
  method: "GET",
  headers: myHeaders,
  mode: "cors",
  cache: "default",
};

let myRequest = new Request("flowers.jpg");

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

Você também poderia passar o objeto init com o constructor Request para obter o mesmo efeito:

js
let myRequest = new Request("flowers.jpg", myInit);

Você também pode usar um object literal como headers em init.

js
const myInit = {
  method: "GET",
  headers: {
    Accept: "image/jpeg",
  },
  mode: "cors",
  cache: "default",
};

let myRequest = new Request("flowers.jpg", myInit);

Especificações

Specification
Fetch Standard
# fetch-method

Compatibilidade com navegadores

BCD tables only load in the browser

Veja também