fetch()

Sintaxe

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:

// space in "C ontent-Type"
const headers = {
    "C ontent-Type": "text/xml",
    "Breaking-Bad": "<3"
};
fetch('https://example.com/', { headers });
        

const headers = [
    ["Content-Type", "text/html", "extra"],
    ["Accept"],
];
fetch('https://example.com/', { headers });
        

fetch('blob://example.com/', { mode: 'cors' })
        

fetch('https://user:password@example.com/')
        

fetch('https://example.com/', {
  referrer: './abc\u0000df'
})
        

fetch('https://example.com/', { mode: 'navigate' })
        

fetch('https://example.com/', {
  cache: 'only-if-cached',
  mode: 'no-cors'
})
        

fetch('https://example.com/', { method: 'CONNECT' })
        

fetch('https://example.com/', {
  method: 'CONNECT',
  mode: 'no-cors'
})
        

fetch('https://example.com/', {
  method: 'GET',
  body: new FormData()
})
        

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>.

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():

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:

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

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

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

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

Especificações

Compatibilidade com navegadores

Veja também

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