fetch()
=======

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` (en-US), 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` (en-US) e/ou
 `Response.status` (en-US).

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

> 
> 
> **Note:** 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 (en-US) — 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` (en-US) 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` (en-US), ou um objeto
 `ReadableStream` (en-US). 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.

> 
> **Note:** 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` (en-US) 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` (en-US) 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 (en-US)
 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()` (en-US).


`signal`

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


### 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` (en-US) ou ao método
 `abort()` (en-US).


`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()` (en-US) 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 with JavaScript enabled. Enable JavaScript to view data.

Veja também
-----------

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